/***************************************************************************
 *     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__ */