CardQueryFreeSpace function

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


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


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.


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;

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.


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).


Target platform



Cardmod.h (include Cardmod.h)



Send comments about this topic to Microsoft