globalplatform/connection.h File Reference

#include <stdio.h>
#include <PCSC/winscard.h>
#include "types.h"
#include "library.h"
#include "security.h"
#include "error.h"

Go to the source code of this file.

Classes
struct	OPGP_CONNECTION_FUNCTIONS
struct	OPGP_CARD_CONTEXT
struct	OPGP_CARD_INFO
Defines
#define	MAX_ATR_SIZE 32
	Maximum ATR size.
#define	OPGP_TRACE_MODE_ENABLE 1
	Switch trace mode on.
#define	OPGP_TRACE_MODE_DISABLE 0
	Switch trace mode off.
#define	OPGP_CARD_PROTOCOL_T0 SCARD_PROTOCOL_T0
	Transport protocol T=0.
#define	OPGP_CARD_PROTOCOL_T1 SCARD_PROTOCOL_T1
	Transport protocol T=1.
Functions
OPGP_API void	OPGP_enable_trace_mode (DWORD enable, FILE *out)
	Enables the trace mode.
OPGP_API OPGP_ERROR_STATUS	OPGP_establish_context (OPGP_CARD_CONTEXT *cardContext)
	This function establishes a context to connection layer.
OPGP_API OPGP_ERROR_STATUS	OPGP_release_context (OPGP_CARD_CONTEXT *cardContext)
	This function releases the context to the connection layer established by OPGP_establish_context().
OPGP_API OPGP_ERROR_STATUS	OPGP_list_readers (OPGP_CARD_CONTEXT cardContext, OPGP_STRING readerNames, PDWORD readerNamesLength)
	This function returns a list of currently available readers.
OPGP_API OPGP_ERROR_STATUS	OPGP_card_connect (OPGP_CARD_CONTEXT cardContext, OPGP_CSTRING readerName, OPGP_CARD_INFO *cardInfo, DWORD protocol)
	This function connects to a reader.
OPGP_API OPGP_ERROR_STATUS	OPGP_card_disconnect (OPGP_CARD_CONTEXT cardContext, OPGP_CARD_INFO *cardInfo)
	This function disconnects a reader.
OPGP_API OPGP_ERROR_STATUS	OPGP_send_APDU (OPGP_CARD_CONTEXT cardContext, OPGP_CARD_INFO cardInfo, GP211_SECURITY_INFO *secInfo, PBYTE capdu, DWORD capduLength, PBYTE rapdu, PDWORD rapduLength)
	This function sends an APDU.

Detailed Description

This file contains all connection related functions. The real functionality is implemented by plugins.

Define Documentation

#define MAX_ATR_SIZE 32

Maximum ATR size.

#define OPGP_CARD_PROTOCOL_T0 SCARD_PROTOCOL_T0

Transport protocol T=0.

#define OPGP_CARD_PROTOCOL_T1 SCARD_PROTOCOL_T1

Transport protocol T=1.

#define OPGP_TRACE_MODE_DISABLE 0

Switch trace mode off.

#define OPGP_TRACE_MODE_ENABLE 1

Switch trace mode on.

Function Documentation

OPGP_API OPGP_ERROR_STATUS OPGP_card_connect	(	OPGP_CARD_CONTEXT	cardContext,
		OPGP_CSTRING	readerName,
		OPGP_CARD_INFO *	cardInfo,
		DWORD	protocol
	)

This function connects to a reader.

OPGP_card_disconnect MUST be called to release allocated resources. If something is not working, you may want to change the protocol type.

Parameters:

	cardContext	[in] The valid OPGP_CARD_CONTEXT returned by establish_context()
	readerName	[in] The name of the reader to connect.
	*cardInfo	[out] The returned OPGP_CARD_INFO.
	protocol	[in] The transmit protocol type to use. Can be OPGP_CARD_PROTOCOL_T0 or OPGP_CARD_PROTOCOL_T1 or both ORed.

Returns:: OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

OPGP_API OPGP_ERROR_STATUS OPGP_card_disconnect	(	OPGP_CARD_CONTEXT	cardContext,
		OPGP_CARD_INFO *	cardInfo
	)

This function disconnects a reader.

Parameters:

	cardContext	[in] The valid OPGP_CARD_CONTEXT returned by establish_context()
	cardInfo	[in, out] The OPGP_CARD_INFO structure returned by card_connect().

Returns:: OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

<same here

OPGP_API void OPGP_enable_trace_mode	(	DWORD	enable,
		FILE *	out
	)

Enables the trace mode.

Parameters:

enable

[in] Enables or disables the trace mode.

*out

[out] The pointer to to FILE to print result.

OPGP_API OPGP_ERROR_STATUS OPGP_establish_context ( OPGP_CARD_CONTEXT * cardContext )

This function establishes a context to connection layer.

OPGP_release_context MUST be called to release allocated resources.

Parameters:

cardContext

[out] The returned OPGP_CARD_CONTEXT.

Returns:: OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

OPGP_API OPGP_ERROR_STATUS OPGP_list_readers	(	OPGP_CARD_CONTEXT	cardContext,
		OPGP_STRING	readerNames,
		PDWORD	readerNamesLength
	)

This function returns a list of currently available readers.

Parameters:

	cardContext	[in] The valid OPGP_CARD_CONTEXT returned by establish_context()
	readerNames	[out] The reader names will be a multi-string and separated by a NULL character and ended by a double NULL. (ReaderA\0ReaderB\0\0). If this value is NULL, list_readers ignores the buffer length supplied in readerNamesLength, writes the length of the multi-string that would have been returned if this parameter had not been NULL to readerNamesLength.
	readerNamesLength	[in, out] The length of the multi-string including all trailing null characters.

Returns:: OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

OPGP_API OPGP_ERROR_STATUS OPGP_release_context ( OPGP_CARD_CONTEXT * cardContext )

This function releases the context to the connection layer established by OPGP_establish_context().

Parameters:

cardContext

[in, out] The valid OPGP_CARD_CONTEXT returned by establish_context()

Returns:: OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

OPGP_API OPGP_ERROR_STATUS OPGP_send_APDU	(	OPGP_CARD_CONTEXT	cardContext,
		OPGP_CARD_INFO	cardInfo,
		GP211_SECURITY_INFO *	secInfo,
		PBYTE	capdu,
		DWORD	capduLength,
		PBYTE	rapdu,
		PDWORD	rapduLength
	)

This function sends an APDU.

If the transmission is successful then the APDU status word is returned as errorCode in the OPGP_ERROR_STATUS structure.

Parameters:

	cardContext	[in] The valid OPGP_CARD_CONTEXT returned by OPGP_establish_context()
	cardInfo	[in] The OPGP_CARD_INFO structure returned by OPGP_card_connect().
	*secInfo	[in, out] The pointer to the GP211_SECURITY_INFO structure returned by GP211_mutual_authentication().
	capdu	[in] The command APDU.
	capduLength	[in] The length of the command APDU.
	rapdu	[out] The response APDU.
	rapduLength	[in, out] The length of the the response APDU.

Returns:: OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

globalplatform/connection.h File Reference

Classes

Defines

Functions

Detailed Description

Define Documentation

Function Documentation