Функция SCardConnectA (winscard.h)

Статья
11/20/2024

Функция SCardConnect устанавливает соединение (с помощью определенного контекста диспетчера ресурсов) между вызывающим приложением и смарт-картой, содержащейся определенным средством чтения. Если карточка не существует в указанном средстве чтения, возвращается ошибка.

Синтаксис

LONG SCardConnectA(
  [in]  SCARDCONTEXT  hContext,
  [in]  LPCSTR        szReader,
  [in]  DWORD         dwShareMode,
  [in]  DWORD         dwPreferredProtocols,
  [out] LPSCARDHANDLE phCard,
  [out] LPDWORD       pdwActiveProtocol
);

Параметры

[in] hContext

Дескриптор, определяющий контекст диспетчера ресурсов. Контекст диспетчера ресурсов задается предыдущим вызовом SCardEstablishContext.

[in] szReader

Имя средства чтения, содержащего целевую карточку.

[in] dwShareMode

Флаг, указывающий, могут ли другие приложения формировать подключения к карточке.

Ценность	Значение
SCARD_SHARE_SHARED	Это приложение готово поделиться карточкой с другими приложениями.
SCARD_SHARE_EXCLUSIVE	Это приложение не готово к совместному доступу к карточке с другими приложениями.
SCARD_SHARE_DIRECT	Это приложение выделяет средство чтения для частного использования и будет управлять им напрямую. К нему не допускаются другие приложения.

[in] dwPreferredProtocols

Битовая маска допустимых протоколов для подключения. Возможные значения можно объединить с операцией OR.

Ценность	Значение
SCARD_PROTOCOL_T0	T=0 является приемлемым протоколом.
SCARD_PROTOCOL_T1	T=1 является приемлемым протоколом.
0	Этот параметр может быть равен нулю, только если dwShareMode задано значение SCARD_SHARE_DIRECT. В этом случае никакие переговоры по протоколу не будут выполняться драйверами, пока директива IOCTL_SMARTCARD_SET_PROTOCOL управления не будет отправлена с SCardControl.

[out] phCard

Дескриптор, определяющий подключение к смарт-карте в указанном средстве чтения.

[out] pdwActiveProtocol

Флаг, указывающий установленный активный протокол.

Ценность	Значение
SCARD_PROTOCOL_T0	T=0 является активным протоколом.
SCARD_PROTOCOL_T1	T=1 является активным протоколом.
SCARD_PROTOCOL_UNDEFINED	SCARD_SHARE_DIRECT был указан, чтобы не произошло никаких переговоров по протоколу. Возможно, что в читателе нет карточки.

Возвращаемое значение

Эта функция возвращает разные значения в зависимости от того, выполнена ли она успешно или завершается сбоем.

Возвращаемый код	Описание
успех	SCARD_S_SUCCESS.
сбоя	Код ошибки. Дополнительные сведения см. в возвращаемых значений смарт-карт.
SCARD_E_NOT_READY	Читатель не смог подключиться к карточке.

Замечания

Функция SCardConnect — это смарт-карты и функция чтения доступа. Дополнительные сведения о других функциях доступа см. в функциях доступа смарт-карт и читателей.

Примеры

В следующем примере создается подключение к средству чтения. В примере предполагается, что hContext является допустимым дескриптором типа SCARDCONTEXT, полученным из предыдущего вызова SCardEstablishContext.

SCARDHANDLE     hCardHandle;
LONG            lReturn;
DWORD           dwAP;

lReturn = SCardConnect( hContext, 
                        (LPCTSTR)"Rainbow Technologies SCR3531 0",
                        SCARD_SHARE_SHARED,
                        SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1,
                        &hCardHandle,
                        &dwAP );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardConnect\n");
    exit(1);  // Or other appropriate action.
}

// Use the connection.
// Display the active protocol.
switch ( dwAP )
{
    case SCARD_PROTOCOL_T0:
        printf("Active protocol T0\n"); 
        break;

    case SCARD_PROTOCOL_T1:
        printf("Active protocol T1\n"); 
        break;

    case SCARD_PROTOCOL_UNDEFINED:
    default:
        printf("Active protocol unnegotiated or unknown\n"); 
        break;
}

// Remember to disconnect (by calling SCardDisconnect).
// ...

Заметка

Заголовок winscard.h определяет SCardConnect как псевдоним, который автоматически выбирает версию этой функции ANSI или Юникод на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	winscard.h
библиотеки	Winscard.lib
DLL	Winscard.dll

См. также

SCardControl

SCardDisconnect

SCardEstablishContext

SCardReconnect

Поделиться через