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

讀取器中智慧卡的目前 狀態 。 成功時，它會收到下列其中一個狀態指標。

值 意義
SCARD_ABSENT
 讀取器中沒有卡片。
SCARD_PRESENT
 讀取器中有卡片，但尚未移至位置以供使用。
SCARD_SWALLOWED
 閱讀機中有卡片可供使用。 卡片未開啟電源。
SCARD_POWERED
 電源會提供給卡片，但讀取器驅動程式不會察覺卡片的模式。
SCARD_NEGOTIABLE
 卡片已重設，正在等候 PTS 交涉。
SCARD_SPECIFIC
 卡片已重設，且已建立特定的 通訊協定 。

[out, optional] pdwProtocol

如果有的話，則為目前的通訊協定。 只有在 pdwState 的傳回值SCARD_SPECIFICMODE時，傳回的值才有意義。

值 意義
SCARD_PROTOCOL_RAW
 原始傳輸通訊協定正在使用中。
SCARD_PROTOCOL_T0
 ISO 7816/3 T=0 通訊協定正在使用中。
SCARD_PROTOCOL_T1
 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

另請參閱

SCardConnect

SCardDisconnect