SCardListCardsW 函式 (winscard.h)

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

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

語法

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

參數

[in] hContext

識別查詢 之資源管理員內容的 控制碼。 資源管理員內容可由先前呼叫 SCardEstablishCoNtext來設定。

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

[in, optional] pbAtr

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

[in] rgquidInterfaces

識別碼陣列 (GUID) ，如果未執行任何介面比對，則為 Null 。 提供陣列時，只有在卡片支援所有指定的識別碼時，才會傳回卡片名稱。

[in] cguidInterfaceCount

rgguidInterfaces陣列中的專案數。 如果 rgguidInterfaces 為 Null，則會忽略此值。

[out] mszCards

列出找到 智慧卡 的多字串。 如果此值為 Null， SCardListCards 會忽略 pcchCards中提供的緩衝區長度，傳回如果此參數不是 Null 給 pcchCards 且成功程式碼傳回的緩衝區長度。

[in, out] pcchCards

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

傳回值

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

備註

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

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

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

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

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