ISCardISO7816::SelectFile method
[The SelectFile method is available for use in the operating systems specified in the Requirements section. It is not available for use in Windows Server 2003 with Service Pack 1 (SP1) and later, Windows Vista, Windows Server 2008, and subsequent versions of the operating system. The Smart Card Modules provide similar functionality.]
The SelectFile method constructs an application protocol data unit (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.
Syntax
HRESULT SelectFile(
[in] BYTE byP1,
[in] BYTE byP2,
[in] LPBYTEBUFFER pData,
[in] LONG lBytesToRead,
[in, out] LPSCARDCMD *ppCmd
);
Parameters
-
byP1 [in]
-
Selection control.
P1 (upper byte in word): 8 7 6 5 4 3 2 1 Meaning - 000000xx
Select File ID - 00000000
EF, DF, or MF - 00000001
Child DF - 00000010
EF under DF - 00000011
Parent DF of current DF 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:
- Immediate children of the current DF
- Parent DF
- 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.
-
byP2 [in]
-
Selection control.
-
pData [in]
-
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]
-
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 value
The method returns one of the following possible values.
| Return code | Description |
|---|---|
|
Operation completed successfully. |
|
Invalid parameter. |
|
A bad pointer was passed in. |
|
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 this 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 more information, see Smart Card Return Values.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client |
Windows XP [desktop apps only] |
| Minimum supported server |
Windows Server 2003 [desktop apps only] |
| End of client support |
Windows XP |
| End of server support |
Windows Server 2003 |
| Header |
|
| Type library |
|
| DLL |
|
| IID |
IID_ISCardISO7816 is defined as 53B6AA68-3F56-11D0-916B-00AA00C18068 |
See also