winscard topic

Windows Smartcard APIs

The Smart Card subsystem, used to provide smartcard-aware applications with access to smartcard-related software resources and readers.

Microsoft documentation on smartcard-APIs

Functions

SCardAccessStartedEvent() → int

The SCardAccessStartedEvent function returns an event handle when an event signals that the smart card resource manager is started. The event-object handle can be specified in a call to one of the wait functions.

SCardAddReaderToGroup(int hContext, Pointer<Utf16> szReaderName, Pointer<Utf16> szGroupName) → int

The SCardAddReaderToGroup function adds a reader to a reader group.

SCardAudit(int hContext, int dwEvent) → int

The SCardAudit function writes event messages to the Windows application log Microsoft-Windows-SmartCard-Audit/Authentication.

SCardBeginTransaction(int hCard) → int

The SCardBeginTransaction function starts a transaction. The function waits for the completion of all other transactions before it begins. After the transaction starts, all other applications are blocked from accessing the smart card while the transaction is in progress.

SCardCancel(int hContext) → int

The SCardCancel function terminates all outstanding actions within a specific resource manager context. The only requests that you can cancel are those that require waiting for external action by the smart card or user. Any such outstanding action requests will terminate with a status indication that the action was canceled. This is especially useful to force outstanding SCardGetStatusChange calls to terminate.

SCardConnect(int hContext, Pointer<Utf16> szReader, int dwShareMode, int dwPreferredProtocols, Pointer<IntPtr> phCard, Pointer<Uint32> pdwActiveProtocol) → int

The SCardConnect function establishes a connection (using a specific resource manager context) between the calling application and a smart card contained by a specific reader. If no card exists in the specified reader, an error is returned.

SCardControl(int hCard, int dwControlCode, Pointer<NativeType> lpInBuffer, int cbInBufferSize, Pointer<NativeType> lpOutBuffer, int cbOutBufferSize, Pointer<Uint32> lpBytesReturned) → int

The SCardControl function gives you direct control of the reader. You can call it any time after a successful call to SCardConnect and before a successful call to SCardDisconnect. The effect on the state of the reader depends on the control code.

SCardDisconnect(int hCard, int dwDisposition) → int

The SCardDisconnect function terminates a connection previously opened between the calling application and a smart card in the target reader.

SCardEndTransaction(int hCard, int dwDisposition) → int

The SCardEndTransaction function completes a previously declared transaction, allowing other applications to resume interactions with the card.

SCardEstablishContext(int dwScope, Pointer<NativeType> pvReserved1, Pointer<NativeType> pvReserved2, Pointer<IntPtr> phContext) → int

The SCardEstablishContext function establishes the resource manager context (the scope) within which database operations are performed.

SCardForgetCardType(int hContext, Pointer<Utf16> szCardName) → int

The SCardForgetCardType function removes an introduced smart card from the smart card subsystem.

SCardForgetReader(int hContext, Pointer<Utf16> szReaderName) → int

The SCardForgetReader function removes a previously introduced reader from control by the smart card subsystem. It is removed from the smart card database, including from any reader group that it may have been added to.

SCardForgetReaderGroup(int hContext, Pointer<Utf16> szGroupName) → int

The SCardForgetReaderGroup function removes a previously introduced smart card reader group from the smart card subsystem. Although this function automatically clears all readers from the group, it does not affect the existence of the individual readers in the database.

SCardFreeMemory(int hContext, Pointer<NativeType> pvMem) → int

The SCardFreeMemory function releases memory that has been returned from the resource manager using the SCARD_AUTOALLOCATE length designator.

SCardGetAttrib(int hCard, int dwAttrId, Pointer<Uint8> pbAttr, Pointer<Uint32> pcbAttrLen) → int

The SCardGetAttrib function retrieves the current reader attributes for the given handle. It does not affect the state of the reader, driver, or card.

SCardGetCardTypeProviderName(int hContext, Pointer<Utf16> szCardName, int dwProviderId, Pointer<Utf16> szProvider, Pointer<Uint32> pcchProvider) → int

The SCardGetCardTypeProviderName function returns the name of the module (dynamic link library) that contains the provider for a given card name and provider type.

SCardGetDeviceTypeId(int hContext, Pointer<Utf16> szReaderName, Pointer<Uint32> pdwDeviceTypeId) → int

The SCardGetDeviceTypeId function gets the device type identifier of the card reader for the given reader name. This function does not affect the state of the reader.

