Finding What You Need

The following documentation describes the software development kit (SDK) provided as a part of the smart card subsystem.

For a description of what is in the SDK documentation, see:

For… | See…
An overview of the Smart Card SDK, including topics on the Smart Card resource manager, user interface, and service providers. | About Smart Card: Smart Card Overview Smart Card Resource Manager Smart Card User Interface Smart Card Service Providers
Individual reference topics on the functions, structures, and COM interfaces provided in the SDK. | Smart Card Reference: Smart Card Functions Smart Card Structures Smart Card SDK Interfaces
Terms used in the SDK document set. | Smart Card Glossary: Terms can be referenced through the Smart Card Glossary or through hypertext links throughout the SDK documentation. Typically, a link is provided the first time a term is used in a topic.


Smart Card Overview

The basic components of the smart card subsystem are defined in the Interoperability Specification for ICCs and Personal Computer Systems (see Documents at http://www.smartcardsys.com/). These basic components include:

  • A resource manager that uses a Win32® application programming interface (API).
  • A user interface (UI) that works with the resource manager.
  • Several base service providers that provide access to specific services. In contrast to the resource manager's Win32® API, service providers use a COM interface model to provide smart card services.

The following illustration shows the relationships of these components in the overall smart card architecture.

For topics on several of the basic smart card concepts, see Smart Card Concepts.

For information on how the smart card subsystem works with other services available in the Microsoft Internet Security Framework, see Relation to Other Services.

For topics on the SDK components, see:

  • Smart Card Resource Manager.
  • Smart Card User Interface
  • Smart Card Service Providers.


Smart Card Concepts

This section covers some basic concepts that may be used when describing the interaction between users (and applications) and smart cards. These concepts include terms, as well as a discussion of two basic interactions between users and smart cards. However, this section does not attempt to describe all possible ways a user might interact with a smart card.

Note In addition to the basic concepts described here, the Smart Card Glossary also provides definitions of the terms used throughout these documents.

For information on… | See…
Readers and reader groups | Smart Card Readers
Smart cards and their COM interfaces. | Smart Card Interfaces
The smart card's primary service provider | Primary Service Provider
Introducing or accessing smart cards | Introducing Smart Cards to the System Accessing a Smart Card

For information on how the smart card subsystem works with other services available in the Microsoft Internet Security Framework, see Relation to Other Services.


Smart Card Readers

Readers are standard devices within the smart card subsystem. They are controlled through drivers, and are introduced to and removed from the system through Plug and Play or through the control panel Devices applet.

Each reader must be defined for use by the smart card subsystem. The subsystem is not responsible for any reader not specifically given to it.

Smart card readers can be divided into logical groups called reader groups. These groups can be defined by the subsystem, as well as defined by administrators and users. A reader can belong to more than one reader group

The smart card subsystem defines the following groups.

SCard$AllReaders
This group contains all the readers in the system. A new reader given to the smart card subsystem is automatically included in the system-wide reader group, SCard$AllReaders.
SCard$DefaultReaders
This default group, one for each terminal, contains all the readers assigned to the terminal that are not reserved for specific use.


Smart Card Interfaces

A smart card interface consists of a predefined set of services available within a smart card, the protocols necessary to invoke the services, and any assumptions regarding the context of the services.

With respect to smart cards, the term "interface" is similar to how it is used in COM, which in turn is similar in concept to the ISO 7816/5 application identifier but with a different scope.

Each smart card interface is identified by a globally unique identifier (GUID). For example, an interface might be defined that provides biorhythm information to its holder. If a given smart card supports this service, then it may claim to support that interface GUID. Using the interface GUIDs, an application may search for a particular set of interfaces, locating any card that supports that set, to complete a task.

Although an interface has one GUID, it may be implemented differently on different cards. For example, the biorhythm interface mentioned above can have several different implementations, yet all are referenced using the same GUID. The different implementations would not change the interaction between the application and the smart card; however, the interaction between the service provider and the smart cards may differ depending on the interface's implementation.

The set of interfaces supported by a smart card is defined during smart card introduction (see Introducing Smart Cards to the System).


Primary Service Provider

Each smart card known to the system may have a registered COM interface listed as its primary service provider. When you access a smart card through COM, this primary service provider supplies the control interfaces to the card. This allows card services to be exposed to a wide range of programming environments, including Java and Visual Basic.


Introducing Smart Cards to the System

Before the smart card subsystem can find a smart card, the smart card must be introduced to the system. This is typically done with a smart card setup utility provided by the card manufacturer. The utility could come as a program on a floppy disk (with the smart card), an ActiveX control available on a web site, and so on.

The setup utility must provide the following pieces of information about the card:

  • Its ATR string, and an optional mask to use as an aid in identifying the card.
  • A list of smart card interfaces supported by the card.
  • A friendly name for the card, to be used in identifying the card to the user. In most cases, the user will supply this to the setup utility.
  • The primary service provider associated with the card (optional), to be used when accessing the card through COM interfaces.

To simplify setup utilities, and to ensure the integrity of the smart card database, the smart card subsystem provides the following two functions. SCardIntroduceCardType introduces a smart card into the database and SCardForgetCardType removes it from the database.


Accessing a Smart Card

The smart card subsystem provides several means for an application or service provider to connect to a smart card:

  • An application can call SCardConnect to connect to a card that resides in a given reader. This is the simplest way to establish communication with a smart card.
  • An application can search for a specific smart card within a given reader group. The application identifies the card by its friendly name, and specifies a list of readers in which the card may appear. The resource manager searches the list of readers for any cards with an ATR string that matches the named card, and returns status information to the application. The smart card subsystem never puts up a GUI or interacts with the card beyond obtaining the ATR string. It does, however, supply sufficient information for the application or a common control to be able to walk the user through locating the desired card or card type. This results in mapping the request to a specific reader, to which further I/O is directed.
  • An application can request a list of cards supporting a given set of smart card interfaces. The application can then use the list in the previous case. This allows applications to connect to cards based on their capabilities, without regard to their names.

When an application looks for a card, it supplies an array of reader names in which to look. For each reader element in the array, the resource manager supplies the following information:

  • Whether the reader is available for use by this application.
  • Whether there is a card inserted into this reader, and if so, what its ATR string is.
  • Whether the card's ATR string matches any of the requested cards' ATR strings.

The application uses the returned information to apply further filters to the cards or to prompt the user to select the desired card. Note that one or more of the returned list of readers may be opened for exclusive use by other applications, so access to this list of readers is not guaranteed.


Relation to Other Services

Other parts of the Microsoft Internet Security Framework use the smart card subsystem, as shown in the following illustration. (Because of U.S. export restrictions, a CSP that uses an SCSP to communicate cryptographic-related requests should sign and verify the SCSP.)

See http://www.microsoft.com/smartcard/ for more information on the role of the smart card subsystem in the Microsoft Internet Security Framework.


Smart Card Resource Manager

The smart card resource manager manages the access to readers and to smart cards. To manage these resources, it performs the following three functions.

  • Identifies and tracks resources.
  • Allocates readers and resources across multiple applications.
  • Supports transaction primitives for accessing services available on a given card.

    Note This is an important point because current cards are single-threaded devices that often require the execution of multiple commands to complete a single function. Transactions allow multiple commands to be executed without interruption, ensuring that intermediate state information is not corrupted.

The resource manager can be accessed directly via the resource manager API or indirectly through any smart card service provider.

The resource manager API is a set of Win32® functions that provide direct access to the resource manager's services. (For an overview of the Win32 functions provided by the API, see Smart Card Resource Manager API.) In comparison, smart card service providers use COM interfaces.

Many of the Win32 functions in the resource manager API have equivalents in the properties and methods of the smart card service providers' COM interfaces. And although most application developers will find the COM model easier to work with, some applications will still need to use the Win32 functions to perform certain tasks. For example, applications that need to manipulate the list of readers or reader groups in the smart card database, and those that need direct control of a reader must use the resource manager API. The services that provide these capabilities are available only in the Win32 functions, not in the COM model provided by the service providers.

For information on how the resource manager is implemented in Microsoft® Windows®, see Resource Manager Implementation.


Resource Manager Implementation

The resource manager runs as a trusted service in a single process. All requests for smart card access are made to the resource manager, which routes them to the reader that contains the targeted card.

Smart cards are often used in conjunction with security and personal privacy. Wherever possible, the resource manager uses the security mechanisms existing within the underlying operating system when accessing a reader or smart card.


Smart Card Resource Manager API

The resource manager API provides the following functionality.

To… | See…
Query the smart card database. | Smart Card Database Query Functions
Manage the smart card database. | Smart Card Database Management Functions
Manage the context of the resource manager's database operations. | Resource Manager Context Functions
Release allocated memory. | Resource Manager Support Function
Track smart cards within readers. | Smart Card Tracking Functions
Connect to and communicate with a smart card, including transferring data using T=0, T=1, and raw protocols. | Smart Card and Reader Access Functions
Communicate with cards that may not conform to the ISO 7816 specifications. | Direct Card Access Functions


Smart Card Database Query Functions

These functions query the smart card database. They can provide a list of smart cards supplied by a specific user, the interfaces and primary service provider of a specific card, the reader groups defined for the system, and the readers within a set of reader groups.

When using these functions, you can query the complete smart card database, or you can narrow the search by setting the resource manager context. The resource manager context is set by calling SCardEstablishContext) before calling a query function.

Note Without a specified context, some information may still be inaccessible due to security restrictions.

To… | Call…
Retrieve the identifier (GUID) of the primary service provider for the given card. | SCardGetProviderId
Retrieve a list of cards previously introduced to the system by a specific user. | SCardListCards
Retrieve the identifiers (GUIDs) of the interfaces supplied by a given card. | SCardListInterfaces
Retrieve a list of reader groups that have previously been introduced to the system. | SCadListReaderGroups
Retrieve the list of readers within a set of named reader groups. | SCardListReaders


Smart Card Database Management Functions

These functions manage the smart card database, updating the database using a specified resource manager context.

Note Database security is maintained by placing access restrictions on the database, rather than by adding security mechanisms to the smart card subsystem.

To… | Call…
Add a reader to a reader group. | SCardAddReaderToGroup
Remove a smart card from the system. | SCardForgetCardType
Remove a reader from the system. | SCardForgetReader
Remove a reader group from the system. | SCardForgetReaderGroup
Introduce a new card to the system. | SCardIntroduceCardType
Introduce a new reader to the system. | SCardIntroduceReader
Introduce a new reader group to the system. | SCardIntroduceReaderGroup
Remove a reader from a reader group. | SCardRemoveReaderFromGroup


Resource Manager Context Functions

These functions establish and release the resource manager context that is used by the database query and database management functions.

To… | Call…
Establishes a context for accessing the smart card database. | SCardEstablishContext
Closes an established context. | SCardReleaseContext


Resource Manager Support Function

This function frees memory allocated through the use of the SCARD_AUTOALLOCATE length designator, simplifying the use of the other resource manager functions.

To… | Call…
Releases memory returned through the use of SCARD_AUTOALLOCATE. | SCardFreeMemory


Smart Card Tracking Functions

These functions let you track cards within readers. These routines typically use the SCARD_READERSTATE structure within an array.

To… | Call…
Search for a card whose ATR string matches a supplied card name. | SCardLocateCards
Block execution until the current availability of cards changes. | SCardGetStatusChange
Terminate outstanding actions. | SCardCancel


Smart Card and Reader Access Functions

These functions connect to and communicate with a specific smart card. I/O operations to the card use a buffer for sending or receiving data, plus a structure that contains protocol control information. The protocol control information structure always begins with an SCARD_IO_REQUEST structure.

To… | Call…
Connect to a card. | SCardConnect
Reestablish a connection. | SCardReconnect
Terminate a connection. | SCardDisconnect
Start a transaction, blocking other applications from accessing a card. | SCardBeginTransaction
End a transaction, allowing other applications to access a card. | SCardEndTransaction
Provide the current status of the reader. | SCardStatus
Requests service and receives data back from a card using T=0, T=1, and raw protocols. | SCardTransmit


Direct Card Access Functions

The smart card subsystem lets you communicate with cards that may not conform to the ISO 7816 specifications. To do this, these functions allow you to control the attributes of the communications between the application and the card by giving you direct, low-level manipulation of the reader.

To use these functions, you have to supply an identifier for the attribute in question. For valid attribute identifiers and values, refer to Table 3-1 in Requirements for PC-Connected Interface Devices.

To… | Call…
Provide direct control of the reader. | SCardControl
Get reader attributes. | SCardGetAttrib
Set reader attribute. | SCardSetAttrib


Smart Card User Interface

The smart card user interface (UI) is a single common dialog that lets the user specify or search for a smart card to open (that is, connect to and use in an application).

Following are two ways you can use the common dialog. Both assume that the dialog UI will be displayed. (See OPENCARDNAME for more information.)

To let the user select a smart card to open (that is, connect to and use in the calling application)
  1. Declare a variable of type OPENCARDNAME.
  2. Fill in the appropriate information for the common dialog to narrow the search for a card that the calling application is looking for. This would include specifying lpstrGroupNames, lpstrCardNames, and, in future releases, rgguidInterfaces. This would also include specifying a preferred sharemode and protocol to use when the common dialog connects to the card using the dwShareMode and dwProtocols OPENCARDNAME structure members.
  3. Call the GetOpenCardName function to display the common dialog to the user. A simple help information line will be displayed, and if one of the cards being requested is found, the card will be highlighted in the display. For multiple card name searches, the first reader containing one of the preferred cards will be highlighted.

  4. The user then selects a card, clicks OK, and connects to the smart card.
To search for a specific card by using the lpfnConnect, lpfnCheck, and lpfnDisconnect callback functions.
  1. Declare a variable of type OPENCARDNAME.
  2. Fill in the appropriate information for the common dialog to use to narrow the search for a card that the calling application seeks. This would include giving lpstrGroupNames, lpstrCardNames, and, in future releases, rgguidInterfaces).
    1. In addition, create the Connect, Check, and Disconnect callback functions and set the lpfnConnect, lpfnCheck, and lpfnDisconnect OPENCARDNAME data members appropriately.

    Note: All three functions and members must be available when using the common dialog in this way.

  4. Call the GetOpenCardName common dialog function.
  5. The common dialog will then look for the requested cards. If a matching card name or ATR string is found, the Connect, Check, and Disconnect callback functions will be called in sequence. If a card passes the Check routine (that is, the Check callback returns TRUE), this card is highlighted in the display to the user.

    Note: If multiple card names are given, the first reader that contains one of the requested cards and passes the Check routine will be the selected card.

  6. If no matches are found, the common dialog seen above will appear.


Smart Card Service Providers

Service providers (SCSP) provide access to Smart Card capabilities. They can provide access to a single capability, such as the base service providers provided by the Smart Card SDK, or they can provide access to several capabilities in order to accomplish a more complex task.

Service providers provide access through COM interfaces. The Smart Card SDK provides the COM interfaces used by its own base service providers, as well as several application interfaces that can be used when developing custom service providers.

For information on… | See…
Base service providers | Base Service Providers
Adding functionality to a service provider. | Building an ISO7816-4 ADPU Command
A vendor wrapper example. | Vendor Wrapper Service Provider

For an overview of all the COM interfaces provided by the smart card SDK (base service provider and application interfaces), see Smart Card Interfaces.


Base Service Providers

These service providers provide the basic smart card capabilities. They can be used to access a single smart card capability, or their COM interfaces can be combined to provide several capabilities within a single service provider. These service providers are the building blocks for developing additional functionality to other service providers.

The following tasks can be performed by base service provider interfaces supplied by the Smart Card SDK.

To… | Use… | In DLL…
Connect to a smart card, implement transactions, close connections, etc. | ISCard | SCardMgr
Maintain a command APDU and reply APDU. | ISCardCmd | SCardDat
Query the smart card database. | ISCardDatabase | SCardMgr
Locate a smart card or reader. | ISCardLocate |
Build an ISO7816-4 command APDU. | ISCardISO7816 | SCardSrv
Wrap an Istream buffer using VB-compatible types. | IByteBuffer | SCardDat

The following example shows a typical use of these base service provider interfaces. In this example, the ISCard, ISCardISO7816, and ISCardCmd interfaces are used to perform a transaction.

To perform a transaction
  1. Create an instance for all base service provider interfaces needed (for example, ISCard, ISCardISO7816, and ISCardCmd).
  2. Connect to a particular smart card using the methods in the ISCard interface.
  3. Using ISCardISO7816 and an ISCardCmd object, build an ISO 7816-4 command by calling an ISCardISO7816 method. The command is contained in ISCardCmd as the command APDU.
  4. Do a transaction with the card by calling the ISCard transaction method and passing the created ISCardCmd object. When the transaction is complete, the results are stored in ISCardCmd reply APDU.
  5. Interpret the ISCardCmd reply APDU and repeat.
  6. Release all interfaces when operations are complete.

For information on the ADPU command is built within the DLLs, see Building an ISO7816-4 ADPU Command.


Building an ISO7816-4 ADPU Command

To add functionality to a service provider, you need to know how an ISO7816-4 ADPU is built within the base service provider DLLs. The following procedure gives a brief overview of the build process.

Note The code segments included here are not necessarily complete; refer to the example applications and DLLs for more information.

To Build an ISO7816-4 APDU Command
  1. Create an instance of ISCardCmd and ISCardISO7816 interface/objects.

    // Create an ISCardCmd object
// Note: To use CoCreateInstance on Windows 95, make sure no Distributed COM
// flags are included in the API call or during build. Do not define flags
// _WIN32_DCOM or _WIN32_WINNT >= 0x0400.
        hresult = CoCreateInstance(    CLSID_CSCardCmd,
                        NULL,
                        CLSCTX_ALL,
                        IID_ISCardCmd,
                        (LPVOID*) &g_pISCardCmd);
    //Create an ISCardISO7816 object
    hresult = CoCreateInstance(    CLSID_CSCardISO7816,
                        NULL,
                        CLSCTX_ALL,
                        IID_ISCardISO7816,
                        (LPVOID*) &g_pISCardISO7816);

    The ISCardCmd object contains two IByteBuffer buffers. One buffer contains the actual APDU command string (plus any data to send with the command). The other contains any reply information returned by the card after command execution.

  2. Using these objects, we can now create a valid ISO7816-4 command as follows:
    // Do challenge
        hresult = g_pISCardISO7816->GetChallenge(    dwLengthOfChallenge,
                                &g_pISCardCmd);

    Here is the code used in the GetChallenge method:

    STDMETHODIMP CSCardISO7816::GetChallenge(    IN DWORD dwBytesExpected /*= 0*/,
                                IN OUT LPSCARDCMD *ppCmd)
{
    // Locals.
    HRESULT hr = S_OK;

    try
    {
        // Is the ISCardCmd object ok?
        hr = IsSCardCmdValid(ppCmd);
        if (FAILED(hr))
            throw (hr);

                // Do it!
        hr = (*ppCmd)->BuildCmd(    m_byClassId,
                                (BYTE) INS_GET_CHALLENGE),
                                (BYTE) INS_NULL),// P1 = 0x00
                                (BYTE) INS_NULL),// P2 = 0x00
                        NULL,
                                &dwBytesExpected);
        if (FAILED(hr))
            throw (hr);
    }

    The ISCardISO7816::GetChallenge method simply uses the ISCardCmd::BuildCmd to build the requested APDU. This is done by writing the appropriate information into the ISCardCmd APDU buffer in the hr = (*ppCmd)->BuildCmd line above.

  3. Using the built ISCardCmd object, do a transaction with the card, interpret the results, and continue.

Expanding beyond ISO7816-4

The recommended way to expand the service provider build-execute process described above is to create a new COM object. This COM object should support a new interface that allows creation of non-ISO7816-4 commands and should aggregate the ISCardISO7816 interface.


Vendor Wrapper Service Provider

The purpose of the vendor wrapper is to encapsulate and utilize the low-level COM interfaces (supplied by the smart card manufacturers) for a particular smart card. These interfaces are not supplied by Microsoft.

