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
    [in] Handle to a socket and function pair.
  • uDesiredTuple
    [in] Specifies the desired tuple to parse. Currently, only the CISTPL_CONFIG or CISTPL_CFTABLE_ENTRY tuples are supported for parsing.
  • pBuf
    [out] Pointer to the buffer to contain the parsed tuple information. Points to the PARSED_CONFIG or the PARSED_CFTABLE structure.
  • pnItems
    [in, out] 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 not valid.
  • CERR_BAD_SOCKET
    Indicates that an hSocket socket identifier is not valid 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, only the CISTPL_CONFIG and CISTPL_CFTABLE_ENTRY tuples are supported 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.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Cardserv.h.
Link Library: Cardserv.lib.

See Also

PARSED_CFTABLE | PARSED_CONFIG | POWER_DESCR

 Last updated on Tuesday, May 18, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.