Expand Minimize

SCardIntroduceReader function

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 WINAPI SCardIntroduceReader(
  _In_  SCARDCONTEXT hContext,
  _In_  LPCTSTR szReaderName,
  _In_  LPCTSTR szDeviceName
);

Parameters

hContext [in]

Handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext. This parameter cannot be NULL.

szReaderName [in]

Display name to be assigned to the reader.

szDeviceName [in]

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 codeDescription
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 );


Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winscard.h

Library

Winscard.lib

DLL

Winscard.dll

Unicode and ANSI names

SCardIntroduceReaderW (Unicode) and SCardIntroduceReaderA (ANSI)

See also

SCardEstablishContext
SCardIntroduceCardType
SCardIntroduceReaderGroup
SCardForgetReader

 

 

Community Additions

ADD
Show:
© 2014 Microsoft