CardGetParsedTuple

This function reads and decodes the CISTPL_CONFIG and CISTPL_CFTABLE_ENTRY tuples. These tuples are both complex and difficult to decode; this function stores the information in those tuples in data structures that are easier to access.

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: Pointer to the buffer to contain the parsed tuple information. Points to the PARSED_CONFIG or the PARSED_CFTABLE structure.
pnItems: Pointer, on entry, to the number of entries in the buffer pointed to by pBuf. On exit, pnItems specifies how many entries of pBuf are needed to store the results or how many entries are required if the buffer is not large enough.

Return Values

CERR_SUCCESS indicates success. One of the following values indicates failure:

CERR_BAD_ARG_LENGTH: Indicates that the buffer specified by the pnItems pointer is not large enough.
CERR_BAD_ARGS: Indicates that the pointer specified by pBuf is invalid.
CERR_BAD_SOCKET: Indicates that an hSocket socket identifier is invalid or that a PC Card is not inserted.
CERR_NO_MORE_ITEMS: Indicates that the end of CIS is reached or that the requested tuple is not found.
CERR_OUT_OF_RESOURCE: Indicates that 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, thus duplication of code to process these tuples.

Currently, Windows CE supports only the CISTPL_CONFIG and CISTPL_CFTABLE_ENTRY tuples for parsing.

When this function 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. Therefore, the pBuf pointer points to either PARSED_CONFIG or PARSED_CFTABLE.

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

Driver Name

PCMCIA