SCardListReadersWithDeviceInstanceIdA 函式 （winscard.h）

SCardListReadersWithDeviceInstanceId 函式會取得已提供裝置實例識別碼的讀取器清單。 此函式不會影響讀取器的狀態。

語法

LONG SCardListReadersWithDeviceInstanceIdA(
  [in]            SCARDCONTEXT hContext,
  [in]            LPCSTR       szDeviceInstanceId,
  [out, optional] LPSTR        mszReaders,
  [in, out]       LPDWORD      pcchReaders
);

參數

[in] hContext

識別查詢之資源管理員內容的句柄。 您可以透過先前呼叫 SCardEstablishContext 函式來設定資源管理員內容。 這個參數不能 NULL。

[in] szDeviceInstanceId

讀取器的裝置實例標識碼。 您可以使用讀取器名稱呼叫 SCardGetReaderDeviceInstanceId 函式，或從 DDK 呼叫 SetupDiGetDeviceInstanceId 函式，以取得此值。

[out, optional] mszReaders

包含所提供裝置實例標識碼內智慧卡讀取器的多字串。 如果此值 NULL，則函式會忽略 pcchReaders 參數中提供的緩衝區長度，如果此參數尚未 NULL，則會寫入傳回的緩衝區長度，以 pcchReaders，並傳回成功碼。

[in, out] pcchReaders

mszReaders 緩衝區的長度，以字元為單位。 此參數會接收多字串結構的實際長度，包括所有終止的 Null 字元。 如果緩衝區長度指定為SCARD_AUTOALLOCATE，則 mszReaders 會轉換成位元組指標的指標，並接收包含多字元串結構的記憶體區塊位址。 當您完成使用此記憶體時，請使用 SCardFreeMemory 函式來解除分配。

傳回值

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

言論

此函式不會重新導向。 在遠端桌面會話內失敗時，呼叫 SCardListReadersWithDeviceInstanceId 函式，並出現SCARD_E_READER_UNAVAILABLE錯誤碼。

例子

szDeviceInstanceIdcchReaderNameLONG     lReturn, lReturn2;

LPTSTR   pmszReaders = NULL;
LPTSTR   pReader = NULL;WCHAR
DWORD    cchReaderName = SCARD_AUTOALLOCATE;

// Retrieve the reader’s name from it’s device instance ID
// hContext was set by a previous call to SCardEstablishContext. 

// szDeviceInstanceId was obtained by calling SetupDiGetDeviceInstanceId
lReturn = SCardListReadersWithDeviceInstanceId (hContext,
                         szDeviceInstanceId,
                         (LPTSTR)&pmszReaders,
                         &cchReaderName);

switch( lReturn )
{
    case SCARD_E_NO_READERS_AVAILABLE:
        printf("No readers have the provided device instance ID.\n");
        // Take appropriate action.
        // ...
        break;

    case SCARD_S_SUCCESS:
        // Do something with the multi string of readers.
        // Output the values.
        // A double-null terminates the list of values.
        pReader = pmszReaders;
        while ( '\0' != *pReader )
        {
            // Display the value.
            printf("Reader: %S\n", pReader );
            // Advance to the next value.
            pReader = pReader + wcslen((wchar_t *)pReader) + 1;
        }
        // Free the memory.
        lReturn2 = SCardFreeMemory( hContext,
                                   pmszReaders );
        if ( SCARD_S_SUCCESS != lReturn2 )
            printf("Failed SCardFreeMemory\n");
        break;

default:
        printf("Failed SCardListReaders\n");
        // Take appropriate action.
        // ...
        break;

要求