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:

  1. 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
  2. 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:

  1. INPUT - Only input parameter is unit
  2. 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:

  1. INPUT - Only input parameter is unit
  2. 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) = "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. It accepts the following parameters:

  1. 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
  2. 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:

  1. 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
  2. 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 = [|c016; A416; 0016; 0016; 0216; 3f16; 0016|] 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:

  1. 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
  2. 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:

  1. INPUT
    1. hCard - Connection made from sCardConnect
  2. 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:

  1. 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
  2. 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:

  1. 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
  2. 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 = ∣C016; A416; 0016; 0016; 0216; 3F16; 0016|] 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:

  1. INPUT
    1. hCard - Connection made from sCardConnect
  2. 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:

  1. INPUT
    1. dwTimeOut - Maximum block waiting time for status change
    2. szReader - Reader name
    3. cReders - Number of structures. Value is 1
  2. 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:

  1. INPUT - Only input parameter is unit
  2. 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:

  1. INPUT
    1. dwTimeout - New timeout value
  2. 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 = "sCardSetTimeout"


1  Index

This document was translated from LATEX by HEVEA.