pcscML

Module PcscML

1. This function creates a communication context to the PC/SC Resource Manager. This MUST be the first function called in a PC/SC application It accepts the following parameters:

INPUT
1. scope - Scope of the establishment. This can be either a remote or local connection, possible values are:
  1. scard_scope_user - Not used
  2. scard_scope_terminal - Not used
  3. scard_scope_system - Services on the Local machine
  4. scard_scope_global - Services are on a remote machine
2. vReserved1 - Should be unit when not used, but if scard_scope_global is used then vReserved1 is a string which is the hostname of the machine in which the Resource Manager services reside.
3. vReserved2 - Reserved for future use, call value is unit
OUTPUT is a tupple with the next 2 values:
1. resultValue - Possible values to resultValue
  1. scard_s_success - Successful
  2. scard_e_invalid_value - Invalid scope type passed
2. hContext - Returned reference of this connection. Viewing purposes only

Example: let rv = sCardEstablishContext scard_scope_system () ()

external sCardEstablishContext : int → α → unit → (int × int) = "sCardEstablishContextML"

2. This function destroys the communication context to the PC/SC Resource manager. This MUST be the last function called in a PC/SC application It accepts the following parameters:

INPUT - Only input parameter is unit
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Successful
  2. scard_e_invalid_handle - Invalid context. There is no active Resource manager connection

Example: let rv = sCardReleaseContext ()

external sCardReleaseContext : unit → int = "sCardReleaseContextML"

3. This function returns a list of currently available readers on the system. This string is saved in the mszReaders return parameter. The readers names will be a multi-string separated by "00" and ended by "00 00". Example: "readerA 00 readerB 00 00" It accepts the following parameters:

INPUT - Only input parameter is unit
OUTPUT - Is a tupple with the next 2 values
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Successful
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_insufficient_buffer - Reader buffer not large enough
  4. scard_e_reader_unavailable - No readers available
2. mszReaders - Multi-string with the list of readers

Example: let rv = sCardListReaders ()

external sCardListReaders : unit → (int × string array) = "sCardListReadersML"

4. This function establishes a connection to the friendly name of the reader specified in szReader. The first connection will power up and perform a reset on the card. //ATTENTION, THIS FUNCTION RETURNS DIFERENT TO OCAML THEN LINUX, IT JUST RETURNS ONE "0" IN THE MULTY STRING... It accepts the following parameters:

INPUT
1. szReader - Reader name to connect to
2. dwShareMode - Mode of connection type: exclusive or shared
  1. scard_share_shared - This application will allow others to share the reader
  2. scard_share_exclusive - This application will NOT allow others to share the reader
3. dwPreferredProtocols - Desired protocol use
  1. scard_protocol_t0 - Use the T = 0 protocol
  2. scard_protocol_t1 - Use the T = 1 protocol
  3. scard_protocol_raw - Use with memory type cards
OUTPUT - Is a tupple with the next 3 values
1. resultValue - Possible values to resultValue
  1. scard_s_success - Success
  2. scard_e_no_smartcard - Smartcard is not inserted
  3. scard_e_not_ready - Could not allocate the desired port
  4. scard_e_invalid_value - Invalid sharing mode, requested protocol, or reader name
  5. scard_e_reader_unavailable - Could not power up the reader or the card
  6. scard_e_unsupported_feature - Protocol not supported
  7. scard_e_sharing_violation - Someone else has exclusive rights
  8. scard_e_invalid_handle - There is no active Resource manager connection
2. hCard - Handle to this connection
3. dwActiveProtocol - Established protocol to this connection
  1. scard_protocol_t0 - T = 0 protocol
  2. scard_protocol_t1 - T = 1 protocol

Example1: let rv = sCardConnect szReader scard_share_shared scard_protocol_t0 Example2: let rv = sCardConnect "reader 00 00" scard_share_shared scard_protocol_t1

external sCardConnect : string → int → int → (int × int × int) = "sCardConnectML"

5. This function reestablishes a connection that was previously connected to using sCardConnect. In a multi application environment it is possible for an application to reset the card in shared mode. When this occurs any other application trying to access certain commands will be returned the value scard_w_reset_card. When this occurs sCardReconnect must be called in order to acknowledge that the card was reset and allows it to change its state accordingly. It accepts the following parameters:

INPUT
1. hCard - Handle to a previous call to connect
2. dwShareMode - Mode of connection type: exclusive or shared
  1. scard_share_shared - This application will allow others to share the reader
  2. scard_share_exclusive - This application will NOT allow others to share the reader
3. dwPreferredProtocols - Desired protocol use
  1. scard_protocol_t0 - Use the T = 0 protocol
  2. scard_protocol_t1 - Use the T = 1 protocol
  3. scard_protocol_raw - Use with memory type cards
4. dwInitialization - Desired action taken on the card/reader
  1. scard_leave_card - Do nothing
  2. scard_reset_card - Reset the card
  3. scard_unpower_card - Unpower the card
  4. scard_eject_card - Eject the card
