SCardListCardsA 함수(winscard.h)

아티클
08/27/2023

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 배열의 항목 수입니다. rgguidInterfaces가 NULL이면 이 값은 무시됩니다.

[out] mszCards

찾은 스마트 카드를 나열하는 다중 문자열입니다. 이 값이 NULL이면 SCardListCards는 pcchCards에 제공된 버퍼 길이를 무시하고 이 매개 변수가 pcchCards 및 성공 코드에 NULL이 아닌 경우 반환된 버퍼의 길이를 반환합니다.

[in, out] pcchCards

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

반환 값

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

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

요구 사항

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