SCardTransmit function
The SCardTransmit function sends a service request to the smart card and expects to receive data back from the card.
Syntax
LONG WINAPI SCardTransmit( _In_ SCARDHANDLE hCard, _In_ LPCSCARD_IO_REQUEST pioSendPci, _In_ LPCBYTE pbSendBuffer, _In_ DWORD cbSendLength, _Inout_opt_ LPSCARD_IO_REQUEST pioRecvPci, _Out_ LPBYTE pbRecvBuffer, _Inout_ LPDWORD pcbRecvLength );
Parameters
- hCard [in]
-
A reference value returned from the SCardConnect function.
- pioSendPci [in]
-
A pointer to the protocol header structure for the instruction. This buffer is in the format of an SCARD_IO_REQUEST structure, followed by the specific protocol control information (PCI).
For the T=0, T=1, and Raw protocols, the PCI structure is constant. The smart card subsystem supplies a global T=0, T=1, or Raw PCI structure, which you can reference by using the symbols SCARD_PCI_T0, SCARD_PCI_T1, and SCARD_PCI_RAW respectively.
- pbSendBuffer [in]
-
A pointer to the actual data to be written to the card.
For T=0, the data parameters are placed into the address pointed to by pbSendBuffer according to the following structure:
struct { BYTE bCla, // the instruction class bIns, // the instruction code bP1, // parameter to the instruction bP2, // parameter to the instruction bP3; // size of I/O transfer } CmdBytes;
The data sent to the card should immediately follow the send buffer. In the special case where no data is sent to the card and no data is expected in return, bP3 is not sent.
- cbSendLength [in]
-
The length, in bytes, of the pbSendBuffer parameter.
For T=0, in the special case where no data is sent to the card and no data expected in return, this length must reflect that the bP3 member is not being sent; the length should be
sizeof(CmdBytes) - sizeof(BYTE). - pioRecvPci [in, out, optional]
-
Pointer to the protocol header structure for the instruction, followed by a buffer in which to receive any returned protocol control information (PCI) specific to the protocol in use. This parameter can be NULL if no PCI is returned.
- pbRecvBuffer [out]
-
Pointer to any data returned from the card.
For T=0, the data is immediately followed by the SW1 and SW2 status bytes. If no data is returned from the card, then this buffer will only contain the SW1 and SW2 status bytes.
- pcbRecvLength [in, out]
-
Supplies the length, in bytes, of the pbRecvBuffer parameter and receives the actual number of bytes received from the smart card. This value cannot be SCARD_AUTOALLOCATE because SCardTransmit does not support SCARD_AUTOALLOCATE.
For T=0, the receive buffer must be at least two bytes long to receive the SW1 and SW2 status bytes.
Return value
If the function successfully sends a service request to the smart card, the return value is SCARD_S_SUCCESS.
If the function fails, it returns an error code. For more information, see Smart Card Return Values.
Remarks
The SCardTransmit function is a smart card and reader access function. For information about other access functions, see Smart Card and Reader Access Functions.
For the T=0 protocol, the data received back are the SW1 and SW2 status codes, possibly preceded by response data. The following paragraphs provide information about the send and receive buffers used to transfer data and issue a command.
- Sending data to the card
-
To send n bytes of data to the card, where n>0, the send and receive buffers must be formatted as follows.
The first four bytes of the pbSendBuffer buffer contain the CLA, INS, P1, and P2 values for the T=0 operation. The fifth byte must be set to n: the size, in bytes, of the data to be transferred to the card. The next n bytes must contain the data to be sent to the card.
The cbSendLength parameter must be set to the size of the T=0 header information (CLA, INS, P1, and P2) plus a byte that contains the length of the data to be transferred (n), plus the size of data to be sent. In this example, this is n+5.
The pbRecvBuffer will receive the SW1 and SW2 status codes from the operation.
The pcbRecvLength should be at least two and will be set to two upon return.
- Retrieving data from the card
-
To receive n>0 bytes of data from the card, the send and receive buffers must be formatted as follows.
The first four bytes of the pbSendBuffer buffer contain the CLA, INS, P1, and P2 values for the T=0 operation. The fifth byte must be set to n: the size, in bytes, of the data to be transferred from the card. If 256 bytes are to be transferred from the card, then this byte must be set to zero.
The cbSendLength parameter must be set to five, the size of the T=0 header information.
The pbRecvBuffer will receive the data returned from the card, immediately followed by the SW1 and SW2 status codes from the operation.
The pcbRecvLength should be at least n+2 and will be set to n+2 upon return.
- Issuing a command without exchanging data
-
To issue a command to the card that does not involve the exchange of data (either sent or received), the send and receive buffers must be formatted as follows.
The pbSendBuffer buffer must contain the CLA, INS, P1, and P2 values for the T=0 operation. The P3 value is not sent. (This is to differentiate the header from the case where 256 bytes are expected to be returned.)
The cbSendLength parameter must be set to four, the size of the T=0 header information (CLA, INS, P1, and P2).
The pbRecvBuffer will receive the SW1 and SW2 status codes from the operation.
The pcbRecvLength should be at least two and will be set to two upon return.
Examples
The following example shows sending a service request to the smart card.
// Transmit the request. // lReturn is of type LONG. // hCardHandle was set by a previous call to SCardConnect. // pbSend points to the buffer of bytes to send. // dwSend is the DWORD value for the number of bytes to send. // pbRecv points to the buffer for returned bytes. // dwRecv is the DWORD value for the number of returned bytes. lReturn = SCardTransmit(hCardHandle, SCARD_PCI_T0, pbSend, dwSend, NULL, pbRecv, &dwRecv ); if ( SCARD_S_SUCCESS != lReturn ) { printf("Failed SCardTransmit\n"); exit(1); // or other appropriate error action }
Requirements
|
Minimum supported client |
Windows XP [desktop apps only] |
|---|---|
|
Minimum supported server |
Windows Server 2003 [desktop apps only] |
|
Header |
|
|
Library |
|
|
DLL |
|
See also