OUTPUT - Is a tupple with the next 2 values
1. resultValue - Possible values to resultValue
  1. scard_s_success - Success
  2. scard_e_not_ready - Could not allocate the desired port
  3. scard_e_invalid_value - Invalid sharing mode, requested protocol, or reader name
  4. scard_e_reader_unavailable - Could not power up the reader or the card
  5. scard_e_unsupported_feature - Protocol not supported
  6. scard_e_sharing_violation - Someone else has exclusive rights
  7. scard_e_invalid_handle - There is no active Resource manager connection
2. dwActiveProtocol - Established protocol to this connection
  1. scard_protocol_t0 - T = 0 protocol
  2. scard_protocol_t1 - T = 1 protocol

Example: let buffer = [|c0₁₆; A4₁₆; 00₁₆; 00₁₆; 02₁₆; 3f₁₆; 00₁₆|] in let rv = sCardTransmit hCard (scard_protocol_t0, 0) buffer 7 in let (returnValue, _, _) = rv in if(returnValue ≡ scard_w_reset_card) then ( let rv2 = sCardReconnect hCard scard_share_shared scard_protocol_t0 scard_reset_card ) else ()

external sCardReconnect : int → int → int → int → (int × int) = "sCardReconnectML"

6. This function terminates the connection made through sCardConnect It accepts the following parameters:

INPUT
1. hCard - Connection made from sCardConnect
2. dwDisposition - Reader function to execute
  1. scard_leave_card - Do nothing
  2. scard_reset_card - Reset the card
  3. scard_unpower_card - Unpower the card
  4. scard_eject_card - Eject the card
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_success - Successful
  2. scard_e_invalid_handle - Invalid hCard handle
  3. scard_e_invalid_value - Invalid dwDisposition
  4. scard_w_reset_card - Card was reset

Example: let rv = sCardDisconnect hCard scard_leave_card

external sCardDisconnect : int → int → int = "sCardDisconnectML"

7. This function establishes a temporary exclusive access mode for doing a series of commands or transaction. You might want to use this when you are selecting a few files and then writing a large file so you can make sure that another application will not change the current file. If another application has a lock on this or this application is in scard_share_exclusive there will be no action taken It accepts the following parameters:

INPUT
1. hCard - Connection made from sCardConnect
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_success - Successful
  2. scard_e_invalid_handle - Invalid hCard handle
  3. scard_e_sharing_violation - Someone else has exclusive rights
  4. scard_w_reset_card - Card was reset

Example: let rv = sCardBeginTransaction hCard

external sCardBeginTransaction : int → int = "sCardBeginTransactionML"

8. This function ends a previously begun transaction. The calling application must be the owner of the previously begun transaction or an error will occur. dwDisposition is not currently used in this release. It accepts the following parameters:

INPUT
1. hCard - Connection made from sCardConnect
2. dwDisposition - Possible values to dwDisposition (Not Used)
  1. scard_leave_card - Do nothing
  2. scard_reset_card - Reset the card
  3. scard_unpower_card - Unpower the card
  4. scard_eject_card - Eject the card
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_success - Successful
  2. scard_e_sharing_violation - Someone else has exclusive rights
  3. scard_e_invalid_handle - Invalid hCard handle

Example: let rv = sCardEndTransaction hCard scard_leave_card

external sCardEndTransaction : int → int → int = "sCardEndTransactionML"

9. This function sends an APDU to the smart card contained in the reader connected to by sCardConnect. The card responds from the APDU and stores this response in pbRecvBuffer. It accepts the following parameters:

INPUT
1. hCard - Connection made from sCardConnect
2. pioSendPci - Is a tupple with the following 2 values
  1. dwProtocol - scard_protocol_t0 or scard_protocol_t1
  2. cbPciLength - Length of this structure (not used, value should be 0)
3. pbSendBuffer - APDU to send to the card
4. dwSendLength - Length of the APDU
OUTPUT - Is a tupple with the following 3 values
1. resultValue - Possible values to resultValue
  1. scard_s_success - Successful
  2. scard_e_not_transacted - APDU exchange not successful
  3. scard_e_invalid_handle - There is no active Resource manager connection
  4. scard_e_proto_mismatch - Connect protocol is different than desired
  5. scard_e_invalid_value - Invalid protocol, reader name, etc
  6. scard_w_reset_card - Card was reset
2. pioRecvPci - Is a tupple with the following 2 values
  1. dwProtocol - scard_protocol_t0 or scard_protocol_t1
  2. cbPciLength - Length of this structure
3. pbRecvBuffer - Response from the card

Example: let pbSendBuffer = ∣C0₁₆; A4₁₆; 00₁₆; 00₁₆; 02₁₆; 3F₁₆; 00₁₆|] in let leng = Array.length pbSendBuffer in let rv = sCardTransmit hCard (scard_protocol_t0, 0) pbSendBuffer leng
external sCardTransmit : int → (int × int) → int array → int → int × (int × int) × int array = "sCardTransmitML"

10. This function return the current status of the reader connected to by hCard. Its friendly name will be stored in szRederName. cchReaderLen will be the size of the allocated buffer for szReaderName. The current state and protocol will be stored in dwState and dwProtocol respectively It accepts the following parameters:

INPUT
1. hCard - Connection made from sCardConnect
OUTPUT - Is a tupple with the following 7 values
1. resultValue - Possible values to resultValue
  1. scard_s_success - Successful
  2. scard_e_invalid_handle - Invalid hCard handle
  3. scard_e_inssuficient_buffer - Not enough allocated memory for szReaderName
  4. scard_w_reset_card - Card was reseted
