// COPYRIGHT_BEGIN
// DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
//
// Copyright (C) 2008-2013, Cable Television Laboratories, Inc.
//
// This software is available under multiple licenses:
//
// (1) BSD 2-clause
// Redistribution and use in source and binary forms, with or without modification, are
// permitted provided that the following conditions are met:
// ·Redistributions of source code must retain the above copyright notice, this list
// of conditions and the following disclaimer.
// ·Redistributions in binary form must reproduce the above copyright notice, this list of conditions
// and the following disclaimer in the documentation and/or other materials provided with the
// distribution.
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
// TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
// PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
// THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// (2) GPL Version 2
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, version 2. This program is distributed
// in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
// even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
// PURPOSE. See the GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License along
// with this program.If not, see.
//
// (3)CableLabs License
// If you or the company you represent has a separate agreement with CableLabs
// concerning the use of this code, your rights and obligations with respect
// to this code shall be as set forth therein. No license is granted hereunder
// for any other purpose.
//
// Please contact CableLabs if you need additional information or
// have any questions.
//
// CableLabs
// 858 Coal Creek Cir
// Louisville, CO 80027-9750
// 303 661-9100
// COPYRIGHT_END
/*
* The MPE OS POD API. This API provides a consistent interface to POD functionality
* regardless of the underlying operating system.
*
* @author Todd Earles - Vidiom Systems Corporation
*/
#ifndef _MPEOS_POD_H_
#define _MPEOS_POD_H_
#ifdef __cplusplus
extern "C"
{
#endif
#include
#include
#include
#define MAX_UDP_DATAGRAM_SIZE (4 * 1024)
/****************************************************************************************
*
* TYPE AND STRUCTURE DEFINITIONS
*
***************************************************************************************/
/****************************************************************************************
*
* POD FUNCTIONS
*
***************************************************************************************/
/**
* mpeos_podInit()
*
* Perform any target specific operations to enable interfacing with the POD
* device via the target HOST-POD devices stack interface. Depending on the platform
* implementation this may include stack API call(s) to get the HOST-POD stack resources
* initialized, or it may simply involve stack API calls(s) to access the data
* already exchanged between the HOST and POD during the initial platform bootstrap
* process.
*
* @param podDB is a pointer to the MPE layer platform-independent POD information
* database used to cache the POD-Host information.
*
* @return MPE_SUCCESS if the initialization process was successful.
*/
mpe_Error mpeos_podInit(mpe_PODDatabase *podDB);
/**
* mpeos_podRegister()
*
* Handles registration for pod-specific asynchronous events. The platform-specific
* layer is responsible for notifying the stack of asynchronous changes to the POD
* generic features list or app info. An asynchronous completion token and
* queueID are provided to the native layer to facilitate this communication.
*
* For efficiency reasons there is only one queue between MPEOS and higher levels, so registering queue B when queue A is
* still active is invalid and a MPE_EINVAL failure should be returned.
*
* These events are defined in mpe_PodEvent. At this time the MPEOS is only required to send the following asynchronous events:
*
* MPE_POD_EVENT_GF_UPDATE
* MPE_POD_EVENT_APPINFO_UPDATE
* MPE_POD_EVENT_INSERTED
* MPE_POD_EVENT_READY
* MPE_POD_EVENT_REMOVED
* MPE_POD_EVENT_RECV_APDU
*
* Other events may be defined in mpe_podEvent, but in the default MPE/MPEOS implementation those events are generated at the MPE layer.
*
* @param queueId is the event queue ID to which POD events should be sent
* @param data is the EdHandle if needed (comm with JNI) or private queue data.
*
* @return MPE_SUCCESS if the registration process was successful. Returns MPE_EINVAL if the previous queue has not been unregistered
* or if one of the parameters is otherwise invalid.
*
*/
mpe_Error mpeos_podRegister(mpe_EventQueue queueId, void* data);
/**
* mpeos_podUnregister()
*
* Removes any previous event handler for pod-specific asynchronous events
*
* @return MPE_SUCCESS if the unregistration process was successful.
*/
mpe_Error mpeos_podUnregister(void);
/**
* mpeos_podGetFeatures
*
* Get the POD's generic features list.
*
* @param podDB is a pointer to the MPE layer platform-independent POD information
* database used to cache the POD-Host information.
*
* @return MPE_SUCCESS if the features list was successfully acquired.
*/
mpe_Error mpeos_podGetFeatures(mpe_PODDatabase *podDB);
/**
* mpeos_podGetFeatureParam
*
* Populate the internal POD database with the specified feature parameter value.
*
* @param featureId is the identifier of the feature parameter of interest.
*
* @return MPE_SUCCESS if the value of the feature was acquired successfully.
*/
mpe_Error mpeos_podGetFeatureParam(mpe_PODDatabase *podDBPtr,
uint32_t featureId);
/**
* mpeos_podSetFeatureParam
*
* Perform actual Generic Feature parameter set operation to POD-HOST interface.
* If the POD accepts the proposed change in value, return TRUE to call to indicate
* successful set operation.
*
* @param featureId is the generic feature parameter to set
* @param param is a pointer to the value of the generic feature
* @param size is the size in bytes of the parameter value
*
* @return TRUE if the values was accepted by the POD.
*/
mpe_Error mpeos_podSetFeatureParam(uint32_t featureId, uint8_t *param,
uint32_t size);
/**
* The mpeos_podCASConnect() function shall establish a connection between a private
* Host application and the POD Conditional Access Support (CAS) resource. It is the MPEOS call's responsibility
* determine the correct resource ID based upon whether the card is M or S mode.
*
* @param sessionId points to a location where the session ID can be returned. The session
* ID is implementation dependent and represents the CAS session to the POD application.
* @param version a pointer to the location where the implementation will store the supported
* version of the Conditional Access Support resource
*
* @return Upon successful completion, this function shall return MPE_SUCCESS. Otherwise,
* one of the errors below is returned.
*

*

MPE_ENOMEM - There was insufficient memory available to complete the operation.
*

MPE_EINVAL - One or more parameters were out of range or unusable.
*

*/
mpe_Error mpeos_podCASConnect(uint32_t *sessionId, uint16_t *version);
/**
* The mpeos_podCASClose() function provides an optional API for systems that may
* require additional work to maintain session resources when an application unregisters
* its handler from POD. The implementation of this function may
* need to: 1) update internal implementation resources, 2) make an OS API call to
* allow the OS to update session related resources or 3) do nothing since it's
* entirely possible that the sessions can be maintained as "connected" upon
* deregistration and simply reused if the same host or another host application makes a
* later request to connect to the CAS application.
*
* @param sessionId the session identifier of the target CAS session.
*
* @return Upon successful completion, this function shall return MPE_SUCCESS. Otherwise,
* one of the errors below is returned.
*

*

MPE_EINVAL - One or more parameters were out of range or unusable.
*

*/
mpe_Error mpeos_podCASClose(uint32_t sessionId);
/**
* The mpeos_podSASConnect() function shall establish a connection between a private
* Host application and the corresponding POD Module vendor-specific application.
*
* @param appId specifies a unique identifier of the private Host application.
* @param sessionId points to a location where the session ID can be returned. The session
* ID is implementation dependent and represents the SAS session to the POD application.
* @param version a pointer to the location where the implementation will store the supported
* version of the Conditional Access Support resource
* @return Upon successful completion, this function shall return MPE_SUCCESS. Otherwise,
* one of the errors below is returned.
*

*

MPE_ENOMEM - There was insufficient memory available to complete the operation.
*

MPE_EINVAL - One or more parameters were out of range or unusable.
*

*/
mpe_Error mpeos_podSASConnect(uint8_t *appId, uint32_t *sessionId, uint16_t *version);
/**
* The mpeos_podSASClose() function provides an optional API for systems that may
* require additional work to maintain session resources when an application unregisters
* its handler from an SAS application. The implementation of this function may
* need to: 1) update internal implementation resouces, 2) make an OS API call to
* allow the OS to update session related resources or 3) do nothing since it's
* entirely possible that the sessions can be maintained as "connected" upon
* deregistration and simply reused if the same host or another host application makes a
* later request to connect to the SAS application.
*
* @param sessionId the session identifier of the target SAS session.
*
* @return Upon successful completion, this function shall return MPE_SUCCESS. Otherwise,
* one of the errors below is returned.
*

*

MPE_EINVAL - One or more parameters were out of range or unusable.
*

*/
mpe_Error mpeos_podSASClose(uint32_t sessionId);
/**
* The mpeos_podMMIConnect() function shall establish a connection with the MMI
* resource on the POD device.
*
* @param sessionId the session identifier of the target MMI session.
* @param version a pointer to the location where the implementation will store the supported
* version of the Man-Machine Interface resource
*
* @return Upon successful completion, this function shall return MPE_SUCCESS. Otherwise,
* one of the errors below is returned.
*

*

MPE_ENOMEM - There was insufficient memory available to complete the operation.
*

MPE_EINVAL - One or more parameters were out of range or unusable.
*

*/
mpe_Error mpeos_podMMIConnect(uint32_t *sessionId, uint16_t *version);
/**
* The mpeos_podMMIClose() function provides an optional API for systems that may
* require additional work to maintain MMI resources when an application unregisters
* its MMI handler from the MMI POD application. The implementation of this function may
* need to: 1) update internal implementation resouces, 2) make an OS API call to
* allow the OS to update MMI session related resources or 3) do nothing since it's
* entirely possible that the MMI sessions can be maintained as "connected" upon
* deregistration.
*
* @return Upon successful completion, this function shall return MPE_SUCCESS. Otherwise,
* one of the errors below is returned.
*

*

MPE_EINVAL - One or more parameters were out of range or unusable.
*

*/
mpe_Error mpeos_podMMIClose(void);
/**
* The mpeos_podAIConnect() function shall establish a connection with the
* Application Information resource on the POD device.
*
* @param sessionId the session identifier of the target application information session.
* @param version a pointer to the location where the implementation will store the supported
* version of the Application Information resource
*
* @return Upon successful completion, this function shall return MPE_SUCCESS. Otherwise,
* one of the errors below is returned.
*

*

MPE_ENOMEM - There was insufficient memory available to complete the operation.
*

MPE_EINVAL - One or more parameters were out of range or unusable.
*

*/
mpe_Error mpeos_podAIConnect(uint32_t *sessionId, uint16_t *version);
/**
* The mpeos_podReceiveAPDU() function retrieves the next available APDU from the POD.
* This function also will receive "copy" APDU's that failed to be sent to the POD so that
* the APDU can be returned to the original sender to be notified of the failure.
*
* This API utilizes the definition of an APDU as defined by CCIF:
*
* APDU() {
* apdu_tag 24 uimsbf
* length_field()
* for (i=0; i
*

MPE_SUCCESS - The APDU was successfully retrieved, the associated session
* ID was copied to *sessionId, a pointer to the buffer
* was stored in *apdu, and the length of the buffer copied to *len
*

MPE_ENOMEM - There was insufficient memory available to complete the operation.
*