As described in part 6 of the Interoperability Specification for ICCs and Personal Computer Systems (see Documents at http://www.smartcardsys.com/), the functionality exposed by this wrapper is easier to use than the functionality of four separate service providers. The wrapper's functionality can be divided into four main areas:

  • Smart card authentication services, such as get challenge and card authentication.
  • Smart card file access or file system services, such as open, close, read, and write.
  • Smart card management, such as attach and detach.
  • Smart card verification services, such as verify and change code.

The functionality is specific to the type of card being used (which functions the card supports, protocols, etc.) and will be different for each card.

The Microsoft example wrapper uses the ATL COM library to implement a simple wrapper and lay down a template for other wrappers. It is structured as follows:

DLL Name | Interface/Object | Description
SCardCOM | ISCardAuth | Authentication services.
SCardCOM | ISCardFileAccess | File system services.
SCardCOM | ISCardManage | Management services.
SCardCOM | ISCardVerify | Verification services.

Following is a typical use of the vendor wrapper. This example uses the ISCardManage interface to create instances of the interfaces that will be wrapped into the service provider and the ISCardVerify interface to verify their operation.

To build a wrapper service provider
  1. Create an instance of the ISCardManage interface. Use this interface to create an instance of required interfaces (for example, ISCardFileAccess or ISCardVerify). When creating these interfaces, any corresponding low-level COM interfaces would also be created.
  2. Attach/connect to a card through the appropriate ISCardManage method.
  3. Perform required operations through the appropriate ISCardVerify method (which may call multiple low-level COM interfaces and methods to complete).
  4. Repeat for other operations.
  5. Release when complete.

The COM interface name and interface identifier (GUID) should not change from those used in the code or example wrapper. However, the class GUID (that is, where an actual implementation of an interface resides) must be changed from those used. This is especially important when implementing a vendor wrapper. One example would be using multiple vendor wrappers on a particular computer. These wrappers should implement the same COM interfaces, but will always use different implementation strategies. Therefore, different classes (and class IDs) are required.


Smart Card Functions

The Smart Card SDK provides the following functions.

Call… | To…
GetOpenCardName | Display the smart card common dialog.
SCardAddReaderToGroup | Add a reader to an existing reader group.
SCardBeginTransaction | Start a transaction.
SCardCancel | Terminate all outstanding actions within a context.
SCardConnect | Establish a connection between the calling application and a smart card.
SCardControl | Get direct control of the reader after SCardConnect is called.
SCardDisconnect | Terminate a connection between the calling application and a smart card.
SCardEndTransaction | Complete a transaction.
SCardEstablishContext | Establish a resource manager context for accessing the smart card database.
SCardForgetCardType | Remove a previously defined smart card from the smart card subsystem.
SCardForgetReader | Remove a previously defined reader from the smart card subsystem.
SCardForgetReaderGroup | Remove a previously defined reader group from the smart card subsystem.
SCardFreeMemory | Release memory allocated by resource manager.
SCardGetAttrib | Get the current reader's attributes from a given reader, driver, or smart card.
SCardGetProviderId | Get the identifier (GUID) of the Primary Service Provider for a smart card.
SCardGetStatusChange | Block execution until status of the reader(s) changes.
SCardIntroduceCardType | Introduce a new smart card to the smart card subsystem.
SCardIntroduceReader | Introduce a new reader to the smart card subsystem.
SCardIntroduceReaderGroup | Introduce a new reader group to the smart card subsystem.
SCardListCards | Provide a list of smart cards already introduced to the subsystem.
SCardListInterfaces | Provide a list of interfaces supplied by a given smart card.
SCardListReaderGroups | Provide a list of reader groups already introduced to the subsystem.
SCardListReaders | Provide a list of readers already introduced to the subsystem.
SCardLocateCards | Locate the card(s) that matches a given ATR string.
SCardLocateDialog | Initiate a search for a given smart card.
SCardReconnect | Reestablish an existing connection from the calling application to the smart card.
SCardReleaseContext | Close an established resource manager context.
SCardRemoveReaderFromGroup | Remove a reader from an existing reader group.
SCardSetAttrib | Set a given reader attribute.
SCardStatus | Get the current state of a reader.
SCardTransmit | Send a service request to a smart card.


GetOpenCardName

The GetOpenCardName function displays the smart card common dialog.

LONG GetOpenCardName(
  IN LPOPENCARDNAME pDlgStruc
);

Parameters

pDlgStruc
Points to the OPENCARDNAME structure for the common dialog.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

See Also

OPENCARDNAME


SCardAddReaderToGroup

The SCardAddReaderToGroup function adds a reader to an existing reader group.

LONG SCardAddReaderToGroup(
  IN SCARDCONTEXT hContext,
  IN LPCTSTR szReaderName,
  IN LPCTSTR szGroupName
);

Parameters

hContext
Supplies the handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext.
szReaderName
Supplies the friendly name of the reader that you are adding.
szGroupName
Supplies the friendly name of the group to which you are adding the reader.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardAddReaderToGroup is a database management function. For a description of other database management functions, see Smart Card Database Management Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardIntroduceReader, SCardIntroduceReaderGroup, SCardRemoveReaderFromGroup


SCardBeginTransaction

The SCardBeginTransaction function starts a transaction, waiting for the completion all other transactions before it begins.

When the transaction starts, all other applications are blocked from accessing the smart card while the transaction is in progress.

LONG SCardBeginTransaction(
  IN SCARDHANDLE hCard
);

Parameters

hCard
Supplies the reference value obtained from a previous call to SCardConnect.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardBeginTransaction is a smart card and reader access function. For a description of other access functions, see Smart Card and Reader Access Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardConnect, SCardEndTransaction


SCardCancel

The SCardCancel function terminates all outstanding actions within a specific resource manager context.

The only requests that you can cancel are those that require waiting for external action by the smart card or user. Any such outstanding action requests will terminate with a status indication that the action was canceled. This is especially useful to force outstanding SCardGetStatusChange calls to terminate.

LONG SCardCancel(
  IN SCARDCONTEXT hContext
);

Parameters

hContext
Supplies the handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardCancel is a smart card tracking function. For a description of other tracking functions, see Smart Card Tracking Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardGetStatusChange, SCardLocateCards


SCardConnect

The SCardConnect function establishes a connection (using a specific resource manager context) between the calling application and a smart card contained by a specific reader. If no card exists in the specified reader, an error is returned.

LONG SCardConnect(
  IN SCARDCONTEXT hContext,
  IN LPCTSTR szReader,
  IN DWORD dwShareMode,
  IN DWORD dwPreferredProtocols,
  OUT LPSCARDHANDLE phCard,
  OUT LPDWORD pdwActiveProtocol
);

Parameters

hContext
Supplies the handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext.
szReader
Supplies the name of the reader containing the target card.
dwShareMode
Supplies a flag that indicates whether other applications may form connections to the card. Possible values are:
Value | Meaning
SCARDSHARE_SHARED | This application is willing to share the card with other applications.
SCARDSHARE_EXCLUSIVE | This application is not willing to share the card with other applications.
SCARDSHARE_DIRECT | This application is allocating the reader for its private use, and will be controlling it directly. No other applications are allowed access to it.

dwPreferredProtocols
Supplies a bit mask of acceptable protocols for the connection. Possible values, which may be combined with the OR operation, are:
Value | Meaning
SCARD_PROTOCOL_T0 | T=0 is an acceptable protocol.
SCARD_PROTOCOL_T1 | T=1 is an acceptable protocol.
0 | This parameter may be zero only if dwShareMode is set to SCARDSHARE_DIRECT. In this case, no protocol negotiation will be performed by the drivers until an IOCTL_SMARTCARD_SET_PROTOCOL control directive is sent with SCardControl.

phCard
Receives a handle that identifies the connection to the smart card in the designated reader.
pdwActiveProtocol
Receives a flag that indicates the established active protocol. Possible values are:
Value | Meaning
SCARD_PROTOCOL_T0 | T=0 is the active protocol.
SCARD_PROTOCOL_T1 | T=1 is the active protocol.
SCARD_PROTOCOL_UNKNOWN | SCARDSHARE_DIRECT has been specified, so that no protocol negotiation has occurred. It is possible that there is no card in the reader.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardConnect is a smart card and reader access function. For a description of other access functions, see Smart Card and Reader Access Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardControl, SCardDisconnect, SCardEstablishContext, SCardReconnect


SCardControl

The SCardControl function gives you direct control of the reader. You can call it any time after a successful call to SCardConnect and before a successful call to SCardDisconnect. The effect on the state of the reader depends on the control code.

LONG SCardControl(
  IN SCARDHANDLE hCard,
  IN DWORD dwControlCode,
  IN LPCVOID lpInBuffer,
  IN DWORD nInBufferSize,
  OUT LPVOID lpOutBuffer,
  IN DWORD nOutBufferSize,
  OUT LPDWORD lpBytesReturned
);

Parameters

hCard
This is the reference value returned from SCardConnect.
dwControlCode
Supplies the control code for the operation. This value identifies the specific operation to be performed.
lpInBuffer
Supplies a pointer to a buffer that contains the data required to perform the operation. This parameter can be NULL if the dwControlCode parameter specifies an operation that does not require input data.
nInBufferSize
Supplies the size, in bytes, of the buffer pointed to by lpInBuffer.
lpOutBuffer
Points to a buffer that receives the operation's output data. This parameter can be NULL if the dwControlCode parameter specifies an operation that does not produce output data.
nOutBufferSize
Supplies the size, in bytes, of the buffer pointed to by lpOutBuffer.
lpBytesReturned
Points to a DWORD that receives the size, in bytes, of the data stored into the buffer pointed to by lpOutBuffer.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardControl is a direct card access function. For a description of other direct access functions, see Direct Card Access Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardConnect
SCardDisconnect


SCardDisconnect

The SCardDisconnect function terminates a connection previously opened between the calling application and a smart card in the target reader.

LONG SCardDisconnect(
  IN SCARDHANDLE hCard,
  IN DWORD dwDisposition
);

Parameters

hCard
Supplies the reference value obtained from a previous call to SCardConnect.
dwDisposition
Indicates what to do with the card in the connected reader on close. Possible values are:
Value | Meaning
SCARD_LEAVE_CARD | Don't do anything special.
SCARD_RESET_CARD | Reset the card.
SCARD_UNPOWER_CARD | Power down the card.
SCARD_EJECT_CARD | Eject the card.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardDisconnect is a smart card and reader access function. For a description of other access functions, see Smart Card and Reader Access Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardConnect, SCardReconnect


SCardEndTransaction

The SCardEndTransaction function completes a previously declared transaction, allowing other applications to resume interactions with the card.

LONG SCardEndTransaction(
  IN SCARDHANDLE hCard,
  IN DWORD dwDisposition
);

Parameters

hCard
Supplies the reference value obtained from a previous call to SCardConnect.
dwDisposition
Indicates what to do with the card in the connected reader on close. Possible values are:
Value | Meaning
SCARD_LEAVE_CARD | Don't do anything special.
SCARD_RESET_CARD | Reset the card.
SCARD_UNPOWER_CARD | Power down the card.
SCARD_EJECT_CARD | Eject the card.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardEndTransaction is a smart card and reader access function. For a description of other access functions, see Smart Card and Reader Access Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardConnect, SCardBeginTransaction


SCardEstablishContext

The SCardEstablishContext function establishes the resource manager context (the scope) within which database operations are performed.

LONG SCardEstablishContext(
  IN  DWORD dwScope,
  IN  LPCVOID pvReserved1,
  IN  LPCVOID pvReserved2,
  OUT LPSCARDCONTEXT phContext
);

Parameters

dwScope
Supplies the scope of the resource manager context. Possible values are:
Value | Meaning
SCARD_SCOPE_USER | Database operations are performed within the domain of the user.
SCARD_SCOPE_SYSTEM | Database operations are performed within the domain of the system. (The calling application must have appropriate access permissions for any database actions.)

pvReserved1
Reserved for future use, and must be NULL. Reserved to allow a suitably privileged management application to act on behalf of another user.
pvReserved2
Reserved for future use, and must be NULL. Reserved to allow a suitably privileged management application to act on behalf of another terminal.
phContext
Receives a handle to the established resource manager context. This handle can now be supplied to other functions attempting to do work within this context.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

The context handle returned by SCardEstablishContext can be used by database query and management functions. For a description of these functions see, Smart Card Database Query Functions and Smart Card Database Management Functions.

To release an established resource manager context, see SCardReleaseContext.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardReleaseContext


SCardForgetCardType

The SCardForgetCardType function removes an introduced smart card from the smart card subsystem.

LONG SCardForgetCardType(
  IN SCARDCONTEXT hContext,
  IN LPCTSTR szCardName
);

Parameters

hContext
Supplies the handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext.
szCardName
Supplies the friendly name of the card to be removed from the smart card database.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardForgetCardType is a database management function. For a description of other database management functions, see Smart Card Database Management Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardForgetReader, SCardForgetReaderGroup, SCardIntroduceCardType


SCardForgetReader

The SCardForgetReader function removes a previously introduced reader from control by the smart card subsystem. It is removed from the smart card database, including from any reader group that it may have been added to.

LONG SCardForgetReader(
  IN SCARDCONTEXT hContext,
  IN LPCTSTR szReaderName
);

Parameters

hContext
Supplies the handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext.
szReaderName
Supplies the friendly name of the reader to be removed from the smart card database.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardForgetReader is a database management function. For a description of other database management functions, see Smart Card Database Management Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardForgetCardType, SCardForgetReaderGroup, SCardIntroduceReader


SCardForgetReaderGroup

The SCardForgetReaderGroup function removes a previously introduced smart card reader group from the smart card subsystem. Although this function automatically clears all readers from the group, it does not affect the existence of the individual readers in the database.

LONG SCardForgetReaderGroup(
  IN SCARDCONTEXT hContext,
  IN LPCTSTR szGroupName
);

Parameters

hContext
Supplies the handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext.
szGroupName
Supplies the friendly name of the reader group to be removed. System-defined reader groups cannot be removed from the database.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardForgetReaderGroup is a database management function. For a description of other database management functions, see Smart Card Database Management Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardForgetCardType, SCardForgetReader, SCardIntroduceReaderGroup


SCardFreeMemory

The SCardFreeMemory function releases memory that has been returned from the resource manager using the SCARD_AUTOALLOCATE length designator.

LONG SCardFreeMemory(
  IN SCARDCONTEXT hContext,
  IN LPVOID pvMem
);

Parameters

hContext
Supplies the handle that identifies the resource manager context returned from SCardEstablishContext, or NULL if the creating function also specified NULL for its hContext (see Smart Card Database Query Functions).
pvMem
Supplies the memory block to be released.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardGetProviderId, SCardListCards' SCardListInterfaces, SCardListReaderGroups, SCardListReaders


SCardGetAttrib

The SCardGetAttrib function gets the current reader attributes for the given handle. It does not affect the state of the reader, driver, or card.

LONG SCardGetAttrib(
  IN SCARDHANDLE hCard,
  IN DWORD dwAttrId,
  OUT LPBYTE pbAttr,
  IN OUT LPDWORD pcbAttrLen
);

Parameters

hCard
Supplies the reference value returned from SCardConnect.
dwAttrId
Supplies the identifier for the attribute to get.
pbAttr
Points to a buffer that receives the attribute whose ID is supplied in dwAttrId. If this value is NULL, SCardGetAttrib ignores the buffer length supplied in pcbAttrLength, writes the length of the buffer that would have been returned if this parameter had not been NULL to pcbAttrLength, and returns a success code.
pcbAttrLength
Supplies the length of the pbAttr buffer in bytes, and receives the actual length of the received attribute. If the buffer length is specified as SCARD_AUTOALLOCATE, then pbAttrBuffer is converted to a pointer to a byte pointer, and receives the address of a block of memory containing the attribute. This block of memory must be deallocated with SCardFreeMemory.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardGetAttrib is a direct card access function. For a description of other direct access functions, see Direct Card Access Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardConnect, SCardFreeMemory, SCardSetAttrib


SCardGetProviderId

The SCardGetProviderId function returns the identifier (GUID) of the primary service provider for a given card.

The caller supplies the name of a smart card (previously introduced to the system) and receives the registered identifier of the primary service provider GUID, if one exists.

LONG SCardGetProviderId(
  IN SCARDCONTEXT hContext,
  IN LPCTSTR szCard,
  OUT LPGUID pguidProviderId
);

Parameters

hContext
Supplies the handle that identifies the resource manager context for the query. The resource manager context can be set by a previous call to SCardEstablishContext, or set to NULL if the query is not directed towards a specific context.
szCard
Supplies the name of the card defined to the system.
pguidInterfaces
Receives the identifier (GUID) of the primary service provider. This provider may be activated via COM, and will supply access to other services in the card.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardGetProviderId is a database query function. For a description of other database query functions, see Smart Card Database Query Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardListCards, SCardListInterfaces, SCardListReaderGroups, SCardListReaders


SCardGetStatusChange

The SCardGetStatusChange function blocks execution until the current availability of the cards in a specific set of readers changes.

The caller supplies a list of readers to be monitored via an SCARD_READERSTATE array and the maximum amount of time (in seconds) that it is willing to wait for an action to occur on one of the listed readers. The function returns when there is a change in availability, having filled in the dwEventState members of the rgReaderStates parameter appropriately.

LONG SCardGetStatusChange(
  IN SCARDCONTEXT hContext,
  IN DWORD dwTimeout,
  IN OUT LPSCARD_READERSTATE rgReaderStates,
  IN DWORD cReaders
);

Parameters

hContext
Supplies the handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext.
dwTimeOut
Supplies the maximum amount of time (in milliseconds) to wait for an action. A value of zero implies a value of INFINITE, dwTimeOut will never timeout.
rgReaderStates
Supplies an array of SCARD_READERSTATE structures that specify the readers to watch, and receives the result.
cReaders
Supplies the number of elements in the rgReaderStates array.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardGetStatusChange is a smart card tracking function. For a description of other tracking functions, see Smart Card Tracking Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardCancel, SCardEstablishContext, SCardLocateCards, SCARD_READERSTATE


SCardIntroduceCardType

The SCardIntroduceCardType function introduces a smart card to the smart card subsystem (for the active user) by adding it to the smart card database.

LONG SCardIntroduceCardType(
  IN SCARDCONTEXT hContext,
  IN LPCTSTR szCardName,
  IN LPGUID pguidPrimaryProvider,
  IN LPGUID rgguidInterfaces,
  IN DWORD dwInterfaceCount,
  IN LPCBYTE pbAtr,
  IN LPCBYTE pbAtrMask,
  IN DWORD cbAtrLen
);

Parameters

hContext
Supplies the handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext.
szCardName
Supplies the name by which the user can recognize the card.
pguidPrimaryProvider
Points to the identifier (GUID) for the smart card's primary service provider.
rgguidInterfaces
Supplies an array of identifiers (GUIDs) that identify the interfaces supported by the smart card.
dwInterfaceCount
Supplies the number of identifiers in the rgguidInterfaces array.
pbAtr
Supplies an ATR string that can be used for matching purposes when querying the smart card database (see SCardListCards). The length of this string is determined by normal ATR parsing.
pbAtrMask
Supplies an optional bitmask to use when comparing the ATRs of smart cards to the ATR supplied in pbAtr. If this value is non-NULL, it must point to a string of bytes the same length as the ATR string supplied in pbAtr. When a given ATR string 'A' is compared to the ATR supplied in pbAtr, it matches if and only if A & M = pbAtr, where M is the supplied mask, and & represents bitwise logical AND.
cbAtrLen
Supplies the length of the ATR and optional ATR Mask. If this value is zero, then the length of the ATR is determined by normal ATR parsing

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardIntroduceCardType is a database management function. For a description of other database management functions, see Smart Card Database Management Functions.

To remove a smart card, see SCardForgetCardType.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardForgetCardType, SCardIntroduceReader, SCardIntroduceReaderGroup, SCardListCards


SCardIntroduceReader

The SCardIntroduceReader function introduces a new name for an existing smart card reader.

Note Smart card readers are automatically introduced to the system.

LONG SCardIntroduceReader(
  IN SCARDCONTEXT hContext,
  IN LPCTSTR szReaderName,
  IN LPCTSTR szDeviceName
);

Parameters

hContext
Supplies the handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext.
szReaderName
Supplies the friendly name to be assigned to the reader.
szDeviceName
Supplies the system name of the smart card reader device. For example, "SCReader0".

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardIntroduceReader is a database management function. For a description of other database management functions, see Smart Card Database Management Functions.

To remove a reader, see SCardForgetReader.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardIntroduceCardType, SCardIntroduceReaderGroup, SCardForgetReader


SCardIntroduceReaderGroup

The SCardIntroduceReaderGroup function introduces a reader group to the smart card subsystem. However, the reader group is not created until the group is specified when adding a reader to the smart card database.

LONG SCardIntroduceReaderGroup(
  IN SCARDCONTEXT hContext,
  IN LPCTSTR szGroupName
);

Parameters

hContext
Supplies the handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext.
szGroupName
Supplies the friendly name to be assigned to the new reader group.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardIntroduceReaderGroup is a database management function. For a description of other database management functions, see Smart Card Database Management Functions.

To remove a reader group, see SCardForgetReaderGroup.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardIntroduceCardType, SCardIntroduceReader, SCardForgetReaderGroup


SCardListCards

The SCardListCards function searches the smart card database and provides a list of named cards previously introduced to the system by the user.

The caller specifies an ATR string, a set of interface identifiers (GUIDs), or both. If both an ATR string and an identifier array are supplied, the cards returned will match the ATR string supplied and support the interfaces specified.

LONG SCardListCards(
  IN SCARDCONTEXT hContext,
  IN LPCBYTE pbAtr,
  IN LPCGUID rgguidInterfaces,
  IN DWORD cguidInterfaceCount,
  OUT LPTSTR mszCards,
  IN OUT LPDWORD pcchCards
);

Parameters

hContext
Supplies the handle that identifies the resource manager context for the query. The resource manager context can be set by a previous call to SCardEstablishContext, or set to NULL if the query is not directed towards a specific context.
pbAtr
Supplies the address of an ATR string to compare to known cards, or NULL if no ATR matching is to be performed.
rgguidInterfaces
Supplies an array of identifiers (GUIDs), or NULL if no interface matching is to be performed. When an array is supplied, a card name will be returned only if all the specified identifiers are supported by the card.
cguidInterfaceCount
Supplies the number of entries in the rgguidInterfaces array. If rgguidInterfaces is NULL, then this value is ignored.
mszCards
Receives a multi-string that lists the smart cards found. If this value is NULL, SCardListCards ignores the buffer length supplied in pcchCards, returning the length of the buffer that would have been returned if this parameter had not been NULL to pcchCards and a success code.
pcchCards
Supplies the length of the mszCards buffer in characters, and receives the actual length of the multi-string structure, including all trailing Null characters. If the buffer length is specified as SCARD_AUTOALLOCATE, then mszCards is converted to a pointer to a string pointer, and receives the address of a block of memory containing the multi-string structure. This block of memory must be deallocated with SCardFreeMemory.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

To return all smart cards introduced to the subsystem, set pbAtr and rgguidInterfaces to NULL.

SCardListCards is a database query function. For a description of other database query functions, see Smart Card Database Query Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardFreeMemory, SCardGetProviderId, SCardListInterfaces, SCardListReaderGroups, SCardListReaders


SCardListInterfaces

The SCardListInterfaces function provides a list of interfaces supplied by a given card.

The caller supplies the name of a smart card previously introduced to the subsystem, and receives the list of interfaces supported by the card.

LONG SCardListInterfaces(
  IN SCARDCONTEXT hContext,
  IN LPCTSTR szCard,
  OUT LPGUID pguidInterfaces,
  IN OUT LPDWORD pcguidInterfaces
);

Parameters

hContext
Supplies the handle that identifies the resource manager context for the query. The resource manager context can be set by a previous call to SCardEstablishContext, or set to NULL if the query is not directed towards a specific context.
szCard
Supplies the name of the smart card already introduced to the smart card subsystem.
pguidInterfaces
Receives an array of interface identifiers (GUIDs) that indicate the interfaces supported by the smart card. If this value is NULL, SCardListInterfaces ignores the array length supplied in pcguidInterfaces, returning the size of the array that would have been returned if this parameter had not been NULL to pcguidInterfaces and a success code.
pcguidInterfaces
Supplies the size of the pguidInterfaces array, and receives the actual size of the returned array. If the array size is specified as SCARD_AUTOALLOCATE, then pguidInterfaces is converted to a pointer to a GUID pointer, and receives the address of a block of memory containing the array. This block of memory must be deallocated with SCardFreeMemory.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardListInterfaces is a database query function. For a description of other database query functions, see Smart Card Database Query Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardFreeMemory, SCardGetProviderId, SCardListCards, SCardListReaderGroups, SCardListReaders


SCardListReaderGroups

The SCardListReaderGroups function provides the list of reader groups that have previously been introduced to the system.

LONG SCardListReaderGroups(
  IN SCARDCONTEXT hContext,
  OUT LPTSTR mszGroups,
  IN OUT LPDWORD pcchGroups
);

Parameters

hContext
Supplies the handle that identifies the resource manager context for the query. The resource manager context can be set by a previous call to SCardEstablishContext, or set to NULL if the query is not directed towards a specific context.
mszGroups
Receives a multi-string that lists the reader groups defined to the system and available to the current user on the current terminal. If this value is NULL, SCardListReaderGroups ignores the buffer length supplied in pcchGroups, writes the length of the buffer that would have been returned if this parameter had not been NULL to pcchGroups, and returns a success code.
pcchGroups
Supplies the length of the mszGroups buffer in characters, and receives the actual length of the multi-string structure, including all trailing Null characters. If the buffer length is specified as SCARD_AUTOALLOCATE, then mszGroups is converted to a pointer to a string pointer, and receives the address of a block of memory containing the multi-string structure. This block of memory must be deallocated with SCardFreeMemory.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

The group SCard$DefaultReaders is returned only if it contains at least one reader.

The group SCard$AllReaders cannot be returned, since it only exists implicitly.

SCardListReaderGroups is a database query function. For a description of other database query functions, see Smart Card Database Query Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardFreeMemory, SCardGetProviderId, SCardListCards, SCardListInterfaces, SCardListReaders


SCardListReaders

The SCardListReaders function provides the list of readers within a set of named reader groups, eliminating duplicates.

The caller supplies a list reader groups, and receives the list of readers within the named groups. Unrecognized group names are ignored.

LONG SCardListReaders(
  IN SCARDCONTEXT hContext,
  IN LPCTSTR mszGroups,
  OUT LPTSTR mszReaders,
  IN OUT LPDWORD pcchReaders
);

Parameters

hContext
Supplies the handle that identifies the resource manager context for the query. The resource manager context can be set by a previous call to SCardEstablishContext, or set to NULL if the query is not directed towards a specific context.
mszGroups
Supplies the names of the reader groups defined to the system, as a multi-string. Use a NULL value to list all readers in the system (that is, the SCard$AllReaders group).
mszReaders
Receives a multi-string that list the card readers within the supplied reader groups. If this value is NULL, SCardListReaders ignores the buffer length supplied in pcchReaders, writes the length of the buffer that would have been returned if this parameter had not been NULL to pcchReaders, and returns a success code.
pcchReaders
Supplies the length of the mszReaders buffer in characters, and receives the actual length of the multi-string structure, including all trailing Null characters. If the buffer length is specified as SCARD_AUTOALLOCATE, then mszReaders is converted to a pointer to a string pointer, and receives the address of a block of memory containing the multi-string structure. This block of memory must be deallocated with SCardFreeMemory.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardListReaders is a database query function. For a description of other database query functions, see Smart Card Database Query Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardFreeMemory, SCardGetProviderId, SCardListCards, SCardListInterfaces, SCardListReaderGroups


SCardLocateCards

The SCardLocateCards function searches the readers listed in the lpReaderStates parameter for a card with an ATR string that matches one of the card names specified in mszCards, returning immediately with the result.

LONG SCardLocateCards(
  IN SCARDCONTEXT hContext,
  IN LPCTSTR mszCards,
  IN OUT LPSCARD_READERSTATE rgReaderStates,
  IN DWORD cReaders
);

Parameters

hContext
Supplies the handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext.
mszCards
Supplies a multi-string that contains the names of the cards to search for.
rgReaderStates
Supplies an array of SCARD_READERSTATE structures that specify the readers to search, and receives the result.
cReaders
Supplies the number of elements in the rgReaderStates array.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

If no matching cards are found, the calling application may use SCardGetStatusChange to wait for card availability changes.

SCardLocateCards is a smart card tracking function. For a description of other tracking functions, see Smart Card Tracking Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardCancel, SCardEstablishContext, SCardGetStatusChange, SCARD_READERSTATE


SCardLocateDialog

This SCardLocateDialog function initiates a search for the smart card according to the constraints specified in the supplied SCARDLOCATECONTROL structure.

LONG SCardLocateDialog(
  IN OUT LPSCARD_LOCATECONTROL pDlgCtrl
);

Parameters

pDlgCtrl
This supplies the address of the SCARDLOCATECONTROL structure constraining the smart card search.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).


SCardReconnect

The SCardReconnect function reestablishes an existing connection between the calling application and a smart card. This function moves a card handle from direct access to general access, or acknowledges and clears an error condition that is preventing further access to the card.

LONG SCardReconnect(
  IN SCARDHANDLE hCard,
  IN DWORD dwShareMode,
  IN DWORD dwPreferredProtocols,
  IN DWORD dwInitialization,
  OUT LPDWORD pdwActiveProtocol
);

Parameters

hCard
Supplies the reference value obtained from a previous call to SCardConnect.
dwShareMode
Supplies a flag that indicates whether other applications may form connections to this card. Possible values are:
Value | Meaning
SCARDSHARE_SHARED | This application will share this card with other applications.
SCARDSHARE_EXCLUSIVE | This application will not share this card with other applications.

dwPreferredProtocols
Supplies a bit mask of acceptable protocols for this connection. Possible values, which may be combined with the OR operation, are:
Value | Meaning
SCARD_PROTOCOL_T0 | T=0 is an acceptable protocol.
SCARD_PROTOCOL_T1 | T=1 is an acceptable protocol.

dwInitialization
Indicates what kind of initialization should be performed on the card. Possible values are:
Value | Meaning
SCARD_LEAVE_CARD | Don't do anything special on reconnect.
SCARD_RESET_CARD | Reset the card (Warm Reset).
SCARD_UNPOWER_CARD | Power down the card and reset it (Cold Reset).

pdwActiveProtocol
Receives a flag that indicates the established active protocol. Possible values are:
Value | Meaning
SCARD_PROTOCOL_T0 | T=0 is the active protocol.
SCARD_PROTOCOL_T1 | T=1 is the active protocol.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardReconnect is a smart card and reader access function. For a description of other access functions, see Smart Card and Reader Access Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardConnect, SCardDisconnect


SCardReleaseContext

The SCardReleaseContext function closes an established resource manager context, freeing any resources allocated under that context, including SCARDHANDLE objects and memory allocated using the SCARD_AUTOALLOCATE length designator.

LONG SCardReleaseContext(
  IN SCARDCONTEXT hContext
);

Parameters

hContext
Supplies the handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext


SCardRemoveReaderFromGroup

The SCardRemoveReaderFromGroup function removes a reader from an existing reader group. This function has no affect on the reader or reader group.

LONG SCardRemoveReaderFromGroup(
  IN SCARDCONTEXT hContext,
  IN LPCTSTR szReaderName,
  IN LPCTSTR szGroupName
);

Parameters

hContext
Supplies the handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext.
szReaderName
Supplies the friendly name of the reader to be removed.
szGroupName
Supplies the friendly name of the group from which the reader should be removed.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

When the last reader is removed from a group, the group is automatically deleted.

SCardRemoveReaderFromGroup is a database management function. For a description of other database management functions, see Smart Card Database Management Functions.

To add a reader to a reader group, see SCardAddReaderToGroup.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardAddReaderToGroup, SCardForgetCardType, SCardForgetReader, SCardForgetReaderGroup


SCardSetAttrib

The SCardSetAttrib function sets the given reader attribute for the given handle. It does not affect the state of the reader, reader driver, or smart card. Not all attributes are supported by all readers (nor can they be set at all times) as many of the attributes are under direct control of the transport protocol.

LONG SCardSetAttrib(
  IN SCARDHANDLE hCard,
  IN dwAttrId,
  IN LPCBYTE pbAttr,
  IN DWORD pbAttrLength
);

Parameters

hCard
Supplies the reference value returned from SCardConnect.
dwAttrId
Supplies the identifier for the attribute to get.
pbAttr
Points to a buffer that supplies the attribute whose ID is supplied in dwAttrId.
cbAttrLength
Supplies the length (in bytes) of the attribute value in the pbAttr buffer.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardSetAttrib is a direct card access function. For a description of other direct access functions, see Direct Card Access Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardConnect, SCardGetAttrib


SCardStatus

The SCardStatus function provides the current status of a smart card in a reader. You can call it any time after a successful call to SCardConnect and before a successful call to SCardDisconnect. It does not affect the state of the reader or reader driver.

LONG SCardStatus(
  IN SCARDHANDLE hCard,
  OUT LPTSTR  mszReaderNames,
  IN OUT LPDWORD pcchReaderLen,
  OUT LPDWORD pdwState,
  OUT LPDWORD pdwProtocol,
  OUT LPBYTE pbAtr,
  OUT LPDWORD pbcAtrLen
);

Parameters

hCard
This is the reference value returned from SCardConnect.
mszReaderNames
Receives a list of friendly names (multi-string) by which the currently connected reader is known.
pcchReaderLen
On input, supplies the length of the mszReaderNames buffer

On output, receives the actual length (in characters) of the reader name list, including the trailing NULL character.

pdwState
Receives the current state of the smart card in the reader. Upon success, it receives one of the following state indicators:
Value | Meaning
SCARD_ABSENT | There is no card in the reader.
SCARD_PRESENT | There is a card in the reader, but it has not been moved into position for use.
SCARD_SWALLOWED | There is a card in the reader in position for use. The card is not powered.
SCARD_POWERED | Power is being provided to the card, but the reader driver is unaware of the mode of the card.
SCARD_NEGOTIABLEMODE | The card has been reset and is awaiting PTS negotiation.
SCARD_SPECIFICMODE | The card has been reset and specific communication protocols have been established.

pdwProtocol
Receives the current protocol, if any. The returned value is meaningful only if the returned value of pdwState is SCARD_SPECIFICMODE. Possible returned values are the following:
Value | Meaning
SCARD_PROTOCOL_RAW | The Raw Transfer protocol is in use.
SCARD_PROTOCOL_T0 | The ISO 7816/3 T=0 protocol is in use.
SCARD_PROTOCOL_T1 | The ISO 7816/3 T=1 protocol is in use.

pbAtr
Points to a 32-byte buffer that receives the ATR string from the currently inserted card, if available.
pbcAtrLen
Points to a DWORD to receive the number of bytes in the ATR string (32 bytes maximum).

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardStatus is a smart card and reader access function. For a description of other access functions, see Smart Card and Reader Access Functions.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardConnect, SCardDisconnect


SCardTransmit

The SCardTransmit function sends a service request to the smart card, and expects to receive data back from the card.

LONG SCardTransmit(
  IN SCARDHANDLE hCard,
  IN LPCSCARD_I0_REQUEST pioSendPci,
  IN LPCBYTE pbSendBuffer,
  IN DWORD cbSendLength,
  IN OUT LPSCARD_IO_REQUEST pioRecvPci,
  OUT LPBYTE pbRecvBuffer,
  IN OUT LPDWORD pcbRecvLength
);

Parameters

hCard
Supplies the reference value returned from SCardConnect.
pioSendPci
Pointer to the protocol header structure for the instruction. This buffer is in the format of an SCARD_IO_REQUEST structure, followed by the specific protocol control information.

For the T=0, T=1, and Raw protocols, the PCI structure is constant. The smart card subsystem supplies a global T=0, T=1, or Raw PCI structure, which you can reference by using the symbols SCARD_PCI_T0, SCARD_PCI_T1, and SCARD_PCI_RAW respectively.

pbSendBuffer
Pointer to the actual data to be written to the card.

T=0 Note For T=0, the data parameters are placed into the pbSendBuffer according to the following structure:

struct {
    BYTE
        bCla,   // The instruction class
        bIns,   // The instruction code
        bP1,    // Parameter to the instruction
        bP2,    // Parameter to the instruction
        bP3;    // Size of I/O Transfer
} CmdBytes;

Members

bCla
The T=0 instruction class
bIns
An instruction code in the T=0 instruction class
bP1, bP2
Reference codes completing the instruction code
bP3
The number of data bytes which are to be transmitted during the command, per ISO 7816-4, Section 8.2.1.

The data sent to the card should immediately follow the send buffer. In the special case where no data is sent to the card and no data is expected in return, bP3 is not sent.

cbSendLength
Supplies the length (in bytes)of the pbSendBuffer parameter.

T=0 Note For T=0, in the special case where no data is sent to the card and no data expected in return, this length must reflect that the bP3 member is not being sent: the length should be sizeof(CmdBytes) – sizeof(BYTE).

pioRecvPci
Pointer to the protocol header structure for the instruction, followed by a buffer in which to receive any returned protocol control information (PCI) specific to the protocol in use. This parameter may be NULL if no returned PCI is desired.
pbRecvBuffer
Pointer to any data returned from the card.

T=0 Note For T=0, the data is immediately followed by the SW1 and SW2 status bytes. If no data is returned from the card, then this buffer will only contain the SW1 and SW2 status bytes.

pcbRecvLength
Supplies the length of the pbRecvBuffer parameter (in bytes) and receives the actual number of bytes received from the smart card.

T=0 Note For T=0, the receive buffer must be at least two bytes long, in order to receive the SW1 and SW2 status bytes.

Return Values

If the function… | The return value is…
Succeeds | SCARD_S_SUCCESS.
Fails | An error code (see Error Codes for a list of all error codes).

Remarks

SCardTransmit is a smart card and reader access function. For a description of other access functions, see Smart Card and Reader Access Functions.

T=0 Protocol Remarks

For the T=0 protocol, the data received back are the SW1 and SW2 status codes, possibly preceded by response data. The following paragraphs provide information on the send and receive buffers used to transfer data and issue a command.

Sending Data to the Card
To send n bytes of data to the card, where n>0, the send and receive buffers must be formatted as follows.

The first four bytes of the pbSendBuffer buffer contain the CLA, INS, P1, and P2 values for the T=0 operation. The fifth byte shall be set to n: the size (in bytes) of the data to be transferred to the card. The next n bytes shall contain the data to be sent to the card.

The cbSendLength parameter shall be set to the size of the T=0 header information (CLA, INS, P1 and P2) plus a byte containing the length of the data to be transferred (n), plus the size of data to be sent. In this example, this is n+5.

The pbRecvBuffer will receive the SW1 and SW2 status codes from the operation.

The pcbRecvLength should be at least 2, and will be set to 2 upon return.

Obtaining Data from the Card
To receive n>0 bytes of data from the card, the send and receive buffers must be formatted as follows.

The first four bytes of the pbSendBuffer buffer contain the CLA, INS, P1, and P2 values for the T=0 operation. The fifth byte shall be set to n: the size (in bytes) of the data to be transferred from the card. If 256 bytes are to be transferred from the card, then this byte shall be set to zero.

The cbSendLength parameter shall be set to 5, the size of the T=0 header information.

The pbRecvBuffer will receive the data returned from the card, immediately followed by the SW1 and SW2 status codes from the operation.

The pcbRecvLength should be at least n+2, and will be set to n+2 upon return.

Issuing a Command Without Exchanging Data
To issue a command to the card that does not involve the exchange of data (either sent or received), the send and receive buffers must be formatted as follows.

The pbSendBuffer buffer shall contain the CLA, INS, P1, and P2 values for the T=0 operation. The P3 value is not sent. (This is to differentiate the header from the case where 256 bytes are expected to be returned.)

The cbSendLength parameter shall be set to 4, the size of the T=0 header information (CLA, INS, P1, and P2).

The pbRecvBuffer will receive the SW1 and SW2 status codes from the operation.

The pcbRecvLength should be at least 2, and will be set to 2 upon return.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardConnect, SCARD_IO_REQUEST


Smart Card Structures

The Smart Card SDK provides the following structures.

Use… | To…
OPENCARDNAME | Provide information used by the GetOpenCardName function.
SCARD_IO_REQUEST | Begin a protocol control information structure.
SCARD_READERSTATE | Track smart cards within a reader.


OPENCARDNAME

The OPENCARDNAME structure contains the information that the GetOpenCardName function uses to initialize a smart card common dialog.

typedef struct tagOCNA {
    DWORD           dwStructSize;
    HWND            hwndOwner;
    SCARDCONTEXT    hSCardContext;
    LPTSTR          lpstrGroupNames;
    DWORD           nMaxGroupNames;
    LPTSTR          lpstrCardNames;
    DWORD           nMaxCardNames;
    LPGUID          rgguidInterfaces;
    DWORD           cguidInterfaces;
    LPTSTR          lpstrRdr;
    DWORD           nMaxRdr;
    LPTSTR          lpstrCard;
    DWORD           nMaxCard;
    LPCTSTR         lpstrTitle;
    DWORD           dwFlags;
    LPVOID          pvUserData;
    DWORD           dwShareMode;
    DWORD           dwPreferredProtocols;
    DWORD           dwActiveProtocol;
    LPOCNCONNPROCA  lpfnConnect;
    LPOCNCHKPROC    lpfnCheck;
    LPOCNDSCPROC    lpfnDisconnect;
    SCARDHANDLE     hCardHandle;
} OPENCARDNAME, *LPOPENCARDNAME;;

Members

dwStructSize
Specifies the length of the structure, in bytes. Must not be NULL.
hwndOwner
Identifies the window that owns the dialog box. This member can be any valid window handle, or it can be NULL for desktop default.
hSCardContext
Context used for communication with the smart card resource manager. Call SCardEstablishContext to set the resource manager context and SCardReleaseContext to release it. Must not be NULL.
lpstrGroupNames
Points to a buffer containing null-terminated group name strings. The last string in the buffer must be terminated by two NULL characters. Each string is the name of a group of cards that is to be included in the search. If lpstrGroupNames is NULL, the default group (Scard$DefaultReaders) is searched.
nMaxGroupNames
Maximum number of bytes (ANSI version) or characters (UNICODE version) in the lpstrGroupNames string.
lpstrCardNames
Points to a buffer containing null-terminated card name strings. The last string in the buffer must be terminated by two NULL characters. Each string is the name of a card that is to be located.
nMaxCardNames
Maximum number of bytes (ANSI version) or characters (UNICODE version) in the lpstrCardNames string.
rgguidInterfaces
An array of GUIDs identifying the interfaces required. NULL for this release (RFU).
cguidInterfaces
The number of interfaces in the rgguidInterfaces array. NULL for this release (RFU).
lpstrRdr
If the card is located, the lpstrRdr buffer contains the name of the reader that contains the located card. The buffer should be at least 256 characters long.
nMaxRdr
Specifies the size, in bytes (ANSI version) or characters (UNICODE version), of the buffer pointed to by lpstrRdr. If the buffer is too small to contain the reader information, GetOpenCardName returns SCARD_E_NO_MEMORY and the required size of the buffer pointed to by lpstrRdr.
lpstrCard
If the card is located, the lpstrCard buffer contains the name of the located card. The buffer should be at least 256 characters long.
nMaxCard
Specifies the size, in bytes (ANSI version) or characters (UNICODE version), of the buffer pointed to by lpstrCard. If the buffer is too small to contain the card information, GetOpenCardName returns SCARD_E_NO_MEMORY and the required size of the buffer in nMaxCard.
lpstrTitle
Points to a string to be placed in the title bar of the dialog box. If this member is NULL, the system uses the default title (that is, "Select Card:").
dwFlags
A set of bit flags you can use to initialize the dialog box. When the dialog box returns, it sets these flags to indicate the user's input. This member can be a combination of the following flags:
Flag | Meaning
SC_DLG_MINIMAL_UI | Displays the dialog only if the card being searched for by the calling application is not located and available for use in a reader. This allows the card to be found, connected (either through the internal dialog mechanism or the user callback functions), and returned to the calling application.
SC_DLG_NO_UI | Force no display of the common dialog UI, regardless of search outcome.
SC_DLG_FORCE_UI | Force display of the common dialog UI, regardless of the search outcome.

pvUserData
A void pointer to user data. This pointer is passed back to the caller on the Connect, Check, and Disconnect routines.
dwShareMode
If lpfnConnect is not NULL, the dwShareMode and dwProtocols members are ignored. If lpfnConnect is NULL and dwShareMode is non-zero, then an internal call is made to SCardConnect using dwShareMode and dwProtocol as the dwShareMode and dwPreferredProtocols parameters. If the connect succeeds, hCardHandle is set to the handle returned by SCardConnect. If lpfnConnect is NULL and dwShareMode is zero, the common dialog returns hCardHandle as NULL.
dwPreferredProtocols
Used for internal connection as described in dwShareMode.
dwActiveProtocol
Returns the actual protocol in use when the dialog makes a connection to a card.
lpfnConnect
Pointer to the caller's card connect routine. If the caller needs to perform additional processing to connect to the card, this function pointer is set to the user's connect function. If the connect function is successful, the card is left connected and initialized, and the card handle is returned.

The prototype for the connect routine is

Connect(
  hSCardContext,  // the card context passed in the parameter block
  szReader,       // the name of the reader
  mszCards,       // multistring containing the possible card names in the reader
  pvUserData      // pointer to user data passed in parameter block
);
lpfnCheck
Pointer to the caller's card verify routine. If no special card verification is required, this pointer is NULL.

If the card is rejected by the verify routine, FALSE is returned and the card will be disconnected, as indicated by lpfnDisconnect.

If the card is accepted by the verify routine, TRUE is returned. When the user accepts the card, all other cards currently connected will be disconnected, as indicated by lpfnDisconnect, and this card will be returned as the located card. The located card will remain connected.

The prototype for the check routine is

Check(
  hSCardContext,  //  the card context passed in the parameter block
  hCard,          //  card handle
  pvUserData      //  pointer to user data passed in the parameter block
);
lpfnDisconnect
Pointer to the caller's card disconnect routine.

The prototype for the disconnect routine is

Disconnect(
  hSCardContext,  //  the card context passed in the parameter block
  hCard,          //  card handle
  pvUserData      //  pointer to user data passed in the parameter block
);

Note When using lpfnConnect, lpfnCheck, and lpfnDisconnect, all three callback procedures should be present. Using these callbacks allows further verification that the calling application has found the appropriate card. This is the best way to ensure the appropriate card is selected.

hCardHandle
Handle of the connected card (either through an internal dialog connect or an lpfnConnect callback.)

See Also

Error Codes, GetOpenCardName, SCardConnect, SCardEstablishContext, SCardReleaseContext


SCARD_IO_REQUEST

The SCARD_IO_REQUEST structure begins a protocol control information structure. Any protocol-specific information then immediately follows this structure. The entire length of the structure must be aligned with the underlying hardware architecture word size. For example, in Win32 the length of any PCI information must be a multiple of 4 bytes so that it aligns on a 32-bit boundary.

typedef struct {
    DWORD           dwProtocol
    DWORD           cbPciLength;
} SCARD_IO_REQUEST;

Members

dwProtocol
Identifies the protocol in use.
cbPciLength
Supplies the length, in bytes, of the SCARD_IO_REQUEST structure plus any following PCI-specific information.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winsmcard.h.
Import Library: Link with winscard.lib.

See Also

SCardTransmit


SCARD_READERSTATE

The SCARD_READERSTATE structure is used by functions for tracking smart cards within readers.

typedef struct {
    LPCTSTR szReader;       // reader name
    LPVOID  pvUserData;     // user defined data
    DWORD   dwCurrentState; // current state of reader at the
                            // time of the call
    DWORD   dwEventState;   // state of reader after a state change
    DWORD   cbAtr;          // Number of bytes in the returned ATR
    BYTE    rgbAtr[36];     // ATR of inserted card
                            // (with extra alignment bytes)
} SCARD_READERSTATE;typedef SCARD_READERSTATE
  *PSCARD_READERSTATE, *LPSCARD_READERSTATE;

Members

szReader
Points to the name of the reader being monitored.
pvUserData
Not used by the smart card subsystem. Used by the application.
dwCurrentState
Supplies the current state of the reader, as seen by the application. This field can take on any of the following values, in combination, as a bit mask:
Value | Meaning
SCARD_STATE_UNAWARE | The application is unaware of the current state, and would like to know. The use of this value results in an immediate return from state transition monitoring services. This is represented by all bits set to zero.
SCARD_STATE_IGNORE | The application is not interested in this reader, and it should not be considered during monitoring operations. If this bit value is set, all other bits are ignored.
SCARD_STATE_UNAVAILABLE | The application believes that this reader is not available for use. If this bit is set, then all the following bits are ignored.
SCARD_STATE_EMPTY | The application believes that there is not card in the reader. If this bit is set, all the following bits are ignored.
SCARD_STATE_PRESENT | The application believes that there is a card in the reader.
SCARD_STATE_ATRMATCH | The application believes that there is a card in the reader with an ATR matching one of the target cards. If this bit is set, SCARD_STATE_PRESENT is assumed. This bit has no meaning to SCardGetStatusChange beyond SCARD_STATE_PRESENT.
SCARD_STATE_EXCLUSIVE | The application believes that the card in the reader is allocated for exclusive use by another application. If this bit is set, SCARD_STATE_PRESENT is assumed.
SCARD_STATE_INUSE | The application believes that the card in the reader is in use by one or more other applications, but may be connected to in shared mode. If this bit is set, SCARD_STATE_PRESENT is assumed.
SCARD_STATE_MUTE | The application believes that there is an unresponsive card in the reader.

dwEventState
Receives the current state of the reader, as known by the smart card resource manager. This field can take on any of the following values, in combination, as a bit mask:
Value | Meaning
SCARD_STATE_IGNORE | This reader should be ignored.
SCARD_STATE_CHANGED | There is a difference between the state believed by the application, and the state known by the resource manager. When this bit is set, the application may assume a significant state change has occurred on this reader.
SCARD_STATE_UNKNOWN | The given reader name is not recognized by the resource manager. If this bit is set, then SCARD_STATE_CHANGED and SCARD_STATE_IGNORE will also be set.
SCARD_STATE_UNAVAILABLE | The actual state of this reader is not available. If this bit is set, then all the following bits are clear.
SCARD_STATE_EMPTY | There is no card in the reader. If this bit is set, all the following bits will be clear.
SCARD_STATE_PRESENT | There is a card in the reader.
SCARD_STATE_ATRMATCH | There is a card in the reader with an ATR matching one of the target cards. If this bit is set, SCARD_STATE_PRESENT will also be set. This bit is only returned on the SCardLocateCards function.
SCARD_STATE_EXCLUSIVE | The card in the reader is allocated for exclusive use by another application. If this bit is set, SCARD_STATE_PRESENT will also be set.
SCARD_STATE_INUSE | The card in the reader is in use by one or more other applications, but may be connected to in shared mode. If this bit is set, SCARD_STATE_PRESENT will also be set.
SCARD_STATE_MUTE | There is an unresponsive card in the reader.

cbAtr
The number of bytes in the returned ATR.
rgbAtr
The ATR of the inserted card, with extra alignment bytes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in winscard.h.
Import Library: Link with winscard.lib.

See Also

SCardGetStatusChange, SCardLocateCards


Smart Card SDK Interfaces

The Smart Card SDK provides the following COM interfaces. (The methods for a specific interface are listed in the TOC and on the reference page for that interface.)

Call… | To…
ISCard | Open and manage a connection to a smart card.
ISCardCmd | Construct and manage a smart card Application Protocol Data Unit (APDU).
ISCardLocate | Locate a smart card.
ISCardDatabase | Perform smart card resource manager database operations.
ISCardISO7816 | Construct an APDU command.
ISCardAuth | Authenticate an application, smart card, or user.
ISCardFileAccess | Perform common file services such as locating, selecting, reading, writing, creating, and deleting files
ISCardManage | Manage the smart card system.
ISCardVerify | Verify or change card holder verification (CHV) policy.


ISCard

The ISCard interface lets you open and manage a connection to a smart card. Each connection to a card requires a single, corresponding instance of the ISCard interface.

The smart card resource manager must be available whenever an instance of ISCard is created. If this service is unavailable, creation of the interface will fail.

The following example shows a typical use of the ISCard interface. The ISCard interface is used to connect to the smart card, submit a transaction, and release the smart card.

To submit a transaction to a specific card
  1. Create an ISCard interface.
  2. Attach to a smart card by specifying a smart card reader or by using a previously established, valid handle.
  3. Create transaction commands with ISCardCmd, and ISCardISO7816 smart card interfaces.
  4. Use ISCard to submit the transaction commands for processing by the smart card.
  5. Use ISCard to release the smart card.
  6. Release the ISCard interface.

Methods

Call… | To…
get_Atr | Retrieve the ATR string of the smart card.
get_CardHandle | Retrieve the handle for the connected smart card.
get_Context | Retrieve the current resource manager context handle.
get_Protocol | Retrieve the identifier of the protocol currently in use on the smart card.
get_Status | Retrieve the current state that the smart card is in.
AttachByHandle | Attach an object to an open and configured smart card handle.
AttachByReader | Open the smart card in the named reader.
Detach | Close the open connection to the smart card.
LockSCard | Claim exclusive access to the smart card.
ReAttach | Reset and reinitialize the smart card.
Transaction | Execute a write and read operation on the smart card command (APDU) object.
UnlockScard | Release exclusive access to the smart card.


ISCard::get_Atr

The get_Atr method retrieves an ATR string of the smart card.

HRESULT get_Atr(
  LPBYTEBUFFER *ppAtr
);

Parameters

ppAtr
[out, retval] Pointer to a byte buffer in the form of an IStream that will contain the ATR string on return.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | ppAtr is invalid.
E_POINTER | A bad pointer was passed in ppAtr.
E_OUTOFMEMORY | Memory to satisfy the request is unavailable.

Remarks

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

get_CardHandle, get_Context, get_Protocol, get_Status, ISCard


ISCard::get_CardHandle

The get_CardHandle method retrieves the handle for a connected smart card. Returns (*pHandle) == NULL if not connected.

HRESULT get_CardHandle(
  HSCARD *pHandle
);

Parameters

pHandle
[out, retval] Pointer to the card handle on return.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pHandle is invalid.
E_POINTER | A bad pointer was passed in pHandle.

Remarks

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

get_Atr, get_Context, get_Protocol, get_Status, ISCard


ISCard::get_Context

The get_Context method retrieves the current resource manager context handle. Returns (*pContext) == NULL if no context has been established.

HRESULT get_Context(
  HSCARDCONTEXT *pContext
);

Parameters

pContext
[out, retval] Pointer to the context handle on return.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pContext is invalid.
E_POINTER | A bad pointer was passed in pContext.

Remarks

The resource manager context is set by calling the smart card function SCardEstablishContext.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

get_Atr, get_CardHandle, get_Protocol, get_Status, ISCard, SCardEstablishContext


ISCard::get_Protocol

The get_Protocol retrieves the identifier of the protocol currently in use on the smart card.

HRESULT get_Protocol(
  SCARD_PROTOCOLS *pProtocol
);

Parameters

pProtocol
[out, retval] Pointer to the protocol identifier.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pProtocol is invalid.
E_POINTER | A bad pointer was passed in pProtocol.

Remarks

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

get_Atr, get_CardHandle, get_Context, get_Status, ISCard


ISCard::get_Status

The get_Status method retrieves the current state of the smart card.

HRESULT get_Status(
  SCARD_STATES *pStatus
);

Parameters

pStatus
[out, retval] Pointer to the state variable.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pStatus is invalid.
E_POINTER | A bad pointer was passed in pStatus.

Remarks

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

get_Atr, get_CardHandle, get_Context, get_Protocol, ISCard


ISCard::AttachByHandle

The AttachByHandle method attaches this object to an open and configured smart card handle.

HRESULT AttachByHandle(
  HSCARD hCard
);

Parameters

hCard
[in] Handle to an open connection to a smart card.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | hCard is invalid.

Remarks

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

AttachByReader, Detach,get_CardHandle, ISCard, ReAttach


ISCard::AttachByReader

The AttachByReader method opens the smart card in the named reader.

HRESULT AttachByReader(
  BSTR bstrReaderName,
  SCARD_SHARE_MODES ShareMode,
  SCARD_PROTOCOLS PrefProtocol
);

Parameters

bstrReaderName [in]
Pointer to the name of the smart card reader.
ShareMode [in, defaultvalue(EXCLUSIVE)]
Mode in which to claim access to the smart card.
Values | Description
EXCLUSIVE | No one else use this connection to the smart card.
SHARED | Other applications can use this connection.

PrefProtocol [in, defaultvalue(T0)]
Preferred protocol.
Values
T0
T1
Raw
T0|T1

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Open on the smart card in the named reader has been completed successfully.
E_INVALIDARG | There is something wrong with one or more of the parameters passed into the function.

Remarks

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

AttachByHandle, Detach, ISCard, ReAttach


ISCard::Detach

The Detach method closes the open connection to the smart card.

HRESULT Detach(
  SCARD_DISPOSITIONS Disposition
);

Parameters

Disposition [in, defaultvalue(LEAVE)]
Indicates what should be done with the card in the connected reader.
Values | Description
LEAVE | Leaves the smart card in the current state.
RESET | Resets the smart card to some known state.
UNPOWER | Removes power from the smart card.
EJECT | Ejects the smart card if the reader has eject capabilities.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Disposition is invalid.

Remarks

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

AttachByHandle, AttachByReader, Detach, ISCard, ReAttach


ISCard::LockSCard

The LockSCard method claims exclusive access to the smart card.

HRESULT LockSCard(void);

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.

Remarks

In addition to the COM error code listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

ISCard, UnlockSCard


ISCard::ReAttach

The ReAttach method resets, or reinitializes, the smart card.

HRESULT ReAttach(
  SCARD_SHARE_MODES ShareMode,
  SCARD_DISPOSITIONS InitState
);

Parameters

ShareMode [in, defaultvalue(EXCLUSIVE)]
Mode in which to share or exclusively own the connection to the smart card.
Values | Description
EXCLUSIVE | No one else use this connection to the smart card.
SHARED | Other applications can use this connection.

InitState [in, defaultvalue(LEAVE)]
Indicates what to do with the card.
Values | Description
LEAVE | Leaves the smart card in the current state.
RESET | Resets the smart card to some known state.
UNPOWER | Removes power from the smart card.
EJECT | Ejects the smart card if the reader has eject capabilities.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | There is something wrong with one or more of the parameters passed into the function.

Remarks

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

AttachByHandle, AttachByReader, Detach, ISCard


ISCard::Transaction

The Transaction method executes a write and read operation on the smart card command (APDU) object. The reply string from the smart card for the command string defined in the card that was sent to the smart card will be accessible after this function returns.

HRESULT Transaction(
  LPSCARDCMD *ppCmd
);

Parameters

ppCmd [in, out]
Pointer to the smart card command object.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | ppCmd is invalid.
E_POINTER | A bad pointer was passed in ppCmd.
E_OUTOFMEMORY | Memory to satisfy the request is unavailable.

Remarks

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

AttachByHandle, AttachByReader, Detach, get_Atr, get_CardHandle, get_Context, get_Protocol, get_Status, ISCard, LockSCard, ReAttach, Transaction, UnlockSCard


ISCard::UnlockSCard

The UnlockSCard method releases exclusive access to the smart card.

HRESULT UnlockSCard(
  SCARD_DISPOSITIONS Disposition
);

Parameters

Disposition [in, defaultvalue(LEAVE)]
Indicates what should be done with the card in the connected reader.
Values | Description
LEAVE | Leaves the smart card in the current state.
RESET | Resets the smart card to some known state.
UNPOWER | Removes power from the smart card.
EJECT | Ejects the smart card if the reader has eject capabilities.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Disposition is invalid

Remarks

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

ISCard, LockSCard


ISCardCmd

The ISCardCmd interface provides the methods needed to construct and manage a smart card Application Protocol Data Unit (APDU ). This interface encapsulates two buffers:

  • The APDU buffer contains the command sequence that will be sent to the card.
  • The APDUReply buffer contains data returned from the card after execution of the APDU command (this data is also referred to as the return ADPU).

The following example shows a typical use of the ISCardCmd interface. The ISCardCmd interface is used to build the an ADPU.

To submit a transaction to a specific card
  1. Create an ISCard interface and connect to a smart card.
  2. Create an ISCardCmd interface.
  3. Build a smart card APDU command using the ISCardISO7816 interface or one of ISCardCmd's build methods).
  4. Execute the command on the smart card by calling the appropriate ISCard interface method.
  5. Evaluate the returned response.
  6. Repeat the procedure as needed.
  7. Release the ISCardCmd interface and others as needed.

Methods

ISCardCmd Methods | Description
get_Apdu | Retrieves the raw APDU.
put_Apdu | Copies the APDU from an IByteBuffer (IStream) object into the APDU wrapped in this interface object.
get_ApduLength | Retrieves the length of the APDU.
get_ApduReply | Retrieves the reply APDU.
put_ApduReply | Sets a new reply APDU.
get_ApduReplyLength | Retrieves the length of the reply APDU.
get_ClassId | Retrieves the class ID from the APDU.
put_ClassId | Sets a new class ID in the APDU.
get_Data | Retrieves the data field from the APDU.
put_Data | Sets or copies a given data field into the APDU.
Get_InstructionId | Retrieves the instruction ID byte from the APDU.
Put_InstructionId | Sets the given instruction ID byte in the APDU.
Get_P1 | Retrieves the first parameter byte from the APDU.
Put_P1 | Sets the first parameter byte in the APDU.
Get_P2 | Retrieves the second parameter byte from the APDU.
Put_P2 | Sets the second parameter byte in the APDU.
Get_P3 | Retrieves the third parameter byte from the APDU.
get_ReplyStatus | Retrieves the reply APDU's message status word.
put_ReplyStatus | Sets a new reply APDU's message status word.
get_ReplyStatusSW1 | Retrieves the reply APDU's message SW1 status byte.
get_ReplyStatusSW2 | Retrieves the reply APDU's message SW2 status byte.
BuildCmd | Constructs a valid command APDU for transmission to a smart card.
Clear | Clear the APDU and the reply APDU message buffers.
Encapsulate | Encapsulate the given command APDU into another command APDU for transmission to a smart card.


ISCardCmd::get_Apdu

The get_Apdu method retrieves the raw APDU.

HRESULT get_Apdu(
  LPBYTEBUFFER *ppApdu
);

Parameters

ppApdu
[out, retval] Pointer to the byte buffer mapped through an IStream that contains the APDU message on return.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | ppApdu is invalid.
E_POINTER | A bad pointer was passed in ppApdu.
E_OUTOFMEMORY | Out of memory.

Remarks

To copy the APDU from an IByteBuffer (IStream) object into the APDU wrapped in this interface object, call put_Apdu.

To determine the length of the APDU, call get_ApduLength.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_ApduLength, ISCardCmd, put_Apdu


ISCardCmd::put_Apdu

The put_Apdu method copies the APDU from the IByteBuffer (IStream) object into the APDU wrapped in this interface object.

HRESULT put_Apdu(
  LPBYTEBUFFER pApdu
);

Parameters

pApdu
[in] Pointer to the ISO 7816-4 APDU to be copied in.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pApdu is invalid.
E_POINTER | A bad pointer was passed in pApdu.
E_OUTOFMEMORY | Out of memory.

Remarks

To retrieve the raw APDU from the byte buffer mapped through an IStream that contains the APDU message, call get_Apdu.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_Apdu, ISCardCmd


ISCardCmd::get_ApduLength

The get_ApduLength method determines the length (in bytes) of the APDU.

HRESULT get_ApduLength(
  LONG *plSize
);

Parameters

plSize
[out, retval] Pointer to the length of the APDU.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | plSize is invalid.
E_POINTER | A bad pointer was passed in plSize.
E_OUTOFMEMORY | Out of memory.

Remarks

To retrieve the raw APDU from the byte buffer mapped through an IStream that contains the APDU message, call get_Apdu.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_Apdu, ISCardCmd


ISCardCmd::get_ApduReply

The get_ApduReply retrieves the reply APDU, placing it in a specific byte buffer. The reply may be NULL if no transaction has been performed on the command APDU.

HRESULT get_ApduReply(
  LPBYTEBUFFER *ppReplyApdu
);

Parameters

ppReplyApdu
[out, retval] Pointer to the byte buffer (mapped through an IStream) that contains the APDU reply message on return.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | ppReplyApdu is invalid.
E_POINTER | A bad pointer was passed in ppReplyApdu.
E_OUTOFMEMORY | Out of memory.

Remarks

To determine the length of the APDU reply, call get_ApduReplyLength.

To set a new reply APDU, call put_ApduReply.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_ApduReplyLength, ISCardCmd, put_ApduReply


ISCardCmd::put_ApduReply

The put_ApduReply method sets a new reply APDU.

HRESULT put_ApduReply(
  LPBYTEBUFFER pReplyApdu
);

Parameters

pReplyApdu
[in] Pointer to the byte buffer (mapped through an IStream) that contains the replay APDU message on return.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pReplyApdu is invalid.
E_POINTER | A bad pointer was passed in pReplyApdu.
E_OUTOFMEMORY | Out of memory.

Remarks

To get an existing reply APDU, call get_ApduReply.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_ApduReply, get_ApduReplyLength, ISCardCmd


ISCardCmd::get_ApduReplyLength

The get_ApduReplyLength method determines the length (in bytes) of the reply APDU.

HRESULT get_ApduReplyLength(
  LONG *plSize
);

Parameters

plSize
[out, retval] Pointer to the size of the reply APDU message.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | plSize is invalid.
E_POINTER | A bad pointer was passed in plSize.
E_OUTOFMEMORY | Out of memory.

Remarks

To get an existing reply APDU, call get_ApduReply.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_ApduReply, ISCardCmd, put_ApduReply


ISCardCmd::get_ClassId

The get_ClassId method retrieves the class identifier from the APDU.

HRESULT get_ClassId(
  BYTE *pbyClass
);

Parameters

pbyClass
[out, retval] Pointer to the byte that represents the class identifier.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pbyClass is invalid.
E_POINTER | A bad pointer was passed in pbyClass.
E_OUTOFMEMORY | Out of memory.

Remarks

To set the class identifier to a new value, call put_ClassId.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

ISCardCmd, put_ClassId


ISCardCmd::put_ClassId

The put_ClassId method sets a new class identifier in the APDU.

HRESULT put_ClassId(
  BYTE byClass
);

Parameters

byClass
[in, defaultvalue(0)] The byte that represents the class identifier.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | byClass is invalid.
E_OUTOFMEMORY | Out of memory.

Remarks

To retrieve the current class identifier, call get_ClassId.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_ClassId, ISCardCmd


ISCardCmd::get_Data

The get_Data method retrieves the data field from the APDU, placing it in a byte buffer object.

HRESULT get_Data(
  LPBYTEBUFFER *ppData
);

Parameters

ppData
[out, retval] Pointer to the byte buffer object (IStream) that holds the APDU's data field on return.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | ppData is invalid.
E_POINTER | A bad pointer was passed in ppData.
E_OUTOFMEMORY | Out of memory.

Remarks

To set the data field of the ADPU, call put_Data.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

ISCardCmd, put_Data


ISCardCmd::put_Data

The put_Data method sets the data field in the APDU.

HRESULT put_Data(
  LPBYTEBUFFER pData
);

Parameters

pData
[in] Pointer to the byte buffer object (IStream) to be copied into the APDU's data field.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pData is invalid.
E_POINTER | A bad pointer was passed in pData.
E_OUTOFMEMORY | Out of memory.

Remarks

When you set a new data portion of the message, the length of the data field is calculated and stored in the P3 parameter of the APDU. To retrieve the length of the data field, call get_P3.

To retrieve the data field from the APDU, call get_Data.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_Data, get_P3, ISCardCmd


ISCardCmd::get_InstructionId

The get_InstructionId method retrieves the instruction identifier byte from the APDU.

HRESULT get_InstructionId(
  BYTE *pbyIns
);

Parameters

pbyIns
[out, retval] Pointer to the byte that is the instruction ID from the APDU on return.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pbyIns is invalid parameter.
E_POINTER | A bad pointer was passed in pbyIns.
E_OUTOFMEMORY | Out of memory.

Remarks

To set the instructional identifier to a new value, call put_InstructionId.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

ISCardCmd, put_InstructionId


ISCardCmd::put_InstructionId

The put_InstructionId sets the given instruction identifier in the APDU.

HRESULT put_InstructionId(
  BYTE byIns
);

Parameters

byIns
[in] The byte that is the instruction identifier.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | byIns is invalid.
E_OUTOFMEMORY | Out of memory.

Remarks

To get the existing instructional identifier, call get_InstructionId.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_InstructionId, ISCardCmd


ISCardCmd::get_P1

The get_P1 method retrieves the first parameter (P1) byte from the APDU.

HRESULT get_P1(
  BYTE *pbyP1
);

Parameters

pbyP1
[out, retval] Pointer to the P1 byte in the APDU on return.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pbyP1 is invalid.
E_POINTER | A bad pointer was passed in pbyP1.
E_OUTOFMEMORY | Out of memory.

Remarks

To set the P1 parameter to a new value, call put_P1.

To get the P2 or P3 parameters, call get_P2 and get_P3 respectively.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_P2, get_P3, ISCardCmd, put_P1


ISCardCmd::put_P1

The put_P1 method sets the first parameter (P1) byte of the APDU.

HRESULT put_P1(
  BYTE byP1
);

Parameters

byP1
[in] The byte that is the P1 field.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | byP1 is invalid.
E_OUTOFMEMORY | Out of memory.

Remarks

To set the P2 value of the APDU, call put_P2.

To retrieve the existing P1, P2, and P3 values, call get_P1, get_P2 or get_P3 respectively.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_P1, get_P2, get_P3, ISCardCmd, put_P2


ISCardCmd::get_P2

The get_P2 method retrieves the second parameter (P2) byte from the APDU

HRESULT get_P2(
  BYTE *pbyP2
);

Parameters

pbyP2
[out, retval] Pointer to the byte that is the P2 from the APDU on return.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pbyP2 is invalid.
E_POINTER | A bad pointer was passed in pbyP2.
E_OUTOFMEMORY | Out of memory.

Remarks

To set the P2 parameter to a new value, call put_P2.

To get the P1 or P3 parameters, call get_P1 and get_P3 respectively.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_P1, get_P3, ISCardCmd, put_P2


ISCardCmd::put_P2

The put_P2 method sets the second parameter (P2) byte in the APDU.

HRESULT put_P2(
  BYTE byP2
);

Parameters

byP2
[in] The byte that is the P2 field.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | byP2 is invalid.
E_OUTOFMEMORY | Out of memory.

Remarks

To set the P1 value of the APDU, call put_P1.

To retrieve the existing P1, P2, and P3 values, call get_P1, get_P2 or get_P3 respectively.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_P1, get_P2, get_P3, get_P2, ISCardCmd, put_P1


ISCardCmd::get_P3

The get_P3 method retrieves the third parameter (P3) byte from the APDU. This read-only byte value represents the size of the data portion of the APDU.

HRESULT get_P3(
  BYTE *pbyP3
);

Parameters

pbyP3
[out, retval] Pointer to the byte that is the P3 from the APDU on return.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pbyP3 is invalid.
E_POINTER | A bad pointer was passed in pbyP3.
E_OUTOFMEMORY | Out of memory.

Remarks

The P3 parameter is read only, and therefore cannot be set.

To get the P1 or P2 parameters, call get_P1 and get_P2 respectively.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_P1, get_P2, ISCardCmd


ISCardCmd::get_ReplyStatus

The get_ReplyStatus method retrieves the reply APDU's message status word.

HRESULT get_ReplyStatus(
  LPWORD pwStatus
);

Parameters

pwStatus
[out, retval] Pointer to the word that is the status on return.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pwStatus is invalid.
E_POINTER | A bad pointer was passed in pwStatus.
E_OUTOFMEMORY | Out of memory.

Remarks

To set the reply APDU's message status word, call put_ReplyStatus.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

ISCardCmd, put_ReplyStatus


ISCardCmd::put_ReplyStatus

The put_ReplyStatus sets a new reply APDU's message status word.

HRESULT put_ReplyStatus(
  WORD wStatus
);

Parameters

wStatus
[in] The word that is the status.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | wStatus is invalid.
E_OUTOFMEMORY | Out of memory.

Remarks

To get the reply APDU's message status word, call get_ReplyStatus.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_ReplyStatus, ISCardCmd


ISCardCmd::get_ReplyStatusSW1

The get_ReplyStatusSW1 method retrieves the reply APDU's SW1 status byte.

HRESULT get_ReplyStatusSW1(
  LPBYTE pbySW1
);

Parameters

pbySW1
[out, retval] Pointer to the byte that contains the value of the SW1 byte on return.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pbySW1 is Invalid.
E_POINTER | A bad pointer was passed in pbySW1.
E_OUTOFMEMORY | Out of memory.

Remarks

The reply APDU's SW1 status byte is read only.

To retrieve the reply APDU's SW2 status byte, call get_ReplyStatusSW2.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_ReplyStatusSW2, ISCardCmd,


ISCardCmd::get_ReplyStatusSW2

The get_ReplyStatusSW2 method retrieves the reply APDU's SW2 status byte.

HRESULT get_ReplyStatusSW2(
  LPBYTE pbySW2
);

Parameters

pbySW2
[out, retval] Pointer to the byte that contains the value of the SW2 byte on return.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | pbySW2 is invalid.
E_POINTER | A bad pointer was passed in pbySW2.
E_OUTOFMEMORY | Out of memory.

Remarks

The reply APDU's SW2 status byte is read only.

To retrieve the reply APDU's SW1 status byte, call get_ReplyStatusSW1.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

get_ReplyStatusSW1, ISCardCmd,


ISCardCmd::BuildCmd

The BuildCmd method constructs a valid command APDU for transmission to a smart card.

HRESULT BuildCmd(
  BYTE byClassId,
  BYTE byInsId,
  BYTE byP1,
  BYTE byP2,
  LPBYTEBUFFER pbyData,
  LONG *p1Le
);

Parameters

byClassId
[in] Command class identifier.
byInsId
[in] Command instruction identifier.
byP1
[in, defaultvalue(0)] Command's first parameter.
byP2
[in, defaultvalue(0)] Command's second parameter.
pbyData
[in, defaultvalue(NULL)] Pointer to the data portion of the command.
p1Le
[in, defaultvalue(NULL)] Pointer to a LONG integer containing the expected length of the returned data.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Public key retrieved successfully.
E_INVALIDARG | One of the parameters are Invalid.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

To encapsulate the command into another command, call Encapsulate

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

Encapsulate, ISCardCmd


ISCardCmd::Clear

The Clear method clears the APDU and reply APDU message buffers.

HRESULT Clear(void);

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Public key retrieved successfully.
S_FALSE | Unknown error.

Remarks

To build a command APDU, call BuildCmd.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

BuildCmd, ISCardCmd


ISCardCmd::Encapsulate

The Encapsulate method encapsulates the given command APDU into another command APDU for transmission to a smart card.

HRESULT Encapsulate(
  LPBYTEBUFFER pApdu,
  ISO_APDU_TYPE ApduType
);

Parameters

pApdu
[in] Pointer to the APDU to be encapsulated.
ApduType
[in] Specifies the ISO 7816-4 case for T0 transmissions. Possible values are:

ISO_CASE_1

ISO_CASE_2

ISO_CASE_3

ISO_CASE_4

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Public key retrieved successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in pApdu.
E_OUTOFMEMORY | Out of memory.

Remarks

To build a command APDU, call BuildCmd.

For a list of all the methods provided by the ISCardCmd interface, see ISCardCmd.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scarddat.h.
Import Library: scarddat.tlb.

See Also

BuildCmd, ISCardCmd


ISCardLocate

The ISCardeLocate interface provides services for locating a smart card by its name.

This interface can display the smart card user interface if it is required.

The following example shows a typical use of the ISCardLocate interface. The ISCardLocate interface is used to build the an ADPU.

To locate a specific card using its name
  1. Create an ISCardLocate interface.
  2. Call ConfigureCardNameSearch to search for a smart card name.
  3. Call FindCard to search for the smart card.
  4. Interpret the results.
  5. Release the ISCardLocate interface.

Methods

ISCardLocate Methods | Description
ConfigureCardNameSearch | Specifies the card name to be used in the search.
FindCard | Searches for the smart card and opens a valid connection to it.


ISCardLocate::ConfigureCardNameSearch

The ConfigureCardNameSearch method specifies the card names to be used in the search for the smart card.

HRESULT ConfigureCardNameSearch(
  LPSAFEARRAY pCardNames,
  LPSAFEARRAY pGroupNames,
  BSTR bstrTitle,
  LONG lFlags
);

Parameters

pCardNames
[in] Pointer to an OLE Automation safe array of card names in BSTR form.
pGroupNames
[in, defaultvalue(NULL )] Pointer to an OLE Automation safe array of names of card/reader groups in BSTR form to add to the search.
bstrTitle
[in, defaultvalue("")] Search common control dialog title.
lFlags
[in, defaultvalue(1)] Specifies when user interface is displayed:
Flag | Meaning
SC_DLG_MINIMAL_UI | Displays the dialog only if the card being searched for by the calling application is not located and available for use in a reader. This allows the card to be found, connected (either through internal dialog mechanism or the user callback functions), and returned to the calling application.
SC_DLG_NO_UI | Causes no UI display, regardless of the search outcome.
SC_DLG_FORCE_UI | Causes UI display regardless of the search outcome.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Public key retrieved successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in pCardNames or pGroupNames.
E_OUTOFMEMORY | Out of memory.

Remarks

To locate the smart card, call FindCard.

To set the search criteria to the interfaces a smart card supports, call ConfigureCardGuidSearch.

For a list of all the methods provided by the ISCardLocate interface, see ISCardLocate.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

FindCard, ISCardLocate


ISCardLocate::FindCard

The FindCard method searches for the smart card and opens a valid connection to it.

HRESULT FindCard(
  SCARD_SHARE_MODES ShareMode,
  SCARD_PROTOCOLS Protocols,
  LONG lFlags,
  LPSCARDINFO *ppCardInfo
);

Parameters

ShareMode [in, defaultvalue(EXCLUSIVE)]
Mode in which to share or not share the smart card when a connection is opened to it.
Values | Description
EXCLUSIVE | No one else use this connection to the smart card.
SHARED | Other applications can use this connection.

Protocols [in, defaultvalue(T0)]
Protocol to use when connecting to the card.
Values
T0
T1
Raw
T0|T1

lFlags [in, defaultvalue(SC_DLG_NO_UI)]
Specifies when user interface is displayed:
Flag | Meaning
SC_DLG_MINIMAL_UI | Displays the dialog only if the card being searched for by the calling application is not located and available for use in a reader. This allows the card to be found, connected (either through internal dialog mechanism or the user callback functions), and returned to the calling application.
SC_DLG_NO_UI | Causes no UI display, regardless of the search outcome.
SC_DLG_FORCE_UI | Causes UI display regardless of the search outcome.

ppCardInfo
[out, retval] Pointer to a data structure that contains/returns information about the opened smart card, if successful. Will be NULL if operation has failed.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Public key retrieved successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in ppCardInfo.
E_OUTOFMEMORY | Out of memory.

Remarks

To set the search criteria of the search, call ConfigureCardNameSearch to specify a smart card's card names or call ConfigureCardGuidSearch to specify a smart card's interfaces.

For a list of all the methods provided by the ISCardLocate interface, see ISCardLocate.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

ConfigureCardNameSearch, ISCardLocate


ISCardDatabase

The ISCardDatabase interface provides the methods for performing the smart card resource manager's database operations. These operations include listing known smart cards, readers, and reader groups, plus retrieving the interfaces supported by a smart card and its primary service provider.

Note The identifier of the primary service provider is a COM GUID that can be used to instantiate and use the COM objects for a specific card.

The following example shows a typical use of the ISCardDatabase interface. In this case, the ISCardDatabase interface is used to list all the known smart cards.

To submit a transaction to a specific card
  1. Create an ISCardDatabase interface.
  2. Call ListCards to retrieve all the known smart cards based on an ATR string or their supported interfaces.
  3. Release the ISCardDatabase interface.

Methods

ISCardDatabase Methods | Description
GetProviderCardId | Retrieves the identifier of the primary service provider for a specific smart card.
ListCardInterfaces | Retrieves the interface identifiers (GUIDs) of all the interfaces supported by a specific smart card.
ListCards | Retrieves all the smart card names that match a specific set of interface identifiers (GUIDs) or an ATR string.
ListReaderGroups | Retrieves the names of the reader groups that the resource manager has knowledge of.
ListReaders | Retrieve the names of the readers that the resource manager has knowledge of.


ISCardDatabase::GetProviderCardId

The GetProviderCardId method retrieves the identifier (GUID) of the primary service provider for the specified smart card.

HRESULT GetProviderCardId(
  BSTR bstrCardName,
  LPGUID *ppguidProviderId
);

Parameters

bstrCardName
[in] Name of the smart card.
ppguidProviderId
[out, retval] Pointer to the primary service provider's identifier (GUID) if successful; NULL if operation failed.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDPARAMETER | Invalid parameter.
E_POINTER | A bad pointer was passed in ppguidProviderId.
E_OUTOFMEMORY | Out of memory.

Remarks

To list the interfaces of the smart card, call ListCardInterfaces.

To retrieve all known smart cards, readers and reader groups call ListCard, ListReaders, and ListReaderGroups respectively.

For a list of all the methods provided by the ISCardDatabase interface, see ISCardDatabase.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

ISCardDatabase, ListCardInterfaces, ListCards, ListReaderGroups, ListReaders


ISCardDatabase::ListCardInterfaces;ListCardInterfaces(ISCardDatabase)

ISCardDatabase::ListCardInterfaces

The ListCardInterfaces method retrieves the identifiers (GUIDs) of all the interfaces supported for the specified smart card.

HRESULT ListCardInterfaces(
  BSTR bstrCardName,
  LPSAFEARRAY *ppInterfaceGuids
);

Parameters

bstrCardName
[in] Name of the smart card.
ppInterfaceGuids
[out, retval] Pointer to the interface GUIDs if successful; NULL if operation failed.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDPARAMETER | Invalid parameter.
E_POINTER | A bad pointer was passed in ppInterfaceGuids.
E_OUTOFMEMORY | Out of memory.

Remarks

To retrieve the primary service provider of the smart card, call GetProviderCardId.

To retrieve all known smart cards, readers, and reader groups call ListCard, ListReaders, and ListReaderGroups respectively.

For a list of all the methods provided by the ISCardDatabase interface, see ISCardDatabase.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

GetProviderCardId, ISCardDatabase, ListCards, ListReaderGroups, ListReaders


ISCardDatabase::ListCards

The ListCards method retrieves all of the smart card names that match the specified interface identifiers (GUIDs), the specified ATR string, or both.

HRESULT ListCards(
  LPBYTEBUFFER pAtr,
  LPSAFEARRAY pInterfaceGuids,
  LONG localeId,
  LPSAFEARRAY *ppCardNames
);

Parameters

pAtr
[in, defaultvalue(NULL) ] Pointer to a smart card ATR string. The ATR string must be packaged into an IByteBuffer.
pInterfaceGuids
[in, defaultvalue(NULL)] Pointer to a SAFEARRAY of COM interface identifiers (GUIDs) in BSTR format.
localeId
[in, lcid, defaultvalue(0x0409)] Language localization identifier.
ppCardNames
[out, retval] Pointer to a SAFEARRAY of BSTRs that contains the names of the smart cards that satisfied the search parameters if successful; NULL if the operation failed.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDPARAMETER | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

To retrieve all known readers or reader groups, call ListReaders or ListReaderGroups respectively.

To retrieve the primary service provider or the interfaces of a specific card GetProviderCardId or ListCardInterfaces respectively.

For a list of all the methods provided by the ISCardDatabase interface, see ISCardDatabase.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

GetProviderCardId, ISCardDatabase, ListCardInterfaces, ListReaderGroups, ListReaders


ISCardDatabase::ListReaderGroups

The ListReaderGroups method retrieves the names of the reader groups registered in the smart card database.

HRESULT ListReaderGroups(
  LONG localeId,
  LPSAFEARRAY *ppReaderGroups
);

Parameters

localeId
[in, lcid, defaultvalue(0x0409)] Language localization ID.
ppReaderGroups
[out, retval] Pointer to a SAFEARRAY of BSTRs that contains the names of the smart card reader groups that satisfied the search parameters if successful; NULL if the operation failed.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDPARAMETER | Invalid parameter.
E_POINTER | A bad pointer was passed in ppReaderGroups.
E_OUTOFMEMORY | Out of memory.

Remarks

To retrieve all known smart cards or readers, call ListCards or ListReaders respectively.

To retrieve the primary service provider or the interfaces of a specific card GetProviderCardId or ListCardInterfaces respectively.

For a list of all the methods provided by the ISCardDatabase interface, see ISCardDatabase.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

GetProviderCardId, ISCardDatabase, ListCardInterfaces, ListCards, ListReaders


ISCardDatabase::ListReaders

The ListReaders method retrieves the names of the smart card readers registered in the smart card database.

HRESULT ListReaders(
  LONG localeId,
  LPSAFEARRAY *ppReaders
);

Parameters

localeId
[in, lcid, defaultvalue(0x0409)] Language localization ID.
ppReaders
[out, retval] Pointer to a SAFEARRAY of BSTRs that contains the names of the smart card readers if successful; NULL if the operation failed.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDPARAMETER | Invalid parameter.
E_POINTER | A bad pointer was passed in ppReaders.
E_OUTOFMEMORY | Out of memory.

Remarks

To retrieve all known smart cards or reader groups, call ListCards or ListReaderGroups respectively.

To retrieve the primary service provider or the interfaces of a specific card GetProviderCardId or ListCardInterfaces respectively.

For a list of all the methods provided by the ISCardDatabase interface, see ISCardDatabase.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardmgr.h.
Import Library: scardmgr.tlb.

See Also

GetProviderCardId, ISCardDatabase, ListCardInterfaces, ListCards, ListReaderGroups


ISCardISO7816

The ISCardISO7816 interface provides methods for implementing ISO 7816-4 functionality. With the exception of ISCardISO7816::SetDefaultClassId, these methods create an APDU command that is encapsulated in a ISCardCmd object.

The ISO 7816-4 specification defines standard commands available on smart cards. The specification also defines how a smart card Application Protocol Data Unit (APDU) command should be constructed and sent to the smart card for execution. This interface automates the building process.

The following example shows a typical use of the ISCardISO7816 interface. In this case, the ISCardISO7816 interface is used to build an APDU command.

To submit a transaction to a specific card
  1. Create an ISCardISO7816 and ISCardCmd interface. The ISCardCmd interface is used to encapsulate the APDU.
  2. Call the appropriate method of the ISCardISO7816 interface, passing the required parameters and the ISCardCmd interface pointer.
  20. The ISO 7816-4 APDU command will be built and encapsulated in the ISCardCmd interface.
  21. Release the ISCardISO7816 and ISCardCmd interfaces.

Note In the method reference pages, if a bit sequence in a table is not defined, assume that bit sequence is reserved for future use or proprietary to a specific vendor).

Methods

ISCardISO7816 Methods | Description
AppendRecord | Constructs a command that appends a record to the end of an elementary file (EF).
EraseBinary | Sets part of the content of an elementary to its logical erased state, sequentially, starting from a given offset.
ExternalAuthenticate | Conditionally updates the security status using the result of the computation by the card, based on a challenge previously issued by the card (for example, by the INS_GET_CHALLENGE command), a possibly secret key stored in the card, and authentication data transmitted by the interface device.
GetChallenge | Requires the issuing of a challenge for use in a security-related procedure.
GetData | Retrieves a single primitive data object or a set of data objects contained in a constructed data object, based on the type of file specified.
GetResponse | Transmits from the card to the interface device APDU(s) that otherwise could not be transmitted by the available protocols.
InternalAuthenticate | Initiates the computation of the authentication data by the card using the challenge data sent from the interface device and a relevant secret stored in the card.
ManageChannel | Opens and closes logical channels.
PutData | Stores one primitive data object, or one or more data objects contained in a constructed data object, within the current resource manager context.
ReadBinary | Constructs a command that acquires a response message that gives that part of the contents of an EF with transparent structure.
ReadRecord | Constructs a command that reads the contents of the specified records of an elementary file.
SelectFile | Sets a current file within a logical channel.
SetDefaultClassId | Assigns a standard class ID byte that will be used in all operations when constructing an ISO 7816-4 command APDU.
UpdateBinary | Initiates the update of the bits already present in an EF with the bits given in the command APDU.
UpdateRecord | Constructs a command that initiates the updating of a specific record.
Verify | Initiates the comparison in the card of the verification data sent from the interface device with the reference data stored in the card.
WriteBinary | Initiates the writing of binary values into an EF.
WriteRecord | Constructs a command that writes a record.


ISCardISO7816::AppendRecord

The AppendRecord method constructs an APDU command that either appends a record to the end of a linear-structured elementary file (EF) or writes record number 1 in an cyclic-structured elementary file.

HRESULT AppendRecord(
  BYTE byRefCtrl,
  LPBYTEBUFFER pData,
  LPSCARDCMD *ppCmd
);

Parameters

byRefCtrl [in, defaultvalue(NULL_BYTE)]
Identifies the elementary file to be appended:
Meaning | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1
Current EF | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
Short EF ID | x | x | x | x | x | 0 | 0 | 0
Reserved | x | x | x | x | x | x | x | x

pData [in]
Pointer to the data to be appended to the file:
Tn (1 byte) Ln (1 or 3 bytes) data (Ln bytes)

ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

The encapsulated command can only be performed if the security status of the smart card satisfies the security attributes of the elementary file read.

If another elementary file is selected at the time of issuing this command, it may be processed without identification of the currently selected file.

Elementary files without a record structure cannot be read. The encapsulated command aborts if applied to an elementary file without a record structure.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

ISCardISO7816, ReadRecord, UpdateRecord, WriteRecord


ISCardISO7816::EraseBinary

The EraseBinary method constructs an APDU command that sequentially sets part of the content of an elementary file to its logical erased state, starting from a given offset.

HRESULT EraseBinary(
  BYTE byP1,
  BYTE byP2,
  LPBYTEBUFFER pData,
  LPSCARDCMD *ppCmd
);

Parameters

byP1, byP2 [in]
RFU position.
If… | Then…
b8=1 in P1 | b7 and b6 of P1 are set to 0 (RFU bits), b5 to b1 of P1 are a short EF identifier and P2 is the offset of the first byte to be erased (in data units) from the beginning of the file.
b8=0 in P1 | then P1 || P2 is the offset of the first byte to be erased (in data units) from the beginning of the file.

If the data field is present, it codes the offset of the first data unit not to be erased. This offset shall be higher than the one coded in P1-P2. When the data field is empty, the command erases up to the end of the file.

pData [in, defaultvalue(NULL)]
Pointer to the data that specifies the erase range; may be NULL.
ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

The encapsulated command can only be performed if the security status of the smart card satisfies the security attributes of the elementary file being processed.

When the command contains a valid short elementary identifier, it sets the file as current elementary file.

Elementary files without a transparent structure cannot be erased. The encapsulated command aborts if applied to an elementary file without a transparent structure.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

ISCardISO7816, ReadBinary, UpdateBinary, WriteBinary


ISCardISO7816::ExternalAuthenticate

The ExternalAuthenticate method constructs an APDU command that conditionally updates security status, verifying the identity of the computer when the smart card does not trust it.

The command uses the result (yes or no) of the computation by the card (based on a challenge previously issued by the card — for example, by the INS_GET_CHALLENGE command), a key (possibly secret) stored in the card, and authentication data transmitted by the interface device.

HRESULT ExternalAuthenticate (
  BYTE byAlgorithmRef,
  BYTE bySecretRef,
  LPBYTEBUFFER pChallenge,
  LPSCARDCMD *ppCmd
);

Parameters

byAlgorithmRef [in, defaultvalue(NULL_BYTE)]
Reference of the algorithm in the card.

If this value is zero, this indicates that no information is given. The reference of the algorithm is known either before issuing the command or is provided in the data field.

bySecretRef [in, defaultvalue(NULL_BYTE)]
Reference of the secret:
Meaning | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1
No Info | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
Global ref 0 - - - - - - -
Specific ref 1 - - - - - - -
RFU - x x - - - - -
Secret - - - x x x x x

No Info = No information is given. The reference of the secret is known either before issuing the command or is provided in the data field.

Global ref = Global reference data (an MF specific key).

Specific ref = Specific reference data (a DF specific key).

RFU = 00 (other values are RFU).

Secret = Number of the secret.

pChallenge [in, defaultvalue(NULL)]
Pointer to the authentication-related data; may be NULL.
ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

For the encapsulated command to be successful, the last challenge obtained from the card must be valid.

Unsuccessful comparisons may be recorded in the card (for example, to limit the number of further attempts of the use of the reference data).

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

InternalAuthenticate, ISCardISO7816


ISCardISO7816::GetChallenge

The GetChallenge method constructs an APDU command that issue a challenge (for example, a random number) for use in a security-related procedure.

HRESULT GetChallenge(
  LONG lBytesExpected,
  LPSCARDCMD *ppCmd
);

Parameters

lBytesExpected [in, defaultvalue(0)]
Maximum length of the expected response.
ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

The challenge is valid at least for the next command.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

ExternalAuthenticate, InternalAuthenticate, ISCardISO7816


ISCardISO7816::GetData

The GetData method constructs an APDU command that retrieves either a single primitive data object or a set of data objects (contained in a constructed data object), depending on the type of file selected.

HRESULT GetData(
  BYTE byP1,
  BYTE byP2,
  LONG lBytesToGet,
  LPSCARDCMD *ppCmd
);

Parameters

byP1, byP2 [in]
Parameters:
Value | Meaning
0000 - 003F | RFU
0040 - 00FF | BER-TLV tag (1 byte) in P2
0100 - 01FF | Application data (proprietary coding)
0200 - 02FF | SIMPLE-TLV tag in P2
0300 - 03FF | RFU
0400 - 04FF | BER-TLV tag (2 bytes) in P1-P2

lBytesToGet [in, defaultvalue(0)]
Number of bytes expected in the response.
ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

The encapsulated command can only be performed if the security status of the smart card satisfies the security attributes of the elementary file being read. Security conditions are dependent on the policy of the card, and may be manipulated through ExternalAuthenticate, InternalAuthenticate, ISCardAuth, etc.

To select a file, call SelectFile.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

ExternalAuthenticate, InternalAuthenticate, ISCardAuth, ISCardISO7816, PutData, SelectFile


ISCardISO7816::GetResponse

The GetResponse method constructs an APDU command that transmits APDU commands (or part of an APDU command) which otherwise could not be transmitted by the available protocols.

HRESULT GetResponse(
  BYTE byP1,
  BYTE byP2,
  LONG lDataLength,
  LPSCARDCMD *ppCmd
);

Parameters

byP1, byP2 [in, defaultvalue(0)]
Per the ISO 7816-4, P1 and P2 should be 0 (RFU).
lDataLength [in, defaultvalue(0)]
Length of data transmitted.
ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

ISCardISO7816


ISCardISO7816::InternalAuthenticate

The InternalAuthenticate method constructs an APDU command that initiates the computation of the authentication data by the card using the challenge data sent from the interface device and a relevant secret (for example, a key) stored in the card.

When the relevant secret is attached to the MF, the command may be used to authenticate the card as a whole.

When the relevant secret is attached to another DF, the command may be used to authenticate that DF.

HRESULT InternalAuthenticate(
  BYTE byAlgorithmRef,
  BYTE bySecretRef,
  LPBYTEBUFFER pChallenge,
  LONG lReplyBytes,
  LPSCARDCMD *ppCmd
);

Parameters

byAlgorithmRef [in, defaultvalue(NULL_BYTE)]
Reference of the algorithm in the card.

If this value is zero, this indicates that no information is given. The reference of the algorithm is known either before issuing the command or is provided in the data field.

bySecretRef [in, defaultvalue(NULL_BYTE)]
Reference of the secret:
Meaning | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1
No Info | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
Global ref 0 - - - - - - -
Specific ref 1 - - - - - - -
RFU - x x - - - - -
Secret - - - x x x x x

No Info = No information is given.

Global ref = Global reference data (an MF specific key).

Specific ref = Specific reference data (a DF specific key).

RFU = 00 (other values are RFU).

Secret = Number of the secret.

pChallenge [in]
Pointer to the authentication-related data (for example, challenge).
lReplyBytes [in, defaultvalue(0)]
Maximum number of bytes expected in response.
ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

The successful execution of the command may be subject to successful completion of prior commands (for example, VERIFY or SELECT FILE) or selections (for example, the relevant secret).

If a key and an algorithm are currently selected when issuing the command, then the command may implicitly use the key and the algorithm.

The number of times the command is issued may be recorded in the card to limit the number of further attempts of using the relevant secret or the algorithm.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

ExternalAuthenticate, ISCardISO7816


ISCardISO7816::ManageChannel

The ManageChannel method constructs an APDU command that opens and closes logical channels.

The open function opens a new logical channel other than the basic one. Options are provided for the card to assign a logical channel number, or for the logical channel number to be supplied to the card.

The close function explicitly closes a logical channel other than the basic one. After the successful closing, the logical channel shall be available for re-use.

HRESULT ManageChannel(
  BYTE byChannelState,
  BYTE byChannel,
  LPSCARDCMD *ppCmd
);

Parameters

byChannelState [in, defaultvalue(ISO_CLOSE_LOGICAL_CHANNEL)]
Bit b8 of P1 is used to indicate the open function or the close function; if b8 is 0 then MANAGE CHANNEL shall open a logical channel and if b8 is 1 then MANAGE CHANNEL shall close a logical channel:

P1 = '00' to open

P1 = '80' to close

Other values are RFU

byChannel [in, defaultvalue(ISO_LOGICAL_CHANNEL_0)]
For the open function (P1 = '00'), the bits b1 and b2 of P2 are used to code the logical channel number in the same manner as in the class byte, the other bits of P2 are RFU.

When b1 and b2 of P2 are NULL, then the card will assign a logical channel number that will be returned in bits b1 and b2 of the data field.

When b1 and/or b2 of P2 are not NULL, they code a logical channel number other than the basic one; then the card will open the externally assigned logical channel number.

ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

When the open function is successfully performed from the basic logical channel, the MF shall be implicitly selected as the current DF and the security status of the new logical channel should be the same as the basic logical channel after ATR. The security status of the new logical channel should be separate from that of any other logical channel.

When the open function is successfully performed from a logical channel, which is not the basic one, the current DF of the logical channel that issued the command will be selected as the current DF. In addition, the security status for the new logical channel should be the same as the security status of the logical channel from which the open function was performed.

After a successful close function, the security status related to this logical channel is lost.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

ISCardISO7816


ISCardISO7816::PutData

The PutData method constructs an APDU command that stores a single primitive data object or the set of data objects contained in a constructed data object, depending on the file selected.

How the objects are stored (writing once and/or updating and/or appending) depends on the definition or the nature of the data objects.

HRESULT PutData(
  BYTE byP1,
  BYTE byP2,
  LPBYTEBUFFER pData,
  LPSCARDCMD *ppCmd
);

Parameters

byP1, byP2 [in]
Coding of P1-P2:
Value | Meaning
0000 - 003F | RFU
0040 - 00FF | BER-TLV tag (1 byte) in P2
0100 - 01FF | Application data (proprietary coding)
0200 - 02FF | SIMPLE-TLV tag in P2
0300 - 03FF | RFU
0400 - 04FF | BER-TLV tag (2 bytes) in P1-P2

pData [in]
Pointer to a byte buffer that contains the parameters and data to be written.
ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

The command can be performed only if the security status satisfies the security conditions defined by the application within the context for the function.

Store Application Data
When the value of P1-P2 lies in the range from 0100 to 01FF, the value of P1-P2 shall be an identifier reserved for card internal tests and for proprietary services meaningful within a given application context.
Store Data Objects
When the value P1-P2 lies in the range from 0040 to 00FF, the value of P2 shall be a BER-TLV tag on a single byte. The value of 00FF is reserved for indicating that the data field carries BER-TLV data objects.

When the value of P1-P2 lies in the range 0200 to 02FF, the value of P2 shall be a SIMPLE-TLV tag. The value 0200 is RFU. The value 02FF is reserved for indicating that the data field carries SIMPLE-TLV data objects.

When the value of P1-P2 lies in the range from 4000 to FFFF, the value of P1-P2 shall be a BER-TLV tag on two bytes. The values 4000 to FFFF are RFU.

When a primitive data object is provided, the data field of the command message shall contain the value of the corresponding primitive data object.

When a constructed data object is provided, the data field of the command message shall contain the value of the constructed data object (that is, data objects including their tag, length, and value).

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

GetData, ISCardISO7816


ISCardISO7816::ReadBinary

The ReadBinary method constructs an APDU command that acquires a response message that gives that part of the contents of a transparent-structured elementary file.

HRESULT ReadBinary(
  BYTE byP1,
  BYTE byP2,
  LONG lBytesToRead,
  LPSCARDCMD *ppCmd
);

Parameters

byP1, byP2 [in]
The P1-P2 field, offset to the first byte to be read from the beginning of the file.

If b8=1 in P1, then b7 and b6 of P1 are set to 0 (RFU bits), b5 to b1 of P1 are a short EF identifier and P2 is the offset of the first byte to be read in data units from the beginning of the file.

If b8=0 in P1, then P1||P2 is the offset of the first byte to be read in data units from the beginning of the file.

lBytesToRead [in, defaultvalue(0)]
Number of bytes to read from the transparent EF.

If the Le field contains only zeroes, then within the limit of 256 for short length or 65536 for extended length, all the bytes until the end of the file should be read.

ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

The encapsulated command can only be performed if the security status of the smart card satisfies the security attributes of the elementary file being processed.

When the command contains a valid short elementary identifier, it sets the file as current elementary file.

Elementary files without a transparent structure cannot be erased. The encapsulated command aborts if applied to an elementary file without a transparent structure.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

EraseBinary, ISCardISO7816, UpdateBinary, WriteBinary


ISCardISO7816::ReadRecord

The ReadRecord method constructs an APDU command that reads either the contents of the specified record(s) or the beginning part of one record of an elementary file.

HRESULT ReadRecord(
  BYTE byRecordId,
  BYTE byRefCtrl,
  LONG lBytesToRead,
  LPSCARDCMD *ppCmd
);

Parameters

byRecordId [in, defaultvalue(NULL_BYTE)]
Record number or ID of the first record to be read (00 indicates the current record).
byRefCtrl [in]
Coding of the reference control:
Meaning 8 7 6 5 4 3 2 1
Current EF 0 0 0 0 0 - - -
Short EF ID x x x x x - - -
RFU 1 1 1 1 1 - - -
Record - - - - - 1 x x
Read Record - - - - - 1 0 0
Up to Last - - - - - 1 0 1
Up to P1 - - - - - 1 1 0
RFU - - - - - 1 1 1
Record ID - - - - - 0 x x
First Occur - - - - - 0 0 0
Last Occur - - - - - 0 0 1
Next Occur - - - - - 0 1 0
Previous - - - - - 0 1 1
Secret - - - x x x x x

Current EF = Currently selected EF.

Short EF ID = Short EF identifier.

Record # = Usage of record number in P1.

Read Record = Read record P1.

Up to Last = Read all records from P1 up to the last.

Up to P1 = Read all records from the last up to P1.

Record ID = Usage of record ID in P1.

First Occur = Read first occurrence.

Last Occur = Read last occurrence.

Next Occur = Read next occurrence.

Previous = Read previous occurrence.

lBytesToRead [in, defaultvalue(0)]
Number of bytes to read from the transparent EF.

If the Le field contains only zeroes, then depending on b3b2b1 of P2 and within the limit of 256 for short length or 65536 for extended length, the command should read completely either the single requested record or the requested sequence of records.

ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

The encapsulated command can only be performed if the security status of the smart card satisfies the security attributes of the elementary file being read.

If another elementary file is currently selected at the time of issuing this command, it may be processed without identification of the currently selected file.

When the command contains a valid short elementary identifier, it sets the file as current elementary file.

Elementary files without a record structure cannot be read. The encapsulated command aborts if applied to an elementary file without a record structure.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

AppendRecord, ISCardISO7816, UpdateRecord, WriteRecord


ISCardISO7816::SelectFile

The SelectFile method constructs an APDU command that sets a current elementary file within a logical channel. Subsequent commands may implicitly refer to the current file through the logical channel.

Selecting a directory (DF) within the card filestore — which may be the root (MF) of the filestore — makes it the current DF. After such a selection, an implicit current elementary file may be referred to through that logical channel.

Selecting an elementary file sets the selected file and its parent as current files.

After the answer to reset, the MF is implicitly selected through the basic logical channel, unless specified differently in the historical bytes or in the initial data string.

HRESULT SelectFile(
  BYTE byP1,
  BYTE byP2,
  LPBYTEBUFFER pData,
  LONG lBytesToRead,
  LPSCARDCMD *ppCmd
);

Parameters

byP1, byP2 [in]
Selection control.

P1 (upper byte in word):
Meaning | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1
Select File ID | 0 | 0 | 0 | 0 | 0 | 0 | x | x
EF, DF, or MF | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
child DF | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1
EF under DF | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0
parent DF of current DF | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 1

Meaning | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1
Select by DF Name | 0 | 0 | 0 | 0 | 0 | 1 | x | x
DFname | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0
RFU | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 1
RFU | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 0
RFU | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 1

Meaning | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1
Select by path | 0 | 0 | 0 | 0 | 1 | 0 | x | x
from MF | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0
current DF | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 1
RFU | 0 | 0 | 0 | 0 | 1 | 0 | 1 | 0
RFU | 0 | 0 | 0 | 0 | 1 | 0 | 1 | 1

When P1=00, the card knows either because of a specific coding of the file ID or because of the context of execution of the command if the file to select is the MF, a DF, or an EF.

When P1-P2=0000, if a file ID is provided, then it shall be unique in the following environments:

  • the immediate children of the current DF
  • the parent DF
  • the immediate children of the parent DF

If P1-P2=0000 and if the data field is empty or equal to 3F00, then select the MF.

When P1=04, the data field is a DF name, possibly right truncated.

When supported, successive such commands with the same data field shall select DFs whose names match with the data field (that is, start with the command data field). If the card accepts the command with an empty data field, then all or a subset of the DFs can be successively selected.

P2 (lower byte of word):
Meaning 8 7 6 5 4 3 2 1
First occur 0 0 0 0 - - 0 0
Last occur 0 0 0 0 - - 0 1
Next occur 0 0 0 0 - - 1 0
Previous occur 0 0 0 0 - - 1 1

Meaning 8 7 6 5 4 3 2 1
File Control 0 0 0 0 x x - -
Return FCI 0 0 0 0 0 0 - -
Return FCP 0 0 0 0 0 1 - -
Return FMD 0 0 0 0 1 0 - -

pData [in, defaultvalue(NULL)]
Data for operation if needed; else, NULL. Types of data that are passed in this parameter include:
  • file ID
  • path from the MF
  • path from the current DF
  • DF name
lBytesToRead [in, defaultvalue(0)]
Empty (that is, 0) or maximum length of data expected in response.
ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

Unless otherwise specified, the correct execution of the encapsulated command modifies the security status according to the following rules:

  • When the current elementary file is changed, or when there is no current elementary file, the security status specific to a former current elementary file is lost.
  • When the current filestore directory (DF) is descendant of, or identical to the former current DF, the security status specific to the former current DF is lost. The security status common to all common ancestors of the previous and new current DF is maintained.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

ISCardISO7816


ISCardISO7816::SetDefaultClassId

The SetDefaultClassId method assigns a standard class identifier byte that will be used in all operations when constructing an ISO 7816-4 command APDU. By default, the standard class identifier byte is 0x00.

HRESULT SetDefaultClassId(
  BYTE byClass
);

Parameters

byClass [in]
Class ID byte.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

ISCardISO7816


ISCardISO7816::UpdateBinary

The UpdateBinary method constructs an APDU command that updates the bits present in an elementary file with the bits given in the APDU command.

HRESULT UpdateBinary(
  BYTE byP1,
  BYTE byP2,
  LPBYTEBUFFER pData,
  LPSCARDCMD *ppCmd
);

Parameters

byP1, byP2 [in]
Offset to the write (update) location into the binary from the start of the binary.

If b8=1 in P1, then b7 and b6 of P1 are set to 0 (RFU bits), b5 to b1 of P1 are a short EF identifier and P2 is the offset of the first byte to be updated in data units from the beginning of the file.

If b8=0 in P1, then P1 || P2 is the offset of the first byte to be updated in data units from the beginning of the file.

pData [in]
Pointer to the string of data units to be updated.
ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

The encapsulated command can only be performed if the security status of the smart card satisfies the security attributes of the elementary file being processed.

When the command contains a valid short elementary identifier, it sets the file as current elementary file.

Elementary files without a transparent structure cannot be erased. The encapsulated command aborts if applied to an elementary file without a transparent structure.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

EraseBinary, ISCardISO7816, ReadBinary, WriteBinary


ISCardISO7816::UpdateRecord

The UpdateRecord method constructs an APDU command that updates a specific record with the bits given in the APDU command.

Note When using current record addressing, the command sets the record pointer on the successfully updated record.

HRESULT UpdateRecord(
  BYTE byRecordId,
  BYTE byRefCtrl,
  LPBYTEBUFFER pData,
  LPSCARDCMD *ppCmd
);

Parameters

byRecordId [in, defaultvalue(NULL_BYTE)]
P1 value:

P1 = 00 designates the current record

P1 != '00' is the number of the specified record

byRefCtrl [in, defaultvalue(NULL_BYTE)]
Coding of the reference control P2:
Meaning 8 7 6 5 4 3 2 1
Current EF 0 0 0 0 0 - - -
Short EF ID x x x x x - - -
First Record - - - - - 0 0 0
Last Record - - - - - 0 0 1
Next Record - - - - - 0 1 0
Previous Record - - - - - 0 1 1
Record # in P1 - - - - - 1 0 0

pData [in]
Pointer to the record to be updated.
ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

The encapsulated command can only be performed if the security status of the smart card satisfies the security attributes of the elementary file being processed.

When the command contains a valid short elementary identifier, it sets the file as current elementary file. If another elementary file is currently selected at the time of issuing this command, this command may be processed without identification of the currently selected file.

If the constructed command applies to a linear-fixed or cyclic-structured elementary file, it will abort if the record length is different from the length of the existing record.

If the command applies to a linear-variable structured elementary file, it may be carried out when the record length is different from the length of the existing record.

The "previous" option of the command (P2=xxxxx011), applied to a cyclic file, has the same behavior as a command constructed by AppendRecord.

Elementary files without a record structure cannot be read. The constructed command aborts if applied to an elementary file without record structure.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

AppendRecord, ISCardISO7816, ReadRecord, WriteRecord


ISCardISO7816::Verify

The Verify method constructs an APDU command that initiates the comparison (in the card) of the verification data sent from the interface device with the reference data stored in the card (for example, password).

HRESULT Verify(
  BYTE byRefCtrl,
  LPBYTEBUFFER pData,
  LPSCARDCMD *ppCmd
);

Parameters

byRefCtrl [in, defaultvalue(NULL_BYTE)]
Quantifier of the reference data; coding of the reference control P2:
Meaning | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1
No Info | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
Global Ref 0 - - - - - - -
Specific Ref 1 - - - - - - -
RFU - x x - - - - -
Ref Data # - - - x x x x x

An example of Global Ref would be a password.

An example of Specific Ref is DF specific password.

P2=00 is reserved to indicate that no particular qualifier is used in those cards where the verify command references the secret data unambiguously.

The reference data number may be for example a password number or a short EF identifier.

When the body is empty, the command may be used either to retrieve the number 'X' of further allowed retries (SW1-SW2=63CX) or to check whether the verification is not required (SW1-SW2=9000).

pData [in, defaultvalue(NULL)]
Pointer to the verification data, or can be NULL.
ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

The security status may be modified as a result of a comparison. Unsuccessful comparisons may be recorded in the card (for example, to limit the number of further attempts of the use of the reference data).

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

ISCardISO7816


ISCardISO7816::WriteBinary

The WriteBinary method constructs an APDU command that writes binary values into an elementary file.

Depending upon the file attributes, the command performs one of the following operations:

  • The logical OR of the bits already present in the card with the bits given in the command APDU (logical erased state of the bits of the file is 0).
  • The logical AND of the bits already present in the card with the bits given in the command APDU (logical erased state of the bits of the file is 1).
  • The one-time write in the card of the bits given in the command APDU.

When no indication is given in the data coding byte, the logical OR behavior applies.

HRESULT WriteBinary(
  BYTE byP1,
  BYTE byP2,
  LPBYTEBUFFER pData,
  LPSCARDCMD *ppCmd
);

Parameters

byP1, byP2 [in]
Offset to the write location from the beginning of the binary file (EF).

If b8=1 in P1, then b7 and b6 of P1 are set to 0 (RFU bits), b5 to b1 of P1 are a short EF identifier and P2 is the offset of the first byte to be written in data units from the beginning of the file.

If b8=0 in P1, then P1||P2 is the offset of the first byte to be written in data units from the beginning of the file.

pData [in]
Pointer to the string of data units to be written.
ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

The encapsulated command can only be performed if the security status of the smart card satisfies the security attributes of the elementary file being processed.

When the command contains a valid short elementary identifier, it sets the file as current elementary file.

Once a write binary operation has been applied to a data unit of a one-time write EF, any further write operation referring to this data unit will be aborted if the content of the data unit or the logical erased state indicator (if any) attached to this data unit is different from the logical erased state.

Elementary files without a transparent structure cannot be written to. The encapsulated command aborts if applied to an elementary file without a transparent structure.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

EraseBinary, ISCardISO7816, ReadBinary, UpdateBinary


ISCardISO7816::WriteRecord

The WriteRecord method constructs an APDU command that initiates one of the following operations:

  • The write once of a record.
  • The logical OR of the data bytes of a record already present in the card with the data bytes of the record given in the command APDU.
  • The logical AND of the data bytes of a record already present in the card with the data bytes of the record given in the command APDU.

When no indication is given in the data coding byte, the logical OR behavior applies.

Note When using current record addressing, the command sets the record pointer on the successfully updated record.

HRESULT WriteRecord(
  BYTE byRecordId,
  BYTE byRefCtrl,
  LPBYTEBUFFER pData,
  LPSCARDCMD *ppCmd
);

Parameters

byRecordId [in, defaultvalue(NULL_BYTE)]
Record identification. This is the P1 value:

P1 = '00' designates the current record.

P1 != '00' is the number of the specified record.

byRefCtrl [in, defaultvalue(NULL_BYTE)]
Coding of the reference control P2:
Meaning 8 7 6 5 4 3 2 1
Current EF 0 0 0 0 0 - - -
Short EF ID x x x x x - - -
First Record - - - - - 0 0 0
Last Record - - - - - 0 0 1
Next Record - - - - - 0 1 0
Previous Record - - - - - 0 1 1
Record # in P1 - - - - - 1 0 0

pData [in]
Pointer to the record to be written.
ppCmd [in, out]
On input, a pointer to an ISCardCmd interface object or NULL.

On return, it is filled with the APDU command constructed by this operation. If ppCmd was set to NULL, a smart card ISCardCmd object is internally created and returned via the ppCmd pointer.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

The encapsulated command can only be performed if the security status of the smart card satisfies the security attributes of the elementary file being processed.

When the command contains a valid short elementary identifier, it sets the file as current elementary file. If another elementary file is currently selected at the time of issuing this command, this command may be processed without identification of the currently selected file.

If the encapsulated command applies to a linear-fixed or cyclic-structured elementary file, it will abort if the record length is different from the length of the existing record. If it applies to a linear-variable structured elementary file, it may be carried out when the record length is different from the length of the existing record.

If P2=xxxxx011 and the elementary file is cyclic file, this command has the same behavior a command constructed using AppendRecord.

Elementary files without a record structure cannot be written to. The constructed command aborts if applied to an elementary file without a record structure.

For a list of all the methods provided by the ISCardISO7816 interface, see ISCardISO7816.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardsrv.h.
Import Library: scardsrv.tlb.

See Also

AppendRecord, ISCardISO7816, ReadRecord, UpdateRecord


ISCardAuth

The following interface definition is provided as a standard that can followed when developing a smart card service provider.

The ISCardAuth interface can be used to expose authentication services supported by a smart card. These services include application authentication, smart card authentication, and user authentication.

The following example shows a typical use of the ISCardAuth interface.

To use ISCardAuth
  1. Create an ISCardAuth interface (through the corresponding ISCardManage interface method).
  2. Call the appropriate ISCardAuth method (APP_Auth, GetChallenge, ICC_Auth, or User_Auth).
  3. Release the ISCardAuth interface.

Methods

ISCardAuth Methods | Definition
APP_Auth | Allows the application to authenticate itself using a challenge/signature protocol.
GetChallenge | Returns a challenge from the smart card.
ICC_Auth | Allows an application to authenticate the smart card.
User_Auth | Allows access to user authentication services.


ISCardAuth::APP_Auth

The APP_Auth method authenticates the application. It allows an application to authenticate itself (using a challenge/signature protocol) when authentication is requested by a smart card.

HRESULT APP_Auth(
  LONG lAlgoID,
  LPBYTEBUFFER pParam,
  LPBYTEBUFFER pBuffer
);

Parameters

lAlgoID [in]
Specifies the algorithm to be used in the authentication process.
pParam [in]
IByteBuffer containing vendor-specific parameters of the authentication process.
pBuffer [in]
Contains data required for the calculation.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods provided by the ISCardAuth interface, see ISCardAuth.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardAuth


ISCardAuth::GetChallenge

The GetChallenge method returns a challenge from the smart card.

HRESULT GetChallenge(
  LONG lAlgoID,
  LONG lLengthOfChallenge,
  LPBYTEBUFFER pParam,
  LPBYTEBUFFER *pBuffer
);

Parameters

lAlgoID [in, optional]
Specifies the algorithm to be used in the authentication process.
lLengthOfChallenge [in]
Maximum length of expected response.
pParam [in]
IByteBuffer containing vendor-specific parameters of the authentication process.
pBuffer [in ,out]
On input, points to the buffer.

On output, contains the challenge data from the card.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

For a list of all the methods provided by the ISCardAuth interface, see ISCardAuth.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardAuth


ISCardAuth::ICC_Auth

The ICC_Auth method allows an application to authenticate the smart card.

HRESULT ICC_Auth(
  LONG lAlgoID,
  LPBYTEBUFFER pParam,
  LPBYTEBUFFER *pBuffer
);

Parameters

lAlgoID [in]
Specifies the algorithm to be used in the authentication process.
pParam [in]
IByteBuffer containing vendor-specific parameters of the authentication process.
pBuffer [in, out]
On input, contains data to be used in the authentication process.

On output, contains the result of the authentication process.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

For a list of all the methods provided by the ISCardAuth interface, see ISCardAuth.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardAuth


ISCardAuth::User_Auth

The User_Auth method allows access to user authentication services.

HRESULT User_Auth(
  LONG lAlgoID,
  LPBYTEBUFFER pParam,
  LPBYTEBUFFER pBuffer
);

Parameters

lAlgorID [in]
Specifies the algorithm to be used in the authentication process.
pParam [in]
IByteBuffer containing vendor-specific parameters of the authentication process.
pBuffer [in]
Contains data to be used in the authentication process.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods provided by the ISCardAuth interface, see ISCardAuth.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardAuth


ISCardFileAccess

The following interface definition is provided as a standard that can followed when developing a smart card service provider.

The ISCardFileAccess interface can be used to implement a high-level interface to a card-based file system with an underlying card file system based on the structure defined in ISO/IEC 7816-4. Other implementations are possible, but this is expected to be the most common.

The ISCardFileAccess interface can be used to expose file system entities in a manner very familiar to application developers in the PC environment. It provides mechanisms for locating specific files and performing common operations such as selecting, reading, writing, creating and deleting. It encapsulates and masks much of the low-level detail involved in performing these operations at the card level.

Following is a typical use of the ISCardFileAccess interface. In this case, the ISCardFileAccess interface is used to select, open and, write to a file.

To write to a file
  1. Call ISCardManage::CreateFileAccess to create an ISCardFileAccess interface.
  2. Call Open to select and open the file.
  4. Call Write.
  5. Call Close.
  6. Release the ISCardFileAccess interface.

Methods

ISCardFileAccess Methods | Description
ChangeDir | Changes the current smart card directory to the new specified directory.
Close | Closes the specified file.
Create | Creates a file at a given location within the ICC file system.
GetCurrentDir | Returns an absolute path to the currently selected directory.
GetProperties | Retrieves the primitive data referred by tags (TLV) for the specified object.
Invalidate | Invalidates the specified file.
Open | Opens the specified file for further use.
Read | Reads and returns the specified data from a given file.
Rehabilitate | Makes a file (EF or DF), which has been previously invalidated with the Invalidate command, accessible by the application.
Seek | Selects the object from which read/write access will be done.
SetProperties | Sets the primitive data referred by tags (TLV) for the specified object.
Write | Writes data to a current opened file.


ISCardFileAccess::ChangeDir

The ChangeDir method changes the current smart card directory to the new specified directory.

HRESULT ChangeDir(
  REFTYPE refType,
  BSTR bstrNewDir
);

Parameters

refType [in]
Specifies the type of reference used in bstrNewDir as follows:

SC_TYPE_BY_NAME

SC_TYPE_BY_ID

SC_TYPE_BY_SHORT

SC_TYPE_BY_ANY

bstrNewDir [in]
Specifies a file/directory name (by refType) to select.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_OUTOFMEMORY | Out of memory.

Remarks

To get an absolute path to the currently selected directory, call GetCurrentDir.

For a list of all the methods defined by the ISCardFileAccess interface, see ISCardFileAccess.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

GetCurrentDir, ISCardFileAccess


ISCardFileAccess::Close

The Close method closes the specified file. No further access to file is allowed.

HRESULT Close(
  HSCARD_FILE hFile
);

Parameters

hFile [in]
Handle to the file to be closed.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_OUTOFMEMORY | Out of memory.

Remarks

To open a file, call Open.

For a list of all the methods defined by the ISCardFileAccess interface, see ISCardFileAccess.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardFileAccess, Open


ISCardFileAccess::Create

The Create method creates a file at a given location within the smart card file system.

HRESULT Create(
  REFTYPE refType,
  BSTR bstrPathSpec,
  TLV_TABLE TLV,
  SCARD_FLAGS Flags,
  LPBYTEBUFFER pDataBuffer
);

Parameters

refType [in]
Specifies the type of reference used in bstrPathSpec as follows:

SC_TYPE_BY_NAME

SC_TYPE_BY_ID

SC_TYPE_BY_SHORT

SC_TYPE_BY_ANY

bstrPathSpec [in]
Specifies file ID to be created within current context.
TLV [in]
List of TLV structures which values have to be set.
Flags [in]
Specifies whether secure messaging has to be used and data preallocated.
Flags…
SC_FL_SECURE_MESSAGING
SC_FL_PREALLOCATED

pDataBuffer [in, defaultvalue(NULL)]
Pointer to preallocated data.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods defined by the ISCardFileAccess interface, see ISCardFileAccess.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardFileAccess


ISCardFileAccess::GetCurrentDir

The GetCurrentDir method returns an absolute path to the currently selected directory.

HRESULT GetCurrentDir(
  BSTR *pbstrPathSpec
);

Parameters

pbstrPathSpec [out, retval]
Pointer to a BSTR that will contain the path.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

To change the current directory, call ChangeDir.

For a list of all the methods defined by the ISCardFileAccess interface, see ISCardFileAccess.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ChangeDir, ISCardFileAccess


ISCardFileAccess::GetProperties

The GetProperties method retrieves the primitive data referred by tags (TLV) for the specified object.

HRESULT GetProperties(
  REFTYPE refType,
  BSTR bstrPathSpec,
  SCARD_FLAGS flags,
  LPTLV_TABLE *ppTLV
);

Parameters

refType [in]
Specifies the type of reference used in bstrNewDir as follows:

SC_TYPE_BY_NAME

SC_TYPE_BY_ID

SC_TYPE_BY_SHORT

SC_TYPE_BY_ANY

bstrPathSpec [in]
Specifies file.
flags [in]
Specifies whether secure messaging should be used.
Flag…
SC_FL_SECURE_MESSAGING

ppTLV [in, out]
Pointer to TLV structures whose value has been retrieved.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods defined by the ISCardFileAccess interface, see ISCardFileAccess.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardFileAccess


ISCardFileAccess::Invalidate

The Invalidate method invalidates the specified file (EF or DF). An invalidated file cannot be accessed by other methods prior to using Rehabilitate.

HRESULT Invalidate(
  BSTR bstrPathSpec,
  SCARD_FLAGS flags
);

Parameters

bstrPathSpec [in]
Specifies file.
flags [in]
Specifies whether secure messaging should be used.
Flags…
SC_FL_SECURE_MESSAGING

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods defined by the ISCardFileAccess interface, see ISCardFileAccess.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardFileAccess, Rehabilitate


ISCardFileAccess::Open

The Open method opens the specified file for further use.

HRESULT Open(
  REFTYPE refType,
  BSTR bstrPathSpec,
  HSCARD_FILE *phFile
);

Parameters

refType [in]
Specifies the type of reference used in bstrPathSpec as follows:

SC_TYPE_BY_NAME

SC_TYPE_BY_ID

SC_TYPE_BY_SHORT

SC_TYPE_BY_ANY

bstrPathSpec [in]
Specifies file to open.
phFile [out, retval]
Pointer to an HSCARD_FILE that will hold the file handle.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

To close a file, call Close.

For a list of all the methods defined by the ISCardFileAccess interface, see ISCardFileAccess.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

Close, ISCardFileAccess


ISCardFileAccess::Read

The Read method reads and returns the specified data from a given file.

HRESULT Read(
  HSCARD_FILE hFile,
  LONG *lBytesToRead,
  SCARD_FLAGS flags,
  LPBYTEBUFFER *ppBuffer
);

Parameters

hFile [in]
Handle of the open file to access.
lBytesToRead [in]
Length of data to be read (in) or number of bytes read (out). Returns list of files as an array of BSTRs.
flags [in]
Specifies whether secure messaging should be used.
Flags…
SC_FL_SECURE_MESSAGING

ppBuffer [out, retval]
IByteBuffer containing the read data.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods defined by the ISCardFileAccess interface, see ISCardFileAccess.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardFileAccess


ISCardFileAccess::Rehabilitate

The Rehabilitate method makes a file (EF or DF), which was previously invalidated with the Invalidate method, accessible by the application.

HRESULT Rehabilitate(
  BSTR bstrPathSpec,
  SCARD_FLAGS flags
);

Parameters

bstrPathSpec [in]
Specifies the file to rehabilitate.
flags [in]
Specifies whether secure messaging should be used.
Flags…
SC_FL_SECURE_MESSAGING

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods defined by the ISCardFileAccess interface, see ISCardFileAccess.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

Invalidate, ISCardFileAccess


ISCardFileAccess::Seek

The Seek method selects the object from which (read/write) access will be done.

HRESULT Seek(
  HSCARD_FILE hFile,
  SEEKTYPE Seek,
  LONG lOffset
);

Parameters

hFile [in]
Handle to an open file.
Seek [in]
Specifies where the seek should begin:

SC_SEEK_FROM_BEGINNING

SC_SEEK_FROM_END

SC_SEEK_RELATIVE

lOffset [in]
The number of data objects from the reference object.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_OUTOFMEMORY | Out of memory.

Remarks

To read to or write from a file, call Read or Write respectively.

For a list of all the methods defined by the ISCardFileAccess interface, see ISCardFileAccess.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardFileAccess, Read, Write


ISCardFileAccess::SetProperties

The SetProperties method sets the primitive data referred by tags (TLV) for the specified object.

HRESULT SetProperties(
  REFTYPE refType,
  BSTR bstrPathSpec,
  SCARD_FLAGS flags,
  LPTLV_TABLE pTable
);

Parameters

refType [in]
Specifies the type of reference used in bstrPathSpec as follows:

SC_TYPE_BY_NAME

SC_TYPE_BY_ID

SC_TYPE_BY_SHORT

SC_TYPE_BY_ANY

bstrPathSpec [in]
Specifies file.
flags [in]
Specifies whether secure messaging should be used.
Flags…
SC_FL_SECURE_MESSAGING

pTable [in]
Pointer to TLV structures whose value should be set.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods defined by the ISCardFileAccess interface, see ISCardFileAccess.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardFileAccess


ISCardFileAccess::Write

The Write method writes data to a current opened file.

HRESULT Write(
  HSCARD_FILE hFile,
  LPBYTEBUFFER pData,
  SCARD_FLAGS flags
);

Parameters

hFile [in]
Handle to an open file.
pData [in]
Contains the object/data to be written.
flags [in]
Specifies whether secure messaging should be used.
Flags…
SC_FL_SECURE_MESSAGING

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

To open a file, call Open.

To close the file, call Close.

For a list of all the methods defined by the ISCardFileAccess interface, see ISCardFileAccess.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

Close, ISCardFileAccess, Open


ISCardManage

The following interface definition is provided as a standard that can be followed when developing a smart card service provider.

The ISCardManage interface must be provided. It is used for attaching to a specific smart card or reader, for creating other optional interfaces to perform specific smart card functions, for locking a specific smart card for exclusive use, and for getting the status of a smart card or reader. As a set, these services can be responsible for maintaining a well-defined context within which an application can communicate with a smart card or reader.

Following is a typical use of ISCardManage interface.

To connect to a smart card
  1. Create the ISCardManage interface associated with the card.
  2. Connect to a smart card by attaching to a specific smart card reader (AttachByIFD) or by using a previously acquired handle (AttachByHandle).
  3. Create other interfaces to perform smart card operations (CreateAuth, CreateFileAccess, CreateVerify, or CreateInterface).
  4. Release the card (Detach).
  5. Release the ISCardManage interface and others as required.

Methods

ISCardManage Method | Definition
AttachByHandle | Allows an application to create a communication link to a smart card using a handle returned by the smart card resource manager.
AttachByIFD | Allows an application to request establishment of a context for a specific reader referenced with a friendly name.
CreateAuth | Allows the creation of a ISCardAuth interface.
CreateFileAccess | Allows the creation of a ISCardFileAccess interface.
CreateInterface | Allows the creation of a component-supported interface.
CreateVerify | Allows the creation of a ISCardVerify interface.
Detach | Releases the attachment to a particular smart card or reader allocated by AttachByHandle or AttachByIFD respectively.
SCardLock | Locks a connected smart card or reader for exclusive use.
SCardUnlock | Releases exclusive use of the connected smart card or reader.
Reconnect | Allows an application to reconnect to a smart card or reader without having to issue a Detach followed by AttachByHandle or AttachByIFD respectively.
Status | Allows an application to get the current status of the smart card or reader.


ISCardManage::AttachByHandle

The AttachByHandle method creates a communication link to a smart card (ICC) using a handle returned by the smart card resource manager.

HRESULT AttachByHandle(
  HSCARD hICC
);

Parameters

hICC [in]
Handle to a smart card.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | hICC is invalid.
E_OUTOFMEMORY | Out of memory.

Remarks

To attach a reader call AttachByIFD.

To release an attachment call Detach.

To reconnect with the smart card without calling Detach and AttachByHandle, call Reconnect.

For a list of all the methods defined by the ISCardManage interface, see ISCardManage.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

AttachByIFD, Detach, ISCardManage, Reconnect


ISCardManage::AttachByIFD

The AttachByIFD method creates a communication link to a reader, using a supplied friendly name for the reader.

HRESULT AttachByIFD(
  BSTR bstrIFDName
);

Parameters

bstrIFDName [in]
Friendly name of the reader.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | bstrIFDName is invalid.
E_OUTOFMEMORY | Out of memory.

Remarks

To attach a smart card call AttachByHandle.

To release an attachment call Detach.

To reconnect with the smart card without calling Detach and AttachByIFD, call Reconnect.

For a list of all the methods defined by the ISCardManage interface, see ISCardManage.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

AttachByHandle, Detach, ISCardManage, Reconnect


ISCardManage::CreateAuth

The CreateAuth method creates an ISCardAuth interface.

HRESULT CreateAuth(
  ISCardAuth **ppISCardAuth
);

Parameters

ppISCardAuth [out]
Returned pointer to the created interface.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | ppISCardAuth is invalid.
E_POINTER | A bad pointer was passed in ppISCardAuth.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods defined by the ISCardManage interface, see ISCardManage.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardManage


ISCardManage::CreateFileAccess

The CreateFileAccess method creates an ISCardFileAccess interface.

HRESULT CreateFileAccess(
  ISCardFileAccess **ppISCardFileAccess
);

Parameters

ppISCardFileAccess [out]
Returned pointer to the created ISCardFileAccess interface.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | ppISCardFileAccess is invalid.
E_POINTER | A bad pointer was passed in ppISCardFileAccess.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods defined by the ISCardManage interface, see ISCardManage.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardFileAccess, ISCardManage


ISCardManage::CreateInterface

The CreateInterface method creates of the specified interface.

HRESULT CreateInterface(
  LPGUID pguidInterface,
  BSTR bstrName,
  LONG *pUserData,
  LPUNKNOWN *ppInterface
);

Parameters

pguidInterface [in]
The GUID value of the interface to create.
bstrName [in, defaultvalue(NULL)]
The name of the interface to create if the GUID is unavailable. Standard values are "CryptoProvider".
pUserData [in, defaultvalue(NULL)]
Pointer to user-specific data to use in the creation of an interface.
ppInterface [out]
Pointer to the returned interface.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | One of the supplied parameters are invalid.
E_POINTER | A bad pointer was passed in pguidInterface or pUserData.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods defined by the ISCardManage interface, see ISCardManage.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

See Also

ISCardManage


ISCardManage::CreateVerify

The CreateVerify method creates an ISCardVerify interface.

HRESULT CreateVerify(
  ISCardVerify **ppISCardVerify
);

Parameters

ppISCardVerify [out]
Returned pointer to the created ISCardVerify interface.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | ppISCardVerify is invalid.
E_POINTER | A bad pointer was passed in ppISCardVerify.
E_OUTOFMEMORY | Out of memory.

Remarks

For information on the ISCardVerify interface, see ISCardVerify.

For a list of all the methods defined by the ISCardManage interface, see ISCardManage.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardManage, ISCardVerify


ISCardManage::Detach

The Detach method releases the attachment to a particular smart card or reader allocated by AttachByHandle and AttachByIFD respectively.

HRESULT Detach(void);

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_OUTOFMEMORY | Out of memory.

Remarks

To attach a smart card call AttachByHandle or AttachByIFD.

To reconnect with the smart card without calling Detach and AttachByHandle, call Reconnect.

For a list of all the methods defined by the ISCardManage interface, see ISCardManage.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

AttachByHandle, AttachByIFD, ISCardManage, Reconnect


ISCardManage::SCardLock

The SCardLock method locks a connected smart card for exclusive use.

HRESULT SCardLock(void);

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_FAIL | Operation failed to complete.

Remarks

To releases exclusive use of the connected smart card, call SCardUnlock.

For a list of all the methods defined by the ISCardManage interface, see ISCardManage.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardManage, SCardUnlock


ISCardManage::SCardUnlock

The SCardUnlock method releases exclusive use of the connected smart card.

HRESULT SCardUnlock(
  SCARD_DISPOSITIONS Disposition
);

Parameters

Disposition [in, defaultvalue(LEAVE)]
The state to leave the smart card in when the lock is released. Possible values are LEAVE, RESET, UNPOWER, and EJECT.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Disposition is invalid.

Remarks

To lock the connected smart card, call SCardLock.

For a list of all the methods defined by the ISCardManage interface, see ISCardManage.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardManage, SCardLock


ISCardManage::Reconnect

The Reconnect method allows an application to reconnect to a smart card or reader without having to issue a Detach call followed by an AttachByHandle or AttachByIFD call respectively.

HRESULT Reconnect(void);

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_OUTOFMEMORY | Out of memory.

Remarks

To attach a smart card call AttachByHandle or AttachByIFD.

To detach a smart card, call Detach.

For a list of all the methods defined by the ISCardManage interface, see ISCardManage.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

AttachByHandle, AttachByIFD, Detach, ISCardManage


ISCardManage::Status

The Status method gets the current status of the smart card or reader.

HRESULT Status(
  SCARD_STATES *pStatus,
  SCARD_PROTOCOLS *pProtocols
);

Parameters

pStatus [out]
On return, contains the current status/state.
pProtocols [out]
On return, contains the current protocol.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods defined by the ISCardManage interface, see ISCardManage.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardManage


ISCardVerify

The following interface definition is provided as a standard that can followed when developing a smart card service provider. The IsCardVerify interface can provide services for setting CHV (card holder verification) code and for verifying the user.

The ISCardVerify class is defined for applications that implement application-specific CHV policy, and that have a detailed knowledge of the smart card's internal implementation.

Following is a typical use of ISCardVerify interface. In this case, the ISCardVerify interface is used to change the CHV code.

To change the CHV code of a smart card
  1. Create an ISCardVerify interface (through the corresponding ISCardManage interface method).
  2. Call ChangeCode. Provide new code, and specify if it is local or global and if it is enabled or disabled.
  3. Release the ISCardVerify interface.

Methods

ISCardVerify Method | Description
ChangeCode | Changes the current CHV code.
Unblock | Re-enable the security context.
ResetSecurityState | Resets the security context of the smart card.
Verify | Authenticates the user.


ISCardVerify::ChangeCode

The ChangeCode method replaces the current CHV (card holder verification) code with new CHV code.

HRESULT ChangeCode(
  LPBYTEBUFFER pOldCode,
  LPBYTEBUFFER pNewCode,
  SCARD_FLAGS Flags,
  LONG lRef
);

Parameters

pOldCode [in]
An IByteBuffer containing the user's current code.
pNewCode [in]
An IByteBuffer containing the new code that will be presented to the smart card during the change process to authenticate the user.
Flags [in]
Indicates whether the code is global or local, and whether the code should be enabled or disabled.
Flags are…
SC_FL_IHV_GLOBAL
SC_FL_IHV_LOCAL
SC_FL_IHV_ENABLE
SC_FL_IHV_DISABLE

lRef [in]
Smart card specific reference.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods defined by the ISCardVerify interface, see ISCardVerify.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardVerify


ISCardVerify::ResetSecurityState

The ResetSecurityState method resets the current security context of the smart card.

HRESULT ResetSecurityState(void);

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_OUTOFMEMORY | Out of memory.

Remarks

To re-enable the security context without resetting, call Unblock.

For a list of all the methods defined by the ISCardVerify interface, see ISCardVerify.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardVerify, Unblock


ISCardVerify::Unblock

The Unblock method re-enables the security context of the smart card.

HRESULT Unblock(
  LONG lData,
  SCARD_FLAGS Flags,
  LONG lRef
);

Parameters

lData [in]
Contains vendor-specific data to be used in the unblocking process.
Flags [in]
Indicates whether the code is global or local.
Flags are…
SC_FL_IHV_GLOBAL
SC_FL_IHV_LOCAL

lRef [in]
Smart card specific reference.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

To globally reset the security context, call Reset.

For a list of all the methods defined by the ISCardVerify interface, see ISCardVerify.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardVerify, Unblock


ISCardVerify::Verify;Verify(ISCardVerify)

ISCardVerify::Verify

The Verify method request a verification of the user.

HRESULT Verify(
  LPBYTEBUFFER pCode,
  SCARD_FLAGS Flags,
  LONG lRef
);

Parameters

pCode [in]
Contains the code to be presented to the smart card in the CHV (card holder verification) process.
Flags [in]
Indicates whether the code is global or local.
Flags are…
SC_FL_IHV_GLOBAL
SC_FL_IHV_LOCAL

lRef [in]
Smart card specific reference.

Return Values

The possible return values are the following:

Value | Meaning
S_OK | Operation completed successfully.
E_INVALIDARG | Invalid parameter.
E_POINTER | A bad pointer was passed in.
E_OUTOFMEMORY | Out of memory.

Remarks

For a list of all the methods defined by the ISCardVerify interface, see ISCardVerify.

In addition to the COM error codes listed above, this interface may return a smart card error code if a smart card function was called to complete the request. For information on smart card error codes, see Smart Card Error Codes.

QuickInfo

Windows NT: Use version 4.0 SP3 and later.
Windows: Use Windows 95 OSR2.1.
Windows CE: Unsupported.
Header: Declared in scardcom.h.
Import Library: scardcom.tlb (vendor-supplied).

See Also

ISCardVerify


Smart Card Error Codes

This section describes the primary error codes returned by smart card functions.

Note Some error codes may have the same value as existing Win32® error codes that signify a similar condition.

Error | Definition
SCARD_E_CANCELLED | The action was canceled by an SCardCancel request.
SCARD_E_CANT_DISPOSE | The system could not dispose of the media in the requested manner.
SCARD_E_CARD_UNSUPPORTED | The smart card does not meet minimal requirements for support.
SCARD_E_DUPLICATE_READER | The reader driver didn't produce a unique reader name.
SCARD_E_INSUFFICIENT_BUFFER | The data buffer for returned data is too small for the returned data.
SCARD_E_INVALID_ATR | An ATR string obtained from the registry is not a valid ATR string.
SCARD_E_INVALID_HANDLE | The supplied handle was invalid.
SCARD_E_INVALID_PARAMETER | One or more of the supplied parameters could not be properly interpreted.
SCARD_E_INVALID_TARGET | Registry startup information is missing or invalid.
SCARD_E_INVALID_VALUE | One or more of the supplied parameter values could not be properly interpreted.
SCARD_E_NOT_READY | The reader or card is not ready to accept commands.
SCARD_E_NOT_TRANSACTED | An attempt was made to end a non-existent transaction.
SCARD_E_NO_MEMORY | Not enough memory available to complete this command.
SCARD_E_NO_SERVICE | The smart card resource manager is not running.
SCARD_E_NO_SMARTCARD | The operation requires a smart card, but no smart card is currently in the device.
SCARD_E_PCI_TOO_SMALL | The PCI receive buffer was too small.
SCARD_E_PROTO_MISMATCH | The requested protocols are incompatible with the protocol currently in use with the card.
SCARD_E_READER_UNAVAILABLE | The specified reader is not currently available for use.
SCARD_E_READER_UNSUPPORTED | The reader driver does not meet minimal requirements for support.
SCARD_E_SERVICE_STOPPED | The smart card resource manager has shut down.
SCARD_E_SHARING_VIOLATION | The smart card cannot be accessed because of other outstanding connections.
SCARD_E_SYSTEM_CANCELLED | The action was canceled by the system, presumably to log off or shut down.
SCARD_E_TIMEOUT | The user-specified timeout value has expired.
SCARD_E_UNKNOWN_CARD | The specified smart card name is not recognized.
SCARD_E_UNKNOWN_READER | The specified reader name is not recognized.
SCARD_F_COMM_ERROR | An internal communications error has been detected.
SCARD_F_INTERNAL_ERROR | An internal consistency check failed.
SCARD_F_UNKNOWN_ERROR | An internal error has been detected, but the source is unknown.
SCARD_F_WAITED_TOO_LONG | An internal consistency timer has expired.
SCARD_S_SUCCESS | No error was encountered.
SCARD_W_REMOVED_CARD | The smart card has been removed, so that further communication is not possible.
SCARD_W_RESET_CARD | The smart card has been reset, so any shared state information is invalid.
SCARD_W_UNPOWERED_CARD | Power has been removed from the smart card, so that further communication is not possible.
SCARD_W_UNRESPONSIVE_CARD | The smart card is not responding to a reset.
SCARD_W_UNSUPPORTED_CARD | The reader cannot communicate with the card, due to ATR string configuration conflicts.


A

APDU
A command sequence (an Application Protocol Data Unit) that can be sent by the smart card or returned by the application.

See also: reply APDU.

ATR string
A sequence of bytes returned from a smart card when it is turned on. These bytes are used to identify the card to the system.


P

primary service provider
The service provider that supplies the control interfaces to the card. Each smart card can register its primary service provider in the smart card database.
process
The security context under which an application runs. Typically, the security context is associated with a user, so all applications running under a given process take on the permissions and privileges of the owning user.


R

reader
A standard device within the smart card subsystem. An interface device (IFD) that supports bi-directional input/output to a smart card. It may be associated with an entire system, one or more reader groups, or with a specific terminal.

The smart card subsystem allows a reader to be dedicated to the terminal to which it is assigned. However, currently only one terminal exists on a computer. Microsoft® Windows NT® may eventually support multiple processes on multiple terminals.

reader driver
A specific driver that maps driver services to a specific hardware reader device. It must communicate card insertion and removal events to the smart card class driver for forwarding to the smart card resource manager, and provide data exchange capabilities to the card by any raw, T=0, T=1, or PTS protocol.
reader group
A logical group of readers. Reader groups can be defined by the system or created by users or administrators. Reader groups are used by smart card functions that can act upon groups of readers.

To avoid naming collisions with user-defined groups, Microsoft reserves the use of any name containing the $ symbol.

reader helper driver
Provides common smart card driver support routines and additional T=0 and T=1 protocol support to specific drivers as needed.
reply APDU
An APDU (Application Protocol Data Unit) sent in reply to a received APDU.

See also: APDU.

resource manager
The component of the smart card subsystem that manages access to multiple readers and smart cards.

The resource manager identifies and tracks resources, allocates readers and resources across multiple applications, and supports transaction primitives for accessing services available on a given card.

resource manager API
A set of Win32® functions that provide direct access to the resource manager's services.
resource manager context
The context used by the resource manager when accessing the smart card database. The resource manager context is primarily used by the query and management functions when accessing the database.

The scope of the resource manager context can be the current user or the system.


S

SCard$DefaultReaders
A terminal reader group that contains all readers assigned to that terminal, however, it is not reserved for this specific use.
SCard$AllReaders
System wide reader group that includes all readers introduced to the smart card resource manger. Readers are automatically added to the group when they are introduced to the system.
SCARD_AUTOALLOCATE
A system constant that tells the smart card resource manager to allocate sufficient memory itself, returning a pointer to the allocated buffer instead of filling in a user-supplied buffer. The returned buffer must then eventually be freed by calling SCardFreeMemory.
security context
The security attributes or rules that are currently in effect. For example, the current user logged on to the computer or the personal identification number entered by the smart card user.
service provider (Smart Card)
Smart card subsystem component that provides access to specific smart card services via COM interfaces.

See also: primary service provider.

smart card
An integrated circuit card (ICC) owned by an individual or a group whose information must be protected according to specific ownership assignments. It provides its own physical access control; without the smart card subsystem placing additional access control on the smart card.

A smart card is a plastic card containing an integrated circuit that is compatible with ISO 7816.

smart card common dialog
A common dialog that assists the user in selecting and locating a smart card. It works with the smart card database management services and reader services to help the application, and if necessary the user, to identify which smart card to use for a given purpose.
smart card database
The database used by the resource manager to manage resources. It contains a list of known smart cards, the interfaces and primary service provider of each card, and know smart card readers and reader groups.
smart card subsystem
The subsystem used to provide a link between smart card readers and smart card aware applications running within the PC environment. This subsystem is designed specifically for Microsoft® Windows® 95 OSR2.1 and Microsoft Windows NT® version 5, with support for CryptoAPI and the Windows driver model.


T

T=0 protocol
An asynchronous, character-oriented half-duplex transmission protocol.
T=1 protocol
An asynchronous, block-oriented half-duplex transmission protocol.
terminal
A combination of monitor, keyboard, mouse, and co-located peripherals, such as smart card readers. Multiple processes may be associated with a single terminal, but only one process controls the terminal at any given time.
transaction
An operation that allows you to perform multiple interactions as a single operation. Intermediate steps are not actually taken until all interactions are completed successfully. If any interaction fails, all steps are returned to their original setting.


U

user
A user of a system is identified by a login procedure, which establishes a process by which applications can run and access other security-relevant objects. An example of a login procedure is to use a smart card, possibly in conjunction with a password or personal identification number (PIN).
user interface (Smart Card)
A common dialog box that lets the user connect to a smart card and use it in an application. Using the dialog box, the user can specify a specific card or search for the smart card to open.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.