SCardListCardsA 函式 （winscard.h）

SCardListCards 函式會搜尋 智慧卡資料庫，並提供使用者先前引入系統的具名卡片清單。

呼叫端會指定 ATR 字串、一組介面識別碼（GUID），或兩者。 如果同時提供 ATR 字串和標識子陣列，傳回的卡片將會符合提供的 ATR 字串，並支援指定的介面。

語法

LONG SCardListCardsA(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCBYTE      pbAtr,
  [in]           LPCGUID      rgquidInterfaces,
  [in]           DWORD        cguidInterfaceCount,
  [out]          CHAR         *mszCards,
  [in, out]      LPDWORD      pcchCards
);

參數

[in] hContext

識別查詢之 資源管理員內容 的句柄。 資源管理員內容可由先前呼叫 SCardEstablishContext來設定。

如果此參數設定為 NULL，則搜尋卡片不限於任何內容。

[in, optional] pbAtr

要與已知卡片比較的 ATR 字串位址，如果沒有執行 ATR 比對，則 NULL。

[in] rgquidInterfaces

標識元陣列（GUID），如果沒有執行任何介面比對，則 NULL。 提供陣列時，只有在卡片支援所有指定的標識碼時，才會傳回卡片名稱。

[in] cguidInterfaceCount

rgguidInterfaces 陣列中的項目數。 如果 rgguidInterfacesNULL，則會忽略此值。

[out] mszCards

列出找到 智慧卡 的多字串。 如果此值 NULL，SCardListCards 會忽略 pcchCards中提供的緩衝區長度，傳回此參數未 NULLpcchCards 和成功碼時所傳回的緩衝區長度。

[in, out] pcchCards

mszCards 字元緩衝區的長度。 接收多字串結構的實際長度，包括所有尾端 null 字元。 如果緩衝區長度指定為 SCARD_AUTOALLOCATE，則 mszCards 會轉換成位元組指標的指標，並接收包含多字元串結構的記憶體區塊位址。 此記憶體區塊必須與 SCardFreeMemory解除分配。

傳回值

此函式會根據它是否成功或失敗，傳回不同的值。

言論

此函式不會重新導向，但在遠端桌面會話內呼叫函式時，不會產生錯誤。 這隻表示結果會來自遠端電腦，而不是本機計算機。

若要傳回子系統導入的所有智慧卡，請將 pbAtr 和 rgguidInterfaces 設定為 NULL。

SCardListCards 函式是資料庫查詢函式。 如需其他資料庫查詢函式的詳細資訊，請參閱 智慧卡資料庫查詢函式。

呼叫此函式應該在異動之外完成。 如果應用程式以 SCardBeginTransaction 函式開始交易，然後呼叫此函式，它會重設 hCard 參數（類型為 SCARDHANDLE），SCardBeginTransaction 函式。

Windows Server 2008 R2 和 Windows 7：在交易中呼叫此函式可能會導致您的電腦沒有回應。

Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP：不適用 。

例子

下列範例顯示智慧卡的清單。

LPTSTR pmszCards = NULL;
LPTSTR pCard;
LONG lReturn;
DWORD cch = SCARD_AUTOALLOCATE;

// Retrieve the list of cards.
lReturn = SCardListCards(NULL,
                         NULL,
                         NULL,
                         NULL,
                         (LPTSTR)&pmszCards,
                         &cch );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardListCards\n");
    exit(1); // Or other appropriate error action
}
// Do something with the multi string of cards.
// Output the values.
// A double-null terminates the list of values.
pCard = pmszCards;
while ( '\0' != *pCard )
{
    // Display the value.
    printf("%S\n", pCard );
    // Advance to the next value.
    pCard = pCard + wcslen(pCard) + 1;
}

// Remember to free pmszCards (by calling SCardFreeMemory).
// ...

要求

另請參閱

SCardEstablishContext

SCardFreeMemory

SCardGetProviderId

SCardListInterfaces

SCardListReaderGroups

SCardListReaders