2. szReaderName - Friendly name of the reader
3. dwState - Current state of the reader
  1. scard_absent - There is no card in the reader
  2. scard_present - There is a card in the reader, but it has not been moved into position for use
  3. scard_swallowed - There is a card in the reader for use. The card is not powered
  4. scard_powered - Power is being provided to the card, but the reader driver is unaware of the mode of the card
  5. scard_negotiablemode - The card has been reset and is awaiting PTS negotiation
  6. scard_specificmode - The card has been reset and specific communication protocols have been established
4. dwProtocol - Current protocol of this reader
  1. scard_protocol_t0 - Use the T = 0 protocol
  2. scard_protocol_t1 - Use the t = 1 protocol
5. cchReaderLen - Size of the szReaderName string
6. atr - Current ATR of a card in this reader
7. cbAtrLen - Length of the ATR

Example: let rv = sCardStatus hCard

external sCardStatus : int → (int × string × int × int × int × int array × int) = "sCardStatusML"

11. This function receives a structure or list of structures containing readers names. It then blocks for a change in state to occur on any of the OR'd values contained in the dwCurrentState for a maximum blocking time of dwTimeOut or forever. The function will return immediately with the current state if dwTimeout is 0 and will wait forever if dwTimeout is infinite. The new event state will be contained in dwEventState. A status change might be a card insertion or removal event, a change in ATR, etc. This function currently only takes one reader as argument It accepts the following parameters:

INPUT
1. dwTimeOut - Maximum block waiting time for status change
2. szReader - Reader name
3. cReders - Number of structures. Value is 1
OUTPUT - Is a tupple with the following 2 values
1. resultValue - Possible values to resultValue
  1. scard_s_success - Successful
  2. scard_e_invalid_value - Invalid states, reader name, etc.
  3. scard_e_invalid_handle - There is no active Resource manager connection
2. ReaderStates - Is a tupple with the following 5 values
  1. reader - Reader name
  2. dwCurrentState - Current state of the reader
  3. dwEventState - Reader state after state change
  4. cbAtr - ATR Length
  5. rgbAtr - ATR value

Example: let rv = sCardGetStatusChange infinite "readerA" 1

external sCardGetStatusChange : int → string → int → int × (string × int × int × int × int array) = "sCardGetStatusChangeML"

12. This function cancels all pending blocking requests on the getStatusChange function. It accepts the following parameters:

INPUT - Only input parameter is unit
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_success - Success.
  2. scard_e_invalid_handle - There is no active Resource manager connection

Example: let rv = sCardCancel ()

external sCardCancel: unit → int = "sCardCancelML"

13. This function updates the working waiting time that RPC uses when waiting for a server function to return. This needs to be updated when a card command is sent that might take more time than usual It accepts the following parameters:

INPUT
1. dwTimeout - New timeout value
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_success - Success.
  2. scard_e_invalid_handle - There is no active Resource manager connection

Example: let rv = sCardSetTimeout 50 (* 50 seconds timeout *)

external sCardSetTimeout : int → int = "sCardSetTimeoutML"

14. This method supports direct communication with the Reader device. Its primary intent is to provide a mechanism to communicate with vendor-defined features. It is the responsibility of the vendor to define ControlCode values and input/output data associated with these features, some are defined in winsmcrd.h. It accepets the following parameters

INPUT
1. hCard - Connection made from sCardConnect
2. dwControlCode - Specifies the control code for the operation.
  1. ioctl_smartcard_power
  2. ioctl_smartcard_get_attribute
  3. ioctl_smartcard_set_attribute
  4. ioctl_smartcard_confiscate
  5. ioctl_smartcard_transmit
  6. ioctl_smartcard_eject
  7. ioctl_smartcard_swallow
  8. ioctl_smartcard_read - obsolete
  9. ioctl_smartcard_write - obsolete
  10. ioctl_smartcard_is_present
  11. ioctl_smartcard_is_absent
  12. ioctl_smartcard_set_protocol
  13. ioctl_smartcard_get_state
  14. ioctl_smartcard_get_last_error
  15. ioctl_smartcard_cancel_blocking
3. lpInBuffer - Buffer that contains the data required to perform the operation. This parameter can be unit if the dwControlCode parameter specifies an operation that does not require input data.
4. nInBufferSize - Size in bytes of lpInBuffer
5. nOutBufferSize - Size in bytes of lpOutBuffer
OUTPUT - Is a tupple with the following 3 values
1. resultValue - Possible values to resultValue
  1. scard_s_success - Success
  2. scard_e_not_transacted - Data exchange not successful
  3. scard_e_invalid_handle - Invalid hCard handle
  4. scard_e_invalid_value - Invalid value has been presented
  5. scard_e_reader_unavailable - The reader has been removed
  6. scard_w_reset_card - The card has been reseted by another application
  7. scard_w_removed_card - The card has been removed from the reader
2. lpOutBuffer - Buffer that receives the operation's output data. This parameter can be unit if the dwControlCode parameter specifies an operation that does not produce output data
3. lpBytesReturned - Size in bytes of the data stored into the buffer pointed to by lpOutBuffer

Example: let control = sCardControl hCard2 ioctl_smartcard_power () 0 255

