CardGetParsedTuple

The CardGetParsedTuple function reads and parses the specified tuple.

Syntax

STATUS CardGetParsedTuple( CARD_SOCKET_HANDLE hSocket
UINT8 uDesiredTuple PVOID pBuf PUINT32 pnItems );

Parameters

hSocket: Specifies a handle to a socket and function pair.
uDesiredTuple: Specifies the desired tuple to parse. Currently, only the CISTPL_CONFIG or CISTPL_CFTABLE_ENTRY tuples are supported for parsing.
pBuf: Points to the buffer to contain the parsed tuple information. Points to the PARSED_CONFIG or PARSED_CFTABLE structure.
pnItems: On entry, pnItems points to the number of entries in the buffer pointed to by pBuf. On exit, pnItems specifies how many entries of pBuf were used, or how many entries are required if the buffer was not large enough.

Return Value

If the function succeeds, the return value is CERR_SUCCESS; otherwise, it is one of the following values:

Value	Description
CERR_BAD_ARG_LENGTH	Indicates the buffer specified by the pnItems pointer is not large enough.
CERR_BAD_ARGS	Indicates an invalid pBuf pointer.
CERR_BAD_SOCKET	Indicates an invalid hSocket socket identifier or a PC Card not inserted.
CERR_NO_MORE_ITEMS	Indicates the end of CIS reached or the requested tuple not found.
CERR_OUT_OF_RESOURCE	Indicates Card Services is unable to set up a memory window to read the CIS.
CERR_READ_FAILURE	Indicates that no PC Card is inserted, or that the PC Card is unreadable.

Remarks

This function reads the CIS data from the specified PC Card of the specified tuple code and formats the encoded data into an easily accessed structure. CardGetParsedTuple reduces code size by eliminating extra processing required to parse some variable length tuples, thereby letting drivers forego duplicating code to process these tuples.

Currently, only the CISTPL_CONFIG and CISTPL_CFTABLE_ENTRY tuples are supported for parsing.

When CardGetParsedTuple is called with CISTPL_CONFIG, it retrieves a PARSED_CONFIG structure. When it is called with CISTPL_CFTABLE_ENTRY, it retrieves a PARSED_CFTABLE structure. Accordingly, the pBuf pointer points to either the PARSED_CONFIG or the PARSED_CFTABLE structure.

If there are multiple CISTPL_CFTABLE_ENTRY tuples, CardGetParsedTuple retrieves the required number of PARSED_CFTABLE structures, provided the user's buffer is large enough.