source: svn/trunk/newcon3bcm2_21bu/dta/src/settop_api/bsettop_smartcard.h

/***************************************************************************
 *     Copyright (c) 2009-2010, Broadcom Corporation
 *     All Rights Reserved
 *     Confidential Property of Broadcom Corporation
 *
 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
 *
 * $brcm_Workfile:  $
 * $brcm_Revision:  $
 * $brcm_Date:  $
 *
 * Module Description:
 *
 * Revision History:
 *
 * $brcm_Log:  $
 *
 ***************************************************************************/
#ifndef BSETTOP_SMARTCARD_H__
#define BSETTOP_SMARTCARD_H__

#include "bsettop_types.h"

#ifdef __cplusplus
extern "C"
{
#endif

/*=*************************
Smartcard (bsmartcard_t) supports a read/write interface to the smartcard along with
reset functions.

Asynchronous I/O is not supported yet.
****************************/

/*
Summary:
        Smartcard handle returned by bsmartcard_open.
*/
typedef struct bsmartcard *bsmartcard_t;

/*
Summary:
        Smartcard protocol enum definition.
*/
typedef enum bsmartcard_protocol {
        bsmartcard_protocol_unknown,
        bsmartcard_protocol_t0,
        bsmartcard_protocol_t1,
        bsmartcard_protocol_t14
} bsmartcard_protocol;

/*
Summary:
        Smartcard standard enum definition.
*/
typedef enum bsmartcard_standard {
        bsmartcard_standard_nds,
        bsmartcard_standard_iso,
        bsmartcard_standard_emv2000,
        bsmartcard_standard_irdeto
} bsmartcard_standard;

/*
Summary:
        Smartcard settings structure.
Description:
        Smartcard settings structure, used by bsmartcard_open.  
This allows protocol (T=0, T=1, T=14) and standard (NDS, ISO, EMV2000, IRDETO) to be selected.
*/
typedef struct bsmartcard_settings {
        bsmartcard_protocol protocol;
        bsmartcard_standard standard;
        void *callback_context;         /* Context pointer, returned in the callback functions */
        void (*card_insertion)(void *context); /* Called when a card is inserted */
        void (*card_removal)(void *context); /* Called when a card is removed */
} bsmartcard_settings_t;

/*
Summary:
        Smartcard setting structure initialization.
Description:
        This function initializes the smartcard settings structure to defaults.
*/
void bsmartcard_settings_init(
        bsmartcard_settings_t *settings
);

/*
Summary:
        Open a smart object which corresponds to one smartcard reader.
Description:
*/
bsmartcard_t bsmartcard_open(
        bobject_t smartcard_id, /* smartcard object id */
        bsmartcard_t *smartcard,
        const bsmartcard_settings_t *settings /* smartcard settings */
);

/*
Summary:
        Close a smartcard object.
Description:
        After closing, the bsmartcard_t handle is invalid.
*/
void bsmartcard_close(
        bsmartcard_t smartcard /* handle returned by bsmartcard_open */
);

/*
Summary:
        Read data from the smartcard.

Description:
        If you don't call bsmartcard_set_async, this function will block until it can return
        some data or returns an error.

        If you call bsmartcard_set_async, this function will never block and will return
        either some data, no data or an error.

        If read fails, you should call bsmartcard_get_status in order to determine
        the state of the smartcard interface.
*/
bresult bsmartcard_read(
        bsmartcard_t smartcard, /* handle returned by bsmartcard_open */
        void *data,                             /* [out,size_is(length)] memory to read into */
        size_t length,                  /* maximum number of bytes to read */
        size_t *length_read             /* [out] amount of data read into memory */
);

/*
Summary:
        Write data to the smartcard.

Description:
        If you don't call bsmartcard_set_async, this function will block until it can write
        some data or returns an error.

        If you call bsmartcard_set_async, this function will never block and will write
        some data or return an error.

        If write fails, you should call bsmartcard_get_status in order to determine
        the state of the smartcard interface.
*/
bresult bsmartcard_write(
        bsmartcard_t smartcard, /* handle returned by bsmartcard_open */
        const void *data,               /* [size_is(length)] memory to write from */
        size_t length,                  /* maximum number of bytes to write */
        size_t *length_written  /* [out] amount of data written */
);

/* TODO: need async notification of status change using bsettop_event */

/*
Summary:
        Smartcard error status enum.
*/
typedef enum bsmartcard_error {
        bsmartcard_no_error,
        bsmartcard_err_rx_parity,
        bsmartcard_err_tx_parity,
        bsmartcard_err_rx_timeout,
        bsmartcard_err_tx_timeout,
        bsmartcard_err_hardware_failure,
        bsmartcard_err_reset_terminal /* requires a call to bsmartcard_reset() */
} bsmartcard_error;

/*
Summary:
        Smartcard state enum.
Description:
        This represents the current state of the given slot and card.
*/
typedef enum bsmartcard_state {
        bsmartcard_state_unknown = 0, /* Unknown state (perhaps not yet initialized).  Persistent. */
        bsmartcard_state_cold_resetting, /* A cold reset has been requested but is not yet complete.  Transient. */
        bsmartcard_state_warm_resetting, /* A warm reset has been requested but is not yet complete.  Transient. */
        bsmartcard_state_reset_done, /* The slot/card reset has completed.  Persistent. */
        bsmartcard_state_activating, /* The slot/card is currently being activated, but activation is not yet complete.  Transient. */
        bsmartcard_state_receive_decode_atr, /* The ATR is being received or decoded.  Transient. */
        bsmartcard_state_ready, /* The slot/card is initialized and is awaiting sends/receives.  Persistent. */
        bsmartcard_state_transmitting, /* The slot/card is currently transmitting.  Transient. */
        bsmartcard_state_transmitted, /* The slot/card has completed its transmission.  Persistent. */
        bsmartcard_state_receiving, /* The slot/card is currently receiving.  Transient. */
        bsmartcard_state_ignore, /* The slot/card is ignoring events/commands.  Persistent. */
        bsmartcard_state_initialized, /* The slot/card has been initialized, but the ATR has not yet been received.  Persistent. */
        bsmartcard_state_max_state /* A value indicating the total number of possible states.  The state returned from bsmartcard_get_status should never exceed this value. */
} bsmartcard_state;
/*
Summary:
        Status information returned by bsmartcard_get_status.
*/
typedef struct bsmartcard_status {
        bool card_present;
        bsmartcard_error err;
        bsmartcard_state state;
} bsmartcard_status;

/*
Summary:
Get the status of the smartcard interface.
Description:
This function must be called after read or write fails in order to determine the
state of the smartcard interface.
*/
bresult bsmartcard_get_status(
        bsmartcard_t smartcard,
        bsmartcard_status *status               /* [out] Fills in the status information. */
);

/*
Summary:
        Reset a smartcard.
Description:
        Reset the smartcard itself.
*/
bresult bsmartcard_reset_card(
        bsmartcard_t smartcard, /* handle returned by bsmartcard_open */
        void *data,                             /* [out,size_is(length)] pointer to memory that can be read into */
        size_t length,                  /* maximum number of bytes pointed to by data */
        size_t *length_read             /* [out] length of data read into the data field. */
);

/*
Summary:
        Reset the smartcard interface.
Description:
        Reprogram all the Broadcom smartcard interface, not the card.
        If you want to reset the card, use bsmartcard_reset_card.

        The interface must be reset whenever a card is inserted.
*/
bresult bsmartcard_reset(
        bsmartcard_t smartcard, /* handle returned by bsmartcard_open */
        bool warm_reset /* true for a warm reset, false for a cold reset */
);


/*
Summary:
        Detect the card insertion.
Description:
        The function will be blocked until the card is inserted.
*/
bresult bsmartcard_detect_card( /* name changed: was bsmartcard_detectCardPres */
                bsmartcard_t smartcard
);

/*
Summary:
        Set the interface paramenters after interpreting ATR data.
Description:
        The function set the interface paramenters after interpreting ATR data.
*/
bresult bsmartcard_set_params_from_atr( /* name changed: was bsmartcard_SetParameters */
                bsmartcard_t smartcard
);


/*
Summary:
        Smartcard initialization.
Description:
        The function initializes the smartcard module.
*/
bresult bsmartcard_init(void);

/*
Summary:
        Smartcard shutdown.
Description:
        The function shutdowns the smartcard module.
*/

void bsmartcard_shutdown(void);


#ifdef __cplusplus
}
#endif


#endif /* BSETTOP_SMARTCARD_H__ */