다음을 통해 공유


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

[in, out] pcchCards

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

반환 값

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

반환 코드 설명
Success
SCARD_S_SUCCESS.
실패
오류 코드입니다. 자세한 내용은 스마트 카드 반환 값을 참조하세요.

설명

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

하위 시스템에 도입된 모든 스마트 카드를 반환하려면 pbAtrrgguidInterfaces를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

추가 정보

SCardEstablishContext

SCardFreeMemory

SCardGetProviderId

SCardListInterfaces

SCardListReaderGroups

SCardListReaders