SCardIntroduceReaderW function (winscard.h)
The SCardIntroduceReader function introduces a new name for an existing smart card reader.
Syntax
LONG SCardIntroduceReaderW(
[in] SCARDCONTEXT hContext,
[in] LPCWSTR szReaderName,
[in] LPCWSTR szDeviceName
);
Parameters
[in] hContext
Handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext. This parameter cannot be NULL.
[in] szReaderName
Display name to be assigned to the reader.
[in] szDeviceName
System name of the smart card reader, for example, "MyReader 01".
Return value
This function returns different values depending on whether it succeeds or fails.
Return code | Description |
---|---|
|
SCARD_S_SUCCESS. |
|
An error code. For more information, see Smart Card Return Values. |
Remarks
All readers installed on the system are automatically introduced by their system name. Typically, SCardIntroduceReader is called only to change the name of an existing reader.
The SCardIntroduceReader function is a database management function. For more information on other database management functions, see Smart Card Database Management Functions.
To remove a reader, use SCardForgetReader.
Examples
The following example shows introducing a smart card reader.
// This example renames the reader name.
// This is a two-step process (first add the new
// name, then forget the old name).
LPBYTE pbAttr = NULL;
DWORD cByte = SCARD_AUTOALLOCATE;
LONG lReturn;
// Step 1: Add the new reader name.
// The device name attribute is a necessary value.
// hCardHandle was set by a previous call to SCardConnect.
lReturn = SCardGetAttrib(hCardHandle,
SCARD_ATTR_DEVICE_SYSTEM_NAME,
(LPBYTE)&pbAttr,
&cByte);
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardGetAttrib\n");
exit(1); // Or other error action
}
// Add the reader name.
// hContext was set earlier by SCardEstablishContext.
lReturn = SCardIntroduceReader(hContext,
TEXT("My New Reader Name"),
(LPCTSTR)pbAttr );
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardIntroduceReader\n");
exit(1); // Or other error action
}
// Step 2: Forget the old reader name.
lReturn = SCardForgetReader(hContext,
(LPCTSTR)pbAttr );
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardForgetReader\n");
exit(1); // Or other error action
}
// Free the memory when done.
lReturn = SCardFreeMemory( hContext, pbAttr );
Note
The winscard.h header defines SCardIntroduceReader as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows XP [desktop apps only] |
Minimum supported server | Windows Server 2003 [desktop apps only] |
Target Platform | Windows |
Header | winscard.h |
Library | Winscard.lib |
DLL | Winscard.dll |