gecko-dev/dom/nfc/nsINfcContentHelper.idl

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "nsIDOMDOMRequest.idl"

interface nsIVariant;

[scriptable, uuid(44eb02f4-6eba-4c12-8ed1-c142513776c9)]
interface nsINfcTagEvent : nsISupports
{
  readonly attribute nsIVariant techList;
};

[scriptable, uuid(8d77d653-f76a-4a21-ae3f-c4cc6074d8ec)]
interface nsINfcDOMEventTarget : nsISupports
{
  /**
   * Callback function used to notify tagfound.
   *
   * @param sessionToken
   *        SessionToken received from parent process
   * @param event
   *        nsINfcTagFoundEvent received from parent process.
   * @param ndefRecords
   *        NDEF records pre-read during tag-discovered.
   */
  void notifyTagFound(in DOMString sessionToken,
                      in nsINfcTagEvent event,
                      in nsIVariant ndefRecords);

  /**
   * Callback function used to notify taglost.
   *
   * @param sessionToken
   *        SessionToken received from parent process
   */
  void notifyTagLost(in DOMString sessionToken);

  /**
   * Callback function used to notify peerready.
   *
   * @param sessionToken
   *        SessionToken received from parent process
   */
  void notifyPeerReady(in DOMString sessionToken);

  /**
   * Callback function used to notify peerlost.
   *
   * @param sessionToken
   *        SessionToken received from parent process
   */
  void notifyPeerLost(in DOMString sessionToken);
};

[scriptable, uuid(cb9c934d-a7fa-422b-bcc1-4ac39741e6ec)]
interface nsINfcContentHelper : nsISupports
{
  const long NFC_EVENT_PEER_READY = 0x01;
  const long NFC_EVENT_PEER_LOST  = 0x02;

  void init(in nsIDOMWindow window);

  boolean checkSessionToken(in DOMString sessionToken);

  nsIDOMDOMRequest readNDEF(in nsIDOMWindow window, in DOMString sessionToken);
  nsIDOMDOMRequest writeNDEF(in nsIDOMWindow window, in nsIVariant records, in DOMString sessionToken);
  nsIDOMDOMRequest makeReadOnlyNDEF(in nsIDOMWindow window, in DOMString sessionToken);

  nsIDOMDOMRequest connect(in nsIDOMWindow window, in unsigned long techType, in DOMString sessionToken);
  nsIDOMDOMRequest close(in nsIDOMWindow window, in DOMString sessionToken);

  /**
   * Initiate send file operation.
   *
   * @param window
   *        Current window
   *
   * @param blob
   *        Raw data of the file to be sent. This object represents a file-like
   *        (nsIDOMFile) object of immutable, raw data. The blob data needs
   *        to be 'object wrapped' before calling this interface.
   *
   * @param sessionToken
   *        Current token
   *
   * Returns DOMRequest, if initiation of send file operation is successful
   * then 'onsuccess' is called else 'onerror'
   */
  nsIDOMDOMRequest sendFile(in nsIDOMWindow window,
                            in jsval blob,
                            in DOMString sessionToken);

  /**
   * Register the event target.
   *
   * @param target  An instance of the nsINfcDOMEventTarget.
   */
  void registerEventTarget(in nsINfcDOMEventTarget target);

  /**
   * Register the given application id with parent process
   *
   * @param window
   *        Current window
   *
   * @param appId
   *        Application ID to be registered
   */
  void registerTargetForPeerReady(in nsIDOMWindow window,
                                  in unsigned long appId);

  /**
   * Unregister the given application id with parent process
   *
   * @param window
   *        Current window
   *
   * @param appId
   *        Application ID to be registered
   */
  void unregisterTargetForPeerReady(in nsIDOMWindow window,
                                    in unsigned long appId);

  /**
   * Checks if the given application's id is a registered peer target (with the parent process)
   *
   * @param window
   *        Current window
   *
   * @param appId
   *        Application ID to be updated with parent process
   *
   * Returns DOMRequest, if appId is registered then 'onsuccess' is called else 'onerror'
   */
  nsIDOMDOMRequest checkP2PRegistration(in nsIDOMWindow window, in unsigned long appId);

  /**
   * Notify the parent process that user has accepted to share nfc message on P2P UI
   *
   * @param window
   *        Current window
   *
   * @param appId
   *        Application ID that is capable of handling NFC_EVENT_PEER_READY event
   */
  void notifyUserAcceptedP2P(in nsIDOMWindow window, in unsigned long appId);

  /**
   * Notify the status of sendFile operation to parent process
   *
   * @param window
   *        Current window
   *
   * @param status
   *        Status of sendFile operation
   *
   * @param requestId
   *        Request ID of SendFile DOM Request
   */
  void notifySendFileStatus(in nsIDOMWindow window,
                            in octet status,
                            in DOMString requestId);

  /**
   * Power on the NFC hardware and start polling for NFC tags or devices.
   */
  nsIDOMDOMRequest startPoll(in nsIDOMWindow window);

  /**
   * Stop polling for NFC tags or devices. i.e. enter low power mode.
   */
  nsIDOMDOMRequest stopPoll(in nsIDOMWindow window);

  /**
   * Power off the NFC hardware.
   */
  nsIDOMDOMRequest powerOff(in nsIDOMWindow window);
};