SCardStatusA 函式 (winscard.h)
SCardStatus 函式會在讀取器中提供智慧卡的目前狀態。 您可以在成功呼叫 SCardConnect 和 成功呼叫 SCardDisconnect 之前,隨時呼叫它。 它不會影響讀取器或讀取器驅動程序的狀態。
語法
LONG SCardStatusA(
[in] SCARDHANDLE hCard,
[out] LPSTR mszReaderNames,
[in, out, optional] LPDWORD pcchReaderLen,
[out, optional] LPDWORD pdwState,
[out, optional] LPDWORD pdwProtocol,
[out] LPBYTE pbAtr,
[in, out, optional] LPDWORD pcbAtrLen
);
參數
[in] hCard
從 SCardConnect 傳回的參考值。
[out] mszReaderNames
顯示名稱清單 (已知目前連接的讀取器) 多個字串。
[in, out, optional] pcchReaderLen
在輸入時,提供 szReaderName 緩衝區的長度。
在輸出中,接收讀取器名稱清單) 字元 (的實際長度,包括 尾端 NULL 字元。 如果這個緩衝區長度指定為 SCARD_AUTOALLOCATE, 則 szReaderName 會轉換成位元組指標的指標,並接收包含多字串結構的記憶體區塊位址。
[out, optional] pdwState
讀取器中智慧卡的目前 狀態 。 成功時,它會收到下列其中一個狀態指標。
值 | 意義 |
---|---|
|
讀取器中沒有卡片。 |
|
讀取器中有卡片,但尚未移至位置以供使用。 |
|
閱讀機中有卡片可供使用。 卡片未開啟電源。 |
|
電源會提供給卡片,但讀取器驅動程式不會察覺卡片的模式。 |
|
卡片已重設,正在等候 PTS 交涉。 |
|
卡片已重設,且已建立特定的 通訊協定 。 |
[out, optional] pdwProtocol
如果有的話,則為目前的通訊協定。 只有在 pdwState 的傳回值SCARD_SPECIFICMODE時,傳回的值才有意義。
值 | 意義 |
---|---|
|
原始傳輸通訊協定正在使用中。 |
|
ISO 7816/3 T=0 通訊協定正在使用中。 |
|
ISO 7816/3 T=1 通訊協定正在使用中。 |
[out] pbAtr
如果有的話,從目前插入的卡片接收 ATR 字串 的 32 位元組緩衝區指標。
[in, out, optional] pcbAtrLen
在輸入時,提供 pbAtr 緩衝區的長度。 在輸出中,接收 ATR 字串中的位元組數目, (32 個字節上限) 。 如果這個緩衝區長度指定為SCARD_AUTOALLOCATE,則 pbAtr 會轉換成位元組指標的指標,並接收包含多字元串結構的記憶體區塊位址。
傳回值
如果函式成功在讀取器中提供智慧卡的目前狀態,則會SCARD_S_SUCCESS傳回值。
如果函式失敗,它會傳回錯誤碼。 如需詳細資訊,請參閱 智慧卡傳回值。
備註
SCardStatus 函式是智慧卡和讀取器存取函式。 如需其他存取函式的相關信息,請參閱 智慧卡和讀取器存取函式。
範例
下列範例示範如何判斷智慧卡的狀態。
WCHAR szReader[200];
DWORD cch = 200;
BYTE bAttr[32];
DWORD cByte = 32;
DWORD dwState, dwProtocol;
LONG lReturn;
// Determine the status.
// hCardHandle was set by an earlier call to SCardConnect.
lReturn = SCardStatus(hCardHandle,
szReader,
&cch,
&dwState,
&dwProtocol,
(LPBYTE)&bAttr,
&cByte);
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardStatus\n");
exit(1); // or other appropriate action
}
// Examine retrieved status elements.
// Look at the reader name and card state.
printf("%S\n", szReader );
switch ( dwState )
{
case SCARD_ABSENT:
printf("Card absent.\n");
break;
case SCARD_PRESENT:
printf("Card present.\n");
break;
case SCARD_SWALLOWED:
printf("Card swallowed.\n");
break;
case SCARD_POWERED:
printf("Card has power.\n");
break;
case SCARD_NEGOTIABLE:
printf("Card reset and waiting PTS negotiation.\n");
break;
case SCARD_SPECIFIC:
printf("Card has specific communication protocols set.\n");
break;
default:
printf("Unknown or unexpected card state.\n");
break;
}
注意
winscard.h 標頭會將 SCardStatus 定義為別名,根據 UNICODE 預處理器常數的定義,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼,可能會導致編譯或運行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
最低支援的伺服器 | Windows Server 2003 [僅限桌面應用程式] |
目標平台 | Windows |
標頭 | winscard.h |
程式庫 | Winscard.lib |
Dll | Winscard.dll |