SCardIntroduceReaderA function (winscard.h)

Article
02/09/2023

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

Note Smart card readers are automatically introduced to the system; a smart card reader vendor's setup program can also introduce a smart card reader to the system.

Syntax

LONG SCardIntroduceReaderA(
  [in] SCARDCONTEXT hContext,
  [in] LPCSTR       szReaderName,
  [in] LPCSTR       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
Success	SCARD_S_SUCCESS.
Failure	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 which 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 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