Share via


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