external sCardControl : int → int → α → int → int → (int × string × int) = "sCardControlML"

15. * This function removes an introduced smart card from the smart card subsystem. It accepets the following parameters

INPUT
1. szCardName - 0 terminated string that contains the friendly name of the card to be removed from the smart card database
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_reader_unavailable - The reader has been removed
  4. scard_w_reset_card - The card has been reseted by another application
  5. scard_w_removed_card - The card has been removed from the reader
  6. check for more values

Example: let rvForgetCard = sCardForgetCardType "myCard"

external sCardForgetCardType : string → int = "sCardForgetCardTypeML"

16. * The SCardListCards function searches the smart card database and provides a list of named cards previously introduced to the system by the user In the next version 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 Note: To return all smart cards introduced to the subsystem, set pbAtr and rgguidInterfaces to unit. It accepets the following parameters

INPUT
1. pbAtr - ATR string to compare to known cards, or unit if no ATR matching is to be performed
2. cpbAtr - Number of entries in the pbAtr array. If pbAtr is unit, then this value is ignored.
3. rgguidInterfaces - Array of identifiers GUIDs, or unit if no interface matching is to be performed
4. cguidCount - Number of entries in the rgguidInterfaces array. If rgguidInterfaces is unit, then this value is ignored.
OUTPUT - Is a tupple with the following 3 values
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Successful
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_insufficient_buffer - Reader buffer not large enough
  4. scard_e_reader_unavailable - No readers available
2. mszCards - Multi-string with the list of cards
3. cchCards - Receives the actual length of the multi-string structure, including all trailing null characters

Example: let rvListCards = sCardListCards () 0 () 0 let myGuid = (3BCDEF01₁₆, ABCD₁₆, ABCD₁₆, [|AA₁₆; BB₁₆; CC₁₆; DD₁₆; A9₁₆; BB₁₆; CC₁₆; DD₁₆|]) in let myATR = [|aa₁₆; bb₁₆; cc₁₆; 00₁₆; dd₁₆|] in let rvListCards = sCardListCards myAtr 5 [|myGuid|] 1

external sCardListCards : α → int → β → int → int × string array × int = "sCardListCardsML"

17. * This function introduces a new name for an existing smart card reader. Note Smart card readers are automatically introduced to the system; a smart card reader vendor's setup program can also introduce a smart card reader to the system. All readers installed on the system are automatically introduced by their system name. Typically, SCardIntroduceReader is called only to change the name of an existing reader The SCardIntroduceReader function is a database management function It accepts the following parameters

INPUT
1. hCard - Handle of the card in the reader who name will be changed (used to get data for the change)
2. szDeviceName - System name of the smart card reader, for example, "MyReader 01"
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_reader_unavailable - The reader has been removed
  4. scard_w_reset_card - The card has been reseted by another application
  5. scard_w_removed_card - The card has been removed from the reader
  6. check for more values

Example: let rv = SCardIntroduceReader hCard "My New Reader Name" in Dont forget also to check error values

external sCardIntroduceReader : int → string → int = "sCardIntroduceReaderML"

18. * 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. It accepts the following parameters

INPUT
1. szReaderName - Display name of the reader to be removed from the smart card database.
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_reader_unavailable - The reader has been removed
  4. scard_w_reset_card - The card has been reseted by another application
  5. scard_w_removed_card - The card has been removed from the reader
  6. check for more values

Example: let rvForgetCard = sCardForgetReader "myReader"

external sCardForgetReader : string → int = "sCardForgetReaderML"

19. * The SCardIntroduceCardType function introduces a smart card to the smart card subsystem (for the active user) by adding it to the smart card database. It requires a Stub function because it has more then 5 arguments, but that's transparent for the API user It accepts the following parameters

INPUT
1. szCardName - Name by which the user can recognize the card
2. guidPrimaryProvider - Identifier (GUID) for the smart card's primary service provider
3. rgguidInterfaces - Array of identifiers (GUIDs) that identify the interfaces supported by the smart card
4. dwInterfaceCount - Number of identifiers in the rgguidInterfaces array
5. pbAtr - ATR string that can be used for matching purposes when querying the smart card database
6. pbAtrMask - Optional bitmask to use when comparing the ATRs of smart cards to the ATR supplied in pbAtr. If this value is non-unit, it must be 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 AND
7. atrLength - Length of pbAtr
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_reader_unavailable - The reader has been removed
  4. scard_w_reset_card - The card has been reseted by another application
  5. scard_w_removed_card - The card has been removed from the reader
  6. check for more values - Lalala

Example: let myGuid = (3BCDEF00₁₆, ABCD₁₆, ABCD₁₆, [|AA₁₆; BB₁₆; CC₁₆; DD₁₆; AA₁₆; BB₁₆; CC₁₆; DD₁₆|]) in \\ let myATR = [|aa₁₆; bb₁₆; cc₁₆; 00₁₆; dd₁₆|] in \\ let myATRMask = [|ff₁₆; ff₁₆; ff₁₆; 00₁₆; ff₁₆|] in \\ let rv = sCardIntroduceCardType "lalalalala" myGuid () 0 myATR myATRMask 5

