/*
 * Licensed to OMTP Ltd. (OMTP) under one or more contributor license agreements.
 * See the NOTICE file distributed with this work for additional information regarding
 * copyright ownership.
 *
 * The Reference Implementation (save for such parts of the reference implementation made
 * available under separate terms and conditions) is made available under the terms of the
 * Apache License, version 2.0, subject to the condition that any "Works" and "Derivative
 * Works" used or distributed for commercial purposes must be and remain compliant with the
 * BONDI specification as promulgated by OMTP in each release. Your implementation of the
 * Reference Implementation (whether object or source) must maintain these conditions, and
 * you must notify any recipient of this condition in a conspicuous way.
 *
 * You may not use this BONDI Reference Implementation except in compliance with the License.
 *
 * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 or at
 * http://bondi.omtp.org/BONDI-LICENSE-2.0
 */

/**
 * \brief BONDI APDU module
 *
 * This module allows the communication between web application and a smart card by using
 * the Application Protocol Data Units (APDUs). An APDU is a short message represented by
 * bytes. APDU messages are either commands or responses.
 * APDU protocol is defined by ISO 7816-4
 *
 * \def-api-feature http://bondi.omtp.org/api/1.5/apdu.access
 * \brief Access to opening APDU Slot connection, used by APDUManager.createConnection
 * \device-cap apdu.access
 *
 * \def-api-feature http://bondi.omtp.org/api/1.5/apdu.openLogicalChannel
 * \brief Access to opening APDU connection to a card application using a logical channel, used by APDUConnection.openLogicalChannel
 * \device-cap apdu.openLogicalChannel
 *
 * \def-api-feature http://bondi.omtp.org/api/1.5/apdu.openDefaultChannel
 * \brief Access to opening APDU connection to a card the default channel, used by APDUConnection.openDefaultChannel
 * \device-cap apdu.openDefaultChannel
 *
 * \def-api-feature http://bondi.omtp.org/api/1.5/apdu.transmit
 * \brief Access to sending an APDU command, used by APDUConnection.transmit
 * \device-cap apdu.transmit
 *
 *
 * \def-device-cap apdu.access
 * \brief Opens an connection between the device and a slot.
 * \param slot string representing the slot (e.g."slot0")
 *
 * \def-device-cap apdu.openLogicalChannel
 * \brief Opens an APDU connection between the device and an application in the UICC or any other secure element.
 * \param slot string representing the slot (e.g."slot0")
 * \param aid string representing the card application (e.g. "a0 00 00 00 62 03 01 0c 02 01")
 *
 * \def-device-cap apdu.openDefaultChannel
 * \brief Opens an APDU connection between the device and the UICC or any other secure element.
 * \param slot string representing the slot (e.g."slot0")
 *
 * \def-device-cap apdu.transmit
 * \brief Send an APDU command.
 * \param Class Class of the command
 * \param ins   Command instruction
 * \param P1    First parameter of the command
 * \param P2    Second parameter of the command
 *
 *
 * \author Daniel Coloma <dcoloma@tid.es>
 * \author Alessandro Ossoli <alessandro.ossoli@telecomitalia.it>
 * \author Stefano Vercelli <stefano.vercelli@telecomitalia.it>
 * \author Jean-Francois Arnaud <jean-francois.arnaud@gemalto.com>
 * \author Patrice Angelini <patrice.angelini@gemalto.com>
 * \author Laurent Lagosanto <laurent.lagosanto@gemalto.com>
 * \version 1.5
 */
module apdu {

	/**
	 * \brief Array of smart cards or secure elements slots.
	 */
	typedef sequence<APDUSlot> APDUSlotArray;

	[Callback=FunctionOnly, NoInterfaceObject] interface OpenSuccessCallback {
		/**
		 * \brief To be invoked when the APDU connection is opened
		 *
		 * \param channel the logical channel used for this connection
		 */
		void onSuccess (in short channel);
	};

	[Callback=FunctionOnly, NoInterfaceObject] interface TransmitSuccessCallback {
		/**
		 * \brief To be invoked when the APDU response is received
		 *
		 * \param response Response to the APDU command
		 */
		void onSuccess (in ByteArray response);
	};

	interface APDUError : GenericError {

		/**
		 * \brief The channel is already open
		 */
		const unsigned short CHANNEL_OPEN_ERROR = 1;

		/**
		 * \brief The channel is not open.
		 */
		const unsigned short CHANNEL_NOT_OPEN_ERROR = 2;
	};

	/**
	 * \brief Management of the APDU communication.
	 *
	 *  Provides a way to open communication with a smart card or secure element slot.
	 *
	 * \code
	 *  var slot = availableSlots[0];
	 *  var cnx;
	 *  cnx = APDUManager.createConnection(slot);
	 * \endcode
	 */
	interface APDUManager {

		/**
		 * \brief The list of available slots on the device.
		 *
		 * Might be updated if a new slot appears (e.g. a bluetooth enabled card reader)
		 */
		readonly attribute APDUSlotArray availableSlots;

		/**
		 * \brief Creates an instance of the APDUConnection interface
		 *
		 * \api-feature http://bondi.omtp.org/api/apdu.access
		 *
		 * \param slot is one of the slots referenced by availableSlots.
		 * \return the object containing the reference to the APDU Connection
		 * \throw SecurityError PERMISSION_DENIED_ERROR when access is denied by the security policy.
		 * \throw DeviceAPIError INVALID_ARGUMENT_ERROR if an invalid slot is passed
		 */
		APDUConnection createConnection(in APDUSlot slot)
			raises(SecurityError, DeviceAPIError);
	};

	/**
	 * \brief Interface to communicate through APDU commands.
	 *
	 * \code
	 *  var cnx;
	 *
	 *  // Define the APDUExchange success callback.
	 *  function APDUSuccess(response) {
	 *    alert("APDU Response is " + response);
	 *  }
	 *
	 *  // Define the APDUExchange failure callback.
	 *  function APDUFailure(e) {
	 *    alert("Error while executing the APDU Command");
	 *  }
	 *
	 *  // Define the open success callback.
	 *  function openSuccess() {
	 *    alert("APDU Connection opened successfully");
	 *
	 *      // send a select file ( selection of 3F00)
	 *      var data = new ByteArray(1);
	 *
	 *      data[0] = 0x3F;
	 *      data[1] = 0x00;
	 *
	 *     cnx.transmit(APDUSuccess, APDUFailure, 0x00, 0xA4, 0x00, 0x02, data, 0x00);
	 *   }
	 *
	 *  // Define the open failure callback.
	 *  function openFailure(e) {
	 *    alert("Cannot open the APDUSlot connection");
	 *  }
	 *
	 *  var slot = availableSlots[0];
	 *  var aid = "a0 00 00 00 62 03 01 0c 02 01";
	 *
	 *  cnx = APDUManager.createConnection(slot);
	 *  // Get ATR
	 *  var ATR = cnx.GetAnswerToReset();
	 *  cnx.openLogicalChannel(openSuccess, openFailure, aid);
	 * \endcode
	 *
	 */
	interface APDUConnection {

		/**
		 * \brief The slot used by this connection
		 *
		 */
		readonly attribute APDUSlot slot;

		/**
		 * \brief Card application identifier
		 *
		 */
		readonly attribute DOMString aid;

		/**
		 * \brief The logical channel used by this connection
		 *
		 */
		readonly attribute short channel;

		/**
		 * \brief Tells whether a card is present in this slot
		 *
		 * \return true if a card is present, or false.
		 */
		boolean isCardPresent();

		/**
		 * \brief Opens the APDU Connection to a card application,
		 * using a logical channel chosen by the system.
		 *
		 * Errors that can be returned in the ErrorCallback:
		 * SecurityError PERMISSION_DENIED_ERROR when access is denied by the security policy.
		 * DeviceAPIError IO_ERROR if the communication with the slot fails
		 * DeviceAPIError INVALID_ARGUMENT_ERROR if an invalid aid is passed
		 * DeviceAPIError PENDING_OPERATION_ERROR if another Open APDU operation is being processed
		 * APDUError CHANNEL_OPEN_ERROR if the channel is already open
		 *
		 * \api-feature http://bondi.omtp.org/api/1.5/apdu.openLogicalChannel
		 *
		 * \param successCallback Callback issued when the opening is correctly finished.
		 * \param errorCallback Callback issued if an error occurs during the opening.
		 * \param aid the application identifier of the application (e.g. "a0 00 00 00 62 03 01 0c 02 01").
		 * \return PendingOperation enabling the requester to cancel this request.
		 */
		PendingOperation openLogicalChannel(in OpenSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString aid);

		/**
		 * \brief Opens the APDU Connection to a card in a slot
		 * using the default logical channel if available.
		 *
		 * Errors that can be returned in the ErrorCallback:
		 * SecurityError PERMISSION_DENIED_ERROR when access is denied by the security policy.
		 * DeviceAPIError IO_ERROR if the communication with the slot fails
		 * DeviceAPIError PENDING_OPERATION_ERROR if another Open APDU operation is being processed
		 * APDUError CHANNEL_OPEN_ERROR if the channel is already open
		 *
		 * \api-feature http://bondi.omtp.org/api/1.5/apdu.openDefaultChannel
		 *
		 * \param successCallback Callback issued when the opening is correctly finished.
		 * \param errorCallback Callback issued if an error occurs during the opening.
		 * \return PendingOperation enabling the requester to cancel this request.
		 */
		PendingOperation openDefaultChannel(in SuccessCallback successCallback, in ErrorCallback errorCallback);

		/**
		 * \brief Closes the APDU Connection
		 *
		 * Closes the APDU Connection.
		 *
		 * \throw DeviceAPIError PENDING_OPERATION_ERROR if an Open APDU operation is being processed
		 * \throw DeviceAPIError IO_ERROR if the communication with the slot fails
		 * \throw APDUError CHANNEL_NOT_OPEN_ERROR if the channel is not open
		 */
		void close()
			raises(DeviceAPIError, APDUError);

		/**
		 * \brief Get Answer To Reset
		 *
		 * Get Answer To Reset.
		 * \return ATR if successful
		 */
		ByteArray GetAnswerToReset();

		/**
		 * \brief Sends an APDU command
		 *
		 * Sends the APDU command to the card.
		 * When the card sends its response APDU, the successCallback is invoked containing the response as another byte array.
		 *
		 * Errors that can be returned in the ErrorCallback:
		 * DeviceAPIError IO_ERROR if the communication with the slot fails
		 * DeviceAPIError INVALID_ARGUMENT_ERROR if any of the parameters is not valid
		 * DeviceAPIError PENDING_OPERATION_ERROR if another open or transmit operation is being processed
		 * APDUError CHANNEL_NOT_OPEN_ERROR if the channel is not open
		 *
		 * \api-feature http://bondi.omtp.org/api/1.5/apdu.transmit
		 *
		 * \param Class       Class of the APDU command as defined in ISO 7816-4
		 * \param Instruction Command Instruction as defined in ISO 7816-4
		 * \param P1          First Parameter of the APDU command as defined in ISO 7816-4
		 * \param P2          Second Parameter of the APDU command as defined in ISO 7816-4
		 * \param Lc          Length of the APDU message
		 * \param message     APDU message data to sent
		 * \param Le          Length of the expected answer
		 * \param successCallback Callback issued when the operation is correctly finished.
		 * \param errorCallback Callback issued if an error occurs during the operation.
		 * \return PendingOperation enabling the requester to cancel this request.
		 */
		PendingOperation transmit(in TransmitSuccessCallback successCallback, in ErrorCallback errorCallback, in Byte Class, in Byte Instruction, in Byte P1, in Byte P2, in unsigned short Lc, in ByteArray message, in unsigned short Le);
	};

	/**
	 * \brief Definition of a card or secure element Slot.
	 *
	 */
	interface APDUSlot {

		/**
		 * \brief the numerical identifier of the slot.
		 * Used internally only.
		 */
		readonly attribute short id;

		/**
		 * \brief a human-readable description of the slot (e.g. "(U)SIM Slot".
		 * May be displayed to the user in a list so he can select which slot to use.
		 */
		readonly attribute DOMString description;
	};

};