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

Target platform

Desktop

Header

Cardmod.h (include Cardmod.h)

 

 

Send comments about this topic to Microsoft

Show: