CardSetProperty function

  • Article

The CardSetProperty function is used to set properties on the card.

Syntax

DWORD WINAPI CardSetProperty(
  _In_ PCARD_DATA pCardData,
  _In_ LPWSTR     wszProperty,
  _In_ PBYTE      pbData,
  _In_ DWORD      cbDataLen,
  _In_ DWORD      dwFlags
);

Parameters

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

  • wszProperty [in]
    The name of the property to set.

  • pbData [in]
    Byte pointer to data buffer that contains the data.

  • cbDataLen [in]
    The length of the data buffer at pbData.

  • dwFlags [in]
    Flags for the operation.

Return value

Zero on success; nonzero on failure.

Remarks

For read-only cards, setting properties through CardSetProperty is optional.

CardSetProperty should check the dwFlags value. Unless dwFlags is specified for the property and the value is nonzero, it should fail and return SCARD_E_INVALID_PARAMETER.

If an unsupported wszProperty is passed to CardSetProperty, it should fail and return SCARD_E_UNSUPPORTED_FEATURE. Any minidriver can choose to define and support optional custom properties that are not defined in this specification.

The format of pbData is different depending on the wszProperty parameter that is passed to the function. For a list of the different types that pbData takes depending on wszProperty, see CardGetProperty.

The following properties are read-only and are not supported by the CardSetProperty function:

  • CP_CARD_FREE_SPACE
  • CP_CARD_CAPABILITIES
  • CP_CARD_KEYSIZES
  • CP_CARD_LIST_PINS
  • CP_CARD_AUTHENTICATED_STATE
  • CP_KEY_IMPORT_SUPPORT
  • CP_ENUM_ALGORITHMS
  • CP_PADDING_SCHEMES
  • CP_CHAINING_MODES

CardSetProperty must return SCARD_E_UNSUPPORTED_FEATURE or SCARD_W_SECURITY_VIOLATION for the read-only properties on the preceding functions.

CardSetProperty must return SCARD_E_UNSUPPORTED_FEATURE or SCARD_W_SECURITY_VIOLATION for read-only cards for the following properties:

  • CP_CARD_CACHE_MODE
  • CP_SUPPORTS_WIN_X509_ENROLLMENT
  • CP_CARD_GUID
  • CP_CARD_SERIAL_NO
  • CP_CARD_PIN_INFO
  • CP_PARENT_WINDOW
  • CP_PIN_CONTEXT_STRING
  • CP_CARD_PIN_STRENGTH_VERIFY
  • CP_CARD_PIN_STRENGTH_CHANGE
  • CP_CARD_PIN_STRENGTH_UNBLOCK

CP_CARD_READ_ONLY is writable if the appropriate level of authentication to the card is successful. SCARD_W_SECURITY_VIOLATION should be returned if it is supported. However, the appropriate principal (ROLE_ADMIN) is not authenticated.

wszProperty pbData Permission

CP_CARD_CACHE_MODE

In this situation pbData is a DWORD value. Three flags indicate which cache mode to use:

#define CP_CACHE_MODE_GLOBAL_CACHE   1
#define CP_CACHE_MODE_SESSION_ONLY   2
#define CP_CACHE_MODE_NO_CACHE       3

Minidrivers that do not support the modification of this property can return SCARD_E_UNSUPPORTED_FEATURE.

 Administrator

CP_SUPPORTS_WIN_X509_ENROLLMENT

If False, enrollment operations is blocked at the Base CSP layer.

Minidrivers that do not support the modification of this property can return SCARD_E_UNSUPPORTED_FEATURE.

 Administrator

CP_CARD_GUID

In this situation, pbData is a buffer that contains a unique GUID for the card. Whether updating the GUID by property or through the “cardid” file, retrieving the GUID by either means should always return the same value.

 Administrator

CP_CARD_SERIAL_NO

In this situation, pbData is a buffer that contains a serial number for the card.

This is an optional property that the card may choose to support

 Administrator

CP_CARD_PIN_INFO

In this situation, pbData is a PIN_INFO structure that contains information about the PIN. The dwFlags parameter contains the identifier of the PIN to return.

If the PIN_INFO structure contains information that the card minidriver does not support, such as the PIN_INFO_REQUIRE_SECURE_ENTRY flag, the card minidriver should return SCARD_E_UNSUPPORTED.

Minidrivers that do not support the modification of this property can return SCARD_E_UNSUPPORTED_FEATURE.

 Administrator

CP_PARENT_WINDOW

In this situation, pbData is a HANDLE to the parent window. If the card minidriver wants to show UI to collect an external PIN, this property should be used to tie the UI to the parent window.

Note  This property is required only for cards that support external PINs.
 
Everyone

CP_PIN_CONTEXT_STRING

In this situation, pbData is a LPWSTR that contains context information from the application. If the card minidriver wants to show UI to collect an external PIN, this property should be used to display the context string from the calling application.

Note  pbData may be NULL if an application has not set a context string.
 
Note  This property is only required for cards that support external PINs.
 
Everyone

CP_CARD_PIN_STRENGTH_VERIFY

In this situation, pbData contains a bitmask of one or more of the following values:

  • CARD_PIN_STRENGTH_PLAINTEXT – Card can accept a plaintext PIN for authentication.
  • CARD_PIN_STRENGTH_SESSION_PIN – Card can generate a session PIN that should be used for subsequent authentications.

The dwFlags parameter contains the identifier of the PIN to return.

Minidrivers that do not support the modification of this property can return SCARD_E_UNSUPPORTED_FEATURE.

 Administrator

 

Requirements

Target platform

 Desktop

Header

 Cardmod.h (include Cardmod.h)

 

 

Send comments about this topic to Microsoft