CardGetParsedTuple

  • Article

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.

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

Parameters

  • hSocket
    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, this parameter 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. This function 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

Requirements

Runs on Versions Defined in Include Link to
Windows CE OS 1.0 and later      

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

PARSED_CFTABLE, PARSED_CONFIG, POWER_DESCR

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.