다음을 통해 공유

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제공된 버퍼 길이를 무시합니다. 이 매개 변수가 pcchCards 및 성공 코드에 NULL 않은 경우 반환된 버퍼의 길이를 반환합니다.

[in, out] pcchCards

mszCards 버퍼의 길이(문자)입니다. 모든 후행 null 문자를 포함하여 다중 문자열 구조의 실제 길이를 받습니다. 버퍼 길이가 SCARD_AUTOALLOCATE 지정된 경우 mszCards 바이트 포인터에 대한 포인터로 변환되고 다중 문자열 구조가 포함된 메모리 블록의 주소를 받습니다. 이 메모리 블록은 SCardFreeMemory할당 취소해야 합니다.

반환 값

이 함수는 성공 여부에 따라 다른 값을 반환합니다.

반환 코드 묘사
성공
 SCARD_S_SUCCESS.
실패
 오류 코드입니다. 자세한 내용은 스마트 카드 반환 값참조하세요.

발언

이 함수는 리디렉션되지 않지만 원격 데스크톱 세션 내에서 함수를 호출해도 오류가 발생하지 않습니다. 이는 결과가 로컬 컴퓨터 대신 원격 컴퓨터에서 발생한다는 의미일 뿐입니다.

하위 시스템에 도입된 모든 스마트 카드를 반환하려면 pbAtr 및 rgguidInterfaces NULL설정합니다.

SCardListCards 함수는 데이터베이스 쿼리 함수입니다. 다른 데이터베이스 쿼리 함수에 대한 자세한 내용은스마트 카드 데이터베이스 쿼리 함수 참조하세요.

이 함수를 호출하는 작업은 트랜잭션 외부에서 수행해야 합니다. 애플리케이션이 SCardBeginTransaction 함수를 사용하여 트랜잭션을 시작한 다음 이 함수를 호출하는 경우 SCardBeginTransaction 함수의 hCard 매개 변수(SCARDHANDLE형식)를 다시 설정합니다.

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).
// ...

메모

winscard.h 헤더는 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 SCardListCards를 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입대한 규칙을 참조하세요.

요구 사항

요구 값
지원되는 최소 클라이언트 Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버 Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼 Windows
헤더 winscard.h
라이브러리 Winscard.lib
DLL Winscard.dll

참고 항목

SCardEstablishContext

SCardFreeMemory

SCardGetProviderId

SCardListInterfaces

SCardListReaderGroups

SCardListReaders