SCardGetProviderId(int hContext, Pointer<Utf16> szCard, Pointer<GUID> pguidProviderId) → int

The SCardGetProviderId function returns the identifier (GUID) of the primary service provider for a given card. The caller supplies the name of a smart card (previously introduced to the system) and receives the registered identifier of the primary service provider GUID, if one exists.

SCardGetReaderDeviceInstanceId(int hContext, Pointer<Utf16> szReaderName, Pointer<Utf16> szDeviceInstanceId, Pointer<Uint32> pcchDeviceInstanceId) → int

The SCardGetReaderDeviceInstanceId function gets the device instance identifier of the card reader for the given reader name. This function does not affect the state of the reader.

SCardGetReaderIcon(int hContext, Pointer<Utf16> szReaderName, Pointer<Uint8> pbIcon, Pointer<Uint32> pcbIcon) → int

The SCardGetReaderIcon function gets an icon of the smart card reader for a given reader's name. This function does not affect the state of the card reader.

SCardGetStatusChange(int hContext, int dwTimeout, Pointer<SCARD_READERSTATE> rgReaderStates, int cReaders) → int

The SCardGetStatusChange function blocks execution until the current availability of the cards in a specific set of readers changes. The caller supplies a list of readers to be monitored by an SCARD_READERSTATE array and the maximum amount of time (in milliseconds) that it is willing to wait for an action to occur on one of the listed readers. Note that SCardGetStatusChange uses the user-supplied value in the dwCurrentState members of the rgReaderStatesSCARD_READERSTATE array as the definition of the current state of the readers. The function returns when there is a change in availability, having filled in the dwEventState members of rgReaderStates appropriately.

SCardGetTransmitCount(int hCard, Pointer<Uint32> pcTransmitCount) → int

The SCardGetTransmitCount function retrieves the number of transmit operations that have completed since the specified card reader was inserted.

SCardIntroduceCardType(int hContext, Pointer<Utf16> szCardName, Pointer<GUID> pguidPrimaryProvider, Pointer<GUID> rgguidInterfaces, int dwInterfaceCount, Pointer<Uint8> pbAtr, Pointer<Uint8> pbAtrMask, int cbAtrLen) → int

The SCardIntroduceCardType function introduces a smart card to the smart card subsystem (for the active user) by adding it to the smart card database.

SCardIntroduceReader(int hContext, Pointer<Utf16> szReaderName, Pointer<Utf16> szDeviceName) → int

The SCardIntroduceReader function introduces a new name for an existing smart card reader.

SCardIntroduceReaderGroup(int hContext, Pointer<Utf16> szGroupName) → int

The SCardIntroduceReaderGroup function introduces a reader group to the smart card subsystem. However, the reader group is not created until the group is specified when adding a reader to the smart card database.

SCardIsValidContext(int hContext) → int

The SCardIsValidContext function determines whether a smart card context handle is valid.

SCardListCards(int hContext, Pointer<Uint8> pbAtr, Pointer<GUID> rgquidInterfaces, int cguidInterfaceCount, Pointer<Utf16> mszCards, Pointer<Uint32> pcchCards) → int

The SCardListCards function searches the smart card database and provides a list of named cards previously introduced to the system by the user. The caller specifies an ATR string, a set of interface identifiers (GUIDs), or both. If both an ATR string and an identifier array are supplied, the cards returned will match the ATR string supplied and support the interfaces specified.

SCardListInterfaces(int hContext, Pointer<Utf16> szCard, Pointer<GUID> pguidInterfaces, Pointer<Uint32> pcguidInterfaces) → int

The SCardListInterfaces function provides a list of interfaces supplied by a given card. The caller supplies the name of a smart card previously introduced to the subsystem, and receives the list of interfaces supported by the card.

SCardListReaderGroups(int hContext, Pointer<Utf16> mszGroups, Pointer<Uint32> pcchGroups) → int

The SCardListReaderGroups function provides the list of reader groups that have previously been introduced to the system.

SCardListReaders(int hContext, Pointer<Utf16> mszGroups, Pointer<Utf16> mszReaders, Pointer<Uint32> pcchReaders) → int

The SCardListReaders function provides the list of readers within a set of named reader groups, eliminating duplicates. The caller supplies a list of reader groups, and receives the list of readers within the named groups. Unrecognized group names are ignored. This function only returns readers within the named groups that are currently attached to the system and available for use.

SCardListReadersWithDeviceInstanceId(int hContext, Pointer<Utf16> szDeviceInstanceId, Pointer<Utf16> mszReaders, Pointer<Uint32> pcchReaders) → int

The SCardListReadersWithDeviceInstanceId function gets the list of readers that have provided a device instance identifier. This function does not affect the state of the reader.

SCardLocateCards(int hContext, Pointer<Utf16> mszCards, Pointer<SCARD_READERSTATE> rgReaderStates, int cReaders) → int

The SCardLocateCards function searches the readers listed in the rgReaderStates parameter for a card with an ATR string that matches one of the card names specified in mszCards, returning immediately with the result.

SCardLocateCardsByATR(int hContext, Pointer<SCARD_ATRMASK> rgAtrMasks, int cAtrs, Pointer<SCARD_READERSTATE> rgReaderStates, int cReaders) → int

The SCardLocateCardsByATR function searches the readers listed in the rgReaderStates parameter for a card with a name that matches one of the card names contained in one of the SCARD_ATRMASK structures specified by the rgAtrMasks parameter.

SCardReadCache(int hContext, Pointer<GUID> CardIdentifier, int FreshnessCounter, Pointer<Utf16> LookupName, Pointer<Uint8> Data, Pointer<Uint32> DataLen) → int

The SCardReadCache function retrieves the value portion of a name-value pair from the global cache maintained by the Smart Card Resource Manager.

SCardReconnect(int hCard, int dwShareMode, int dwPreferredProtocols, int dwInitialization, Pointer<Uint32> pdwActiveProtocol) → int

The SCardReconnect function reestablishes an existing connection between the calling application and a smart card. This function moves a card handle from direct access to general access, or acknowledges and clears an error condition that is preventing further access to the card.

SCardReleaseContext(int hContext) → int

The SCardReleaseContext function closes an established resource manager context, freeing any resources allocated under that context, including SCARDHANDLE objects and memory allocated using the SCARD_AUTOALLOCATE length designator.

SCardReleaseStartedEvent() → void

The SCardReleaseStartedEvent function decrements the reference count for a handle acquired by a previous call to the SCardAccessStartedEvent function.

SCardRemoveReaderFromGroup(int hContext, Pointer<Utf16> szReaderName, Pointer<Utf16> szGroupName) → int

The SCardRemoveReaderFromGroup function removes a reader from an existing reader group. This function has no effect on the reader.

SCardSetAttrib(int hCard, int dwAttrId, Pointer<Uint8> pbAttr, int cbAttrLen) → int

The SCardSetAttrib function sets the given reader attribute for the given handle. It does not affect the state of the reader, reader driver, or smart card. Not all attributes are supported by all readers (nor can they be set at all times) as many of the attributes are under direct control of the transport protocol.

SCardSetCardTypeProviderName(int hContext, Pointer<Utf16> szCardName, int dwProviderId, Pointer<Utf16> szProvider) → int

The SCardSetCardTypeProviderName function specifies the name of the module (dynamic link library) containing the provider for a given card name and provider type.

SCardStatus(int hCard, Pointer<Utf16> mszReaderNames, Pointer<Uint32> pcchReaderLen, Pointer<Uint32> pdwState, Pointer<Uint32> pdwProtocol, Pointer<Uint8> pbAtr, Pointer<Uint32> pcbAtrLen) → int

The SCardStatus function provides the current status of a smart card in a reader. You can call it any time after a successful call to SCardConnect and before a successful call to SCardDisconnect. It does not affect the state of the reader or reader driver.

SCardTransmit(int hCard, Pointer<SCARD_IO_REQUEST> pioSendPci, Pointer<Uint8> pbSendBuffer, int cbSendLength, Pointer<SCARD_IO_REQUEST> pioRecvPci, Pointer<Uint8> pbRecvBuffer, Pointer<Uint32> pcbRecvLength) → int

The SCardTransmit function sends a service request to the smart card and expects to receive data back from the card.

SCardUIDlgSelectCard(Pointer<OPENCARDNAME_EX> param0) → int

The SCardUIDlgSelectCard function displays the smart card Select Card dialog box.

SCardWriteCache(int hContext, Pointer<GUID> CardIdentifier, int FreshnessCounter, Pointer<Utf16> LookupName, Pointer<Uint8> Data, int DataLen) → int

The SCardWriteCache function writes a name-value pair from a smart card to the global cache maintained by the Smart Card Resource Manager.