external sCardIntroduceCardType : string → (int × int × int × int array) → α → int → int array → int array → int → int = "sCardIntroduceCardTypeML" "sCardIntroduceCardTypeStubML"

20. * 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 with SCardIntroduceCardType) and receives the registered identifier of the primary service provider GUID, if one exists. It accepts the following parameters

INPUT
1. szCard - Name of the card defined to the system.
OUTPUT - Represents a tupple with the following 2 values
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_reader_unavailable - The reader has been removed
  4. scard_w_reset_card - The card has been reseted by another application
  5. scard_w_removed_card - The card has been removed from the reader
  6. check for more values
2. guidProviderId - Identifier (GUID) of the primary service provider. This provider may be activated using COM, and will supply access to other services in the card. It represents a tupple with the following 4 values
  1. data1
  2. data2
  3. data3
  4. data4

external sCardGetProviderId : string → int × (int × int × int × int array) = "sCardGetProviderIdML"

21. * This 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. The SCardSetAttrib function is a direct card access function. It accepts the following parameters

INPUT
1. hCard - Reference value returned from SCardConnect
2. dwAttrId - Identifier for the attribute to set. The values are write-only. Note that vendors may not support all attributes
  1. scard_attr_supress_t1_ifs_request - Suppress sending of T=1 IFSD packet from the reader to the card. (Can be used if the currently inserted card does not support an IFSD request.)
3. pbAttr - buffer that supplies the attribute whose ID is supplied in dwAttrId
4. cbAttrLen - Length (in bytes) of the attribute value in the pbAttr buffef
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_reader_unavailable - The reader has been removed
  4. scard_w_reset_card - The card has been reseted by another application
  5. scard_w_removed_card - The card has been removed from the reader
  6. check for more values

* Example: let rv = sCardSetAttribute hCard dwAttrId pbAttr cbAttrLen

external sCardSetAttrib : int → int → int array → int → int = "sCardSetAttribML"

22. * This function gets the current reader attributes for the given handle. It does not affect the state of the reader, driver, or card. The pcbAttrLen function is a direct card access function It accepts the following parameters

INPUT
1. hCard - Reference value returned from SCardConnect
2. dwAttrId - Identifier for the attribute to get
  1. scard_attr_vendor_name
  2. scard_attr_vendor_ifd_type
  3. scard_attr_vendor_ifd_version
  4. scard_attr_vendor_ifd_serial_no
  5. scard_attr_channel_id
  6. scard_attr_protocol_types
  7. scard_attr_default_clk
  8. scard_attr_max_clk
  9. scard_attr_default_data_rate
  10. scard_attr_max_data_rate
  11. scard_attr_max_ifsd
  12. scard_attr_power_mgmt_support
  13. scard_attr_user_to_card_auth_device
  14. scard_attr_user_auth_input_device
  15. scard_attr_characteristics
  16. scard_attr_current_protocol_type
  17. scard_attr_current_clk
  18. scard_attr_current_f
  19. scard_attr_current_d
  20. scard_attr_current_n
  21. scard_attr_current_w
  22. scard_attr_current_ifsc
  23. scard_attr_current_ifsd
  24. scard_attr_current_bwt
  25. scard_attr_current_cwt
  26. scard_attr_current_ebc_encoding
  27. scard_attr_current_bwt
  28. scard_attr_icc_presence
  29. scard_attr_icc_interface_status
  30. scard_attr_current_io_state
  31. scard_attr_atr_string
  32. scard_attr_icc_type_per_atr
  33. scard_attr_esc_reset
  34. scard_attr_esc_cancel
  35. scard_attr_esc_authrequest
  36. scard_attr_maxinput
  37. scard_attr_device_unit
  38. scard_attr_device_in_use
  39. scard_attr_device_friendly_name_a
  40. scard_attr_device_system_name_a
  41. scard_attr_device_friendly_name_w - Unicode
  42. scard_attr_device_system_name_w - Unicode
  43. scard_attr_supress_t1_ifs_request
OUTPUT - Represents a tupple with the following 2 values
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_reader_unavailable - The reader has been removed
  4. scard_w_reset_card - The card has been reseted by another application
  5. scard_w_removed_card - The card has been removed from the reader
  6. check for more values
2. pbAttr - Buffer that receives the attribute whose ID is supplied in dwAttrId
3. pcbAttrLen - Length of the pbAttr buffer in bytes

Example: let rv = sCardGetAttrib hCard scard_attr_vendor_name

external sCardGetAttrib : int → (int × int) → int × int array × int = "sCardGetAttribML"

23. * This 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 The SCardListInterfaces function is a database query function It accepts the following parameters

INPUT
1. szCard - Name of the smart card already introduced to the smart card subsystem
OUTPUT - It's a tupple with the following 3 values
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_reader_unavailable - The reader has been removed
  4. scard_w_reset_card - The card has been reseted by another application
  5. scard_w_removed_card - The card has been removed from the reader
  6. check for more values
2. pguidInterfaces - Array of interface identifiers (GUIDs) that indicate the interfaces supported by the smart card
3. pcguidInterfaces - Size of the pcguidInterfaces array

Example: let rv = sCardListInterfaces "my_card"

external sCardListInterfaces : string → int × (int × int × int × int array) array × int = "sCardListInterfacesML"

24. * This function searches the readers available int the system for a card with an ATR string that matches one of the card names specified in mszCards, returning immediately with the result This service is especially useful when used in conjunction with SCardGetStatusChange. If no matching cards are found by means of SCardLocateCards, the calling application may use SCardGetStatusChange to wait for card availability changes The SCardLocateCards function is a smart card tracking function It accepts the following parameters

INPUT
1. mszCards - A multiple string that contains the names of the cards to search for
OUTPUT - Is a tupple with the following 2 values
1. resultValue - Possible values to resultValue
  1. scard_s_success - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_reader_unavailable - The reader has been removed
  4. scard_w_reset_card - The card has been reseted by another application
  5. scard_w_removed_card - The card has been removed from the reader
  6. check for more values
2. rgReaderStates - An array of scardreaderstate structures with the results of the search
  1. szReader - The name of the reader being monitored
  2. pvUserData - Not used by the smart card subsystem. This number is used by the application
  3. dwCurrentState - Current state of the reader, as seen by the application
    1. scard_state_unaware - The application is unaware of the current state, and would like to know *
    2. scard_state_ignore - The application is not interested in this reader *
    3. scard_state_unavailable - The application believes that this reader is not available for use
    4. scard_state_empty - The application believes that there is no card in the reader
    5. scard_state_present - The application believes that there is a card in the reader
    6. scard_state_atrmatch - The application believes that there is a card in the reader with an ATR matching one of the target cards
    7. scard_state_exclusive - The application believes that the card in the reader is allocated for exclusive use by another application
    8. 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
    9. scard_state_mute - The application believes that there is an unresponsive card in the reader
    10. scard_specificmode - The card has been reset and specific communication protocols have been established
  4. dwEventState - Current state of the reader, as known by the smart card resource manager
    1. scard_state_ignore - The application is not interested in this reader
    2. scard_state_changed - There is a difference between the state believed by the application, and the state known by the resource manager
    3. scard_state_unknown - The given reader name is not recognized by the resource manager
    4. scard_state_unavailable - The application believes that this reader is not available for use
    5. scard_state_empty - The application believes that there is no card in the reader
    6. scard_state_present - The application believes that there is a card in the reader
    7. scard_state_atrmatch - The application believes that there is a card in the reader with an ATR matching one of the target cards
    8. scard_state_exclusive - The application believes that the card in the reader is allocated for exclusive use by another application
    9. 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
    10. scard_state_mute - The application believes that there is an unresponsive card in the reader
  5. cbAtr - Number of bytes in the returned ATR.
  6. rgbAtr - ATR of the inserted card, with extra alignment bytes

Example: let rv = sCardLocateCards "my_card"

external sCardLocateCards : string → int × (string × int × int × int × int × int array) array = "sCardLocateCardsML"

25. * This 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. The sCardIntroduceReaderGroup function is provided for PC/SC specification compatibility. Reader groups are not stored until a reader is added to the group. The SCardIntroduceReaderGroup function is a database management function It accepts the following parameters

INPUT
1. szGroupName - Supplies the display name to be assigned to the new reader group
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_reader_unavailable - The reader has been removed
  4. check for more values

Example: let rv = sCardIntroduceReaderGroups "my_group"

external sCardIntroduceReaderGroup : string → int = "sCardIntroduceReaderGroupML"

26. * This 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. The SCardForgetReaderGroup function is a database management function It accepts the following parameters

INPUT
1. szGroupName - Display name of the reader group to be removed. System-defined reader groups cannot be removed from the database
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_reader_unavailable - The reader has been removed
  4. check for more values

Example: let rv = sCardForgetReaderGroups "my_group"

external sCardForgetReaderGroup : string → int = "sCardForgetReaderGroupML"

27. * This function provides the list of reader groups that have previously been introduced to the system A group is returned only if it contains at least one reader. This includes the group SCard$DefaultReaders. The group SCard$AllReaders cannot be returned, since it only exists implicitly. The SCardListReaderGroups function is a database query function It accepts the following parameters

INPUT - Only input parameter is unit
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_reader_unavailable - The reader has been removed
  4. check for more values
2. mszGroups - Multi-string that lists the reader groups defined to the system and available to the current user on the current terminal
3. pcchGroups - Length of the mszGroups buffer in characters

Example: let rv = sCardListReaderGroups ()

external sCardListReaderGroups : unit → int × string × int = "sCardListReaderGroupsML"

28. * This function adds a reader to a reader group sCardAddReaderToGroup automatically creates the reader group specified if it does not already exist The sCardAddReaderToGroup function is a database management function It accepts the following parameters

INPUT
1. szReaderName - Display name of the reader that you are adding
2. szGroupName - Display name of the group to which you are adding the reader
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. check for more values

Example: let rv = sCardAddReaderToGroup "my_reader" "my_group"

external sCardAddReaderToGroup : string → string → int = "sCardAddReaderToGroupML"

29. * function removes a reader from an existing reader group. This function has no affect on the reader When the last reader is removed from a group, the group is automatically forgotten. The sCardRemoveReaderFromGroup function is a database management function It accepts the following parameters

INPUT
1. szReaderName - Display name of the reader to be removed
2. szGroupName - Display name of the group from which the reader should be removed
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. check for more values

Example: let rv = sCardAddReaderToGroup "readerA" "my_group"

external sCardRemoveReaderFromGroup : string → string → int = "sCardRemoveReaderFromGroupML"

30. * This function determines whether a smart card context handle is valid Call this function to determine whether a smart card context handle is still valid. After a smart card context handle has been set by SCardEstablishContext, it may become not valid if the resource manager service has been shut down. It accepts the following parameters

INPUT - Only input parameter is unit
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. error_invalid_handle - The hContext parameter is not valid

Example let rv = sCardIsValidContext

external sCardIsValidContext : unit → int = "sCardIsValidContextML"

31. * This function specifies the name of the module (dynamic link library) containing the provider for a given card name and provider type This function sets the provider name, while SCardGetCardTypeProviderName can be used to retrieve the provider name It accepts the following parameters

INPUT
1. szCardName - Name of the card type with which this provider name is associated
2. dwProviderId - Identifier for the provider associated with this card type
  1. scard_provider_primary - The function specifies the name of the smart card's primary service provider as a GUID string
  2. scard_provider_csp - The function specifies the name of the cryptographic service provider
3. szProvider - String variable being assigned as the provider name, representing the cryptographic service provider (CSP)
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. check for more values

Example: let rv = sCardSetCardTypeProviderName "my_card" scard_provider_primary "windowscard.dll"

external sCardSetCardTypeProviderName : string → int → string → int = "sCardSetCardTypeProviderNameML"

32. * This function returns the name of the module (dynamic link library) containing the provider for a given card name and provider type. Upon successful completion of this function, the value in szProvider can be used as the third parameter in a call to CryptAcquireContex It accepts the following parameters

INPUT
1. szCardName - Name of the card type with which this provider name is associated
2. dwProviderId - Identifier for the provider associated with this card type
  1. scard_provider_primary - The function specifies the name of the smart card's primary service provider as a GUID string
  2. scard_provider_csp - The function specifies the name of the cryptographic service provider
OUTPUT
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. check for more values
2. szProvider - String variable which will contain the retrieved provider name upon successful completion of this function
3. cchProvider - This value represents the actual number of characters, including the null terminator

Example let rv = sCardGetCardTypeProviderName "my_card" scard_provider_primary

external sCardGetCardTypeProviderName : string → int → int × string × int = "sCardGetCardTypeProviderNameML"

33. * function returns an event handle when an event signals that the smart card resource manager is started. The event-object handle can be specified in a call to one of the wait functions Do not close the handle returned by this function. When you have finished using the handle, decrement the reference count by calling the SCardReleaseStartedEvent function It accepts the following parameters

INPUT - Only input parameter is unit
OUTPUT
1. resultValue - Handle to the event or error code

Example let rv = sCardAccessStartedEvent ()

external sCardAccessStartedEvent : unit → int = "sCardAccessStartedEventML"

34. * This function function decrements the reference count for a handle acquired by using the SCardAccessStartedEvent function It Accepts the following parameters

INPUT
1. hStartedEventHandle - A HANDLE whose reference count is being decremented
OUTPUT - Returns unit

Example let _ = sCardReleaseContext handle

external sCardReleaseStartedEvent : int → unit = "sCardReleaseStartedEventML"

35. * This function function retrieves the number of transmit operations that have completed since the specified card reader was inserted It accepets the following parameters

INPUT
1. hCard - A handle to a smart card obtained from a previous call to sCardConnectML
OUTPUT - Is a tupple with the following 2 values
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_reader_unavailable - The reader has been removed
  4. scard_w_reset_card - The card has been reseted by another application
  5. scard_w_removed_card - The card has been removed from the reader
  6. check for more values
2. pcTransmitCount - Number of transmit operations that have completed since the specified card reader was inserted

Example: let rv = sCardGetTransmitCount hCard

external sCardGetTransmitCount : int → int × int = "sCardGetTransmitCountML"

36. * This function searches the readers listed in the rgReaderStates parameter for a card with an ATR string that matches one of the ATR masks specified in rgAtrMasks, returning immediately with the result This service is especially useful when used in conjunction with SCardGetStatusChange. If no matching cards are found by means of SCardLocateCards, the calling application may use SCardGetStatusChange to wait for card availability changes The sCardLocateCardsByATR function is a smart card tracking function It Accepts the following values

INPUT
1. rgAtrMasks - Array of SCARD_ATRMASK structures (OCaml tupple) that contain the names of the cards for which to search
  1. cbAtr - The number of bytes in the ATR and the mask
  2. rgbAtr - An array of BYTE values for the ATR of the card with extra alignment bytes
  3. rgbMask - An array of BYTE values for the mask for the ATR with extra alignment bytes
2. cAtrs - Number of elements in the rgAtrMasks array.
OUTPUT - Is a tupple with the following 2 values
1. resultValue - Possible values to resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_e_reader_unavailable - The reader has been removed
  4. scard_w_reset_card - The card has been reseted by another application
  5. scard_w_removed_card - The card has been removed from the reader
  6. check for more values
2. rgReaderStates - An array of scardreaderstate structures with the results of the search
  1. szReader - The name of the reader being monitored
  2. pvUserData - Not used by the smart card subsystem. This number is used by the application
  3. dwCurrentState - Current state of the reader, as seen by the application
    1. scard_state_unaware - The application is unaware of the current state, and would like to know
    2. scard_state_ignore - The application is not interested in this reader
    3. scard_state_unavailable - The application believes that this reader is not available for use
    4. scard_state_empty - The application believes that there is no card in the reader
    5. scard_state_present - The application believes that there is a card in the reader
    6. scard_state_atrmatch - The application believes that there is a card in the reader with an ATR matching one of the target cards
    7. scard_state_exclusive - The application believes that the card in the reader is allocated for exclusive use by another application
    8. 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
    9. scard_state_mute - The application believes that there is an unresponsive card in the reader
    10. scard_specificmode - The card has been reset and specific communication protocols have been established
  4. dwEventState - Current state of the reader, as known by the smart card resource manager
    1. scard_state_ignore - The application is not interested in this reader
    2. scard_state_changed - There is a difference between the state believed by the application, and the state known by the resource manager
    3. scard_state_unknown - The given reader name is not recognized by the resource manager
    4. scard_state_unavailable - The application believes that this reader is not available for use
    5. scard_state_empty - The application believes that there is no card in the reader
    6. scard_state_present - The application believes that there is a card in the reader
    7. scard_state_atrmatch - The application believes that there is a card in the reader with an ATR matching one of the target cards
    8. scard_state_exclusive - The application believes that the card in the reader is allocated for exclusive use by another application
    9. 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
    10. scard_state_mute - The application believes that there is an unresponsive card in the reader
  5. cbAtr - Number of bytes in the returned ATR.
  6. rgbAtr - ATR of the inserted card, with extra alignment bytes

Example: let rv = sCardLocateCards "my_card"

external sCardLocateCardsByATR : (int × int array × int array) array → int → int × (string × int × int × int × int × int array) array = "sCardLocateCardsByATRML"

37. * This function retrieves the value portion of a name-value pair from the global cache maintained by the Smart Card Resource Manager Only for Windows Vista(tm) * It accepets the following parameters

INPUT
1. cardIdentifier - a value that uniquely identifies a smart card. The name-value pair that this function reads from the global cache is associated with this smart card
  1. data1
  2. data2
  3. data3
  4. data4
2. freshnessCounter - The current revision of the cached data
3. lookupName - A null-terminated string that contains the name portion of the name-value pair for which to retrieve the value portion
OUTPUT - It's a tupple withe the following 3 values
1. resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_w_cache_item_not_found - The specified name-value pair was not found in the global cache
  4. scard_w_cache_item_stal - The specified name-value pair was older than requested and has been deleted from the cache
2. data - Contain the value portion of the name-value pair specified by the lookupName parameter
3. dataLen - Size, in bytes, of the data array

Example: To teste under Windows Vista(tm)

external sCardReadCache : (int × int × int × int array) × int × string → int × int array × int = "sCardReadCacheML"

38. * This function writes a name-value pair from a smart card to the global cache maintained by the Smart Card Resource Manager It accepets the following parameters

INPUT
1. cardIdentifier - a value that uniquely identifies a smart card. The name-value pair that this function reads from the global cache is associated with this smart card
  1. data1
  2. data2
  3. data3
  4. data4
2. freshnessCounter - The current revision of the cached data
3. lookupName - A null-terminated string that contains the name portion of the name-value pair for which to retrieve the value portion
4. data - Contain the value portion of the name-value pair specified by the lookupName parameter
5. dataLen - Size, in bytes, of the data array
OUTPUT
1. resultValue
  1. scard_s_sccess - Success
  2. scard_e_invalid_handle - There is no active Resource manager connection
  3. scard_w_cache_item_not_found - The specified name-value pair was not found in the global cache
  4. scard_w_cache_item_stal - The specified name-value pair was older than requested and has been deleted from the cache

Example: To teste under Windows Vista(tm)

external sCardWriteCache : (int × int × int × int array) × int × string × int array × int → int = "sCardWriteCacheML"

1 Index

PcscML (module), 1
sCardAccessStartedEvent, 33
sCardAddReaderToGroup, 28
sCardBeginTransaction, 7
sCardCancel, 12
sCardConnect, 4
sCardControl, 14
sCardDisconnect, 6
sCardEndTransaction, 8
sCardEstablishContext, 1
sCardForgetCardType, 15
sCardForgetReader, 18
sCardForgetReaderGroup, 26
sCardGetAttrib, 22
sCardGetCardTypeProviderName, 32
sCardGetProviderId, 20
sCardGetStatusChange, 11
sCardGetTransmitCount, 35
sCardIntroduceCardType, 19
sCardIntroduceReader, 17
sCardIntroduceReaderGroup, 25
sCardIsValidContext, 30
sCardListCards, 16
sCardListInterfaces, 23
sCardListReaderGroups, 27
sCardListReaders, 3
sCardLocateCards, 24
sCardLocateCardsByATR, 36
sCardReadCache, 37
sCardReconnect, 5
sCardReleaseContext, 2
sCardReleaseStartedEvent, 34
sCardRemoveReaderFromGroup, 29
sCardSetAttrib, 21
sCardSetCardTypeProviderName, 31
sCardSetTimeout, 13
sCardStatus, 10
sCardTransmit, 9
sCardWriteCache, 38

This document was translated from L^AT_EX by H^EV^EA.