CardQueryFreeSpace function

The CardQueryFreeSpace function determines the amount of available card storage space.

Syntax

DWORD WINAPI CardQueryFreeSpace(
  _In_ PCARD_DATA            pCardData,
  _In_ DWORD                 dwFlags,
  _In_ PCARD_FREE_SPACE_INFO pCardFreeSpaceInfo
);

Parameters

• pCardData [in]
  Context information for the call. For more information, see CardAcquireContext.

• dwFlags [in]
  Reserved. Set to 0.

• pCardFreeSpaceInfo [in]
  Pointer to an uninitialized CARD_FREE_SPACE_INFO structure. Card space information (such as the number of remaining bytes or the number of available key containers).

Return value

Zero on success; otherwise, nonzero.

Remarks

Free space information is returned in the following structure.

typedef struct _CARD_FREE_SPACE_INFO
{
    IN OUT DWORD  dwVersion;
    OUT DWORD  dwBytesAvailable;
    OUT DWORD  dwKeyContainersAvailable;
    OUT DWORD  dwMaxKeyContainers;
} CARD_FREE_SPACE_INFO, *PCARD_FREE_SPACE_INFO;

Sometimes these may be approximate values. Examples of the use of this information are determining if a new key container can be created and determining if the card has sufficient storage for a given certificate.

CardQueryFreeSpace should check the dwFlags value. If this is nonzero, it should fail and return SCARD_E_INVALID_PARAMETER.

Note  Important In the CARD_FREE_SPACE_INFO structure, the caller must set the dwVersion member. The following are the currently defined values.

#define CARD_FREE_SPACE_INFO_CURRENT_VERSION 1

In the CARD_FREE_SPACE_INFO structure that was discussed earlier, values that are unknown should be set to CARD_DATA_VALUE_UNKNOWN for each of the three fields that are used (dwBytesAvailable, dwKeyContainersAvailable, and/or dwMaxKeyContainers).

Requirements

Send comments about this topic to Microsoft