/* 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"

%{C++
#define ICC_STK_CMD_FACTORY_CONTRACTID \
  "@mozilla.org/icc/stkcmdfactory;1"
%}

interface nsIStkProactiveCmd;
interface nsIStkTerminalResponse;
interface nsIStkDownloadEvent;
interface nsIStkTimer;

/**
 * This StkCmdFactory provides series factory methods to create objects defined
 * in nsIStkProactiveCmd.idl and MozStkCommandEvent.webidl.
 */
[scriptable, uuid(743536c4-006f-11e5-a3f7-bf7a7fd59b9b)]
interface nsIStkCmdFactory : nsISupports
{
  /**
   * @param  aCommandDetails
   *         A JS object which complies with 'dictionary MozStkCommand'
   *         in MozStkCommandEvent.webidl
   *
   * @return a nsIStkProactiveCmd instance.
   */
  nsIStkProactiveCmd createCommand(in jsval aCommandDetails);

  /**
   * @param  aStkProactiveCmd
   *         a nsIStkProactiveCmd instance.
   *
   * @return a JS object which complies with 'dictionary MozStkCommand'
   *         in MozStkCommandEvent.webidl
   */
  jsval createCommandMessage(in nsIStkProactiveCmd aStkProactiveCmd);

  /**
   * @param  aStkProactiveCmd
   *         a nsIStkProactiveCmd instance.
   *
   * @return a JSON string which complies with 'dictionary MozStkCommand'
   *         in MozStkCommandEvent.webidl
   */
  AString deflateCommand(in nsIStkProactiveCmd aStkProactiveCmd);

  /**
   * @param  a JSON string which complies with 'dictionary MozStkCommand'
   *         in MozStkCommandEvent.webidl
   *
   * @return a nsIStkProactiveCmd instance.
   */
  nsIStkProactiveCmd inflateCommand(in AString aJSON);

  /**
   * @param aResponseMessage
   *        A JS object which complies with 'dictionary MozStkResponse'
   *        in MozStkCommandEvent.webidl
   *
   * @return a nsIStkTerminalResponse instance.
   */
  nsIStkTerminalResponse createResponse(in jsval aResponseMessage);

  /**
   * @param  aStkTerminalResponse
   *         a nsIStkTerminalResponse instance.
   *
   * @return a JS object which complies with 'dictionary MozStkResponse'
   *         in MozStkCommandEvent.webidl
   */
  jsval createResponseMessage(in nsIStkTerminalResponse aStkTerminalResponse);

  /**
   * @param  aStkTerminalResponse
   *         a nsIStkTerminalResponse instance.
   *
   * @return a JSON string which complies with 'dictionary MozStkResponse'
   *         in MozStkCommandEvent.webidl
   */
  AString deflateResponse(in nsIStkTerminalResponse aStkTerminalResponse);

  /**
   * @param  a JSON string which complies with 'dictionary MozStkResponse'
   *         in MozStkCommandEvent.webidl
   *
   * @return a nsIStkTerminalResponse instance.
   */
  nsIStkTerminalResponse inflateResponse(in AString aJSON);

  /**
   * @param aEventMessage
   *        A JS object which complies with 'dictionary MozStkXxxEvent'
   *        in MozStkCommandEvent.webidl
   *
   * @return a nsIStkDownloadEvent instance.
   */
  nsIStkDownloadEvent createEvent(in jsval aEventMessage);

  /**
   * @param  aStkDownloadEvent
   *         a nsIStkDownloadEvent instance.
   *
   * @return a JS object which complies with 'dictionary MozStkXxxEvent'
   *         in MozStkCommandEvent.webidl
   */
  jsval createEventMessage(in nsIStkDownloadEvent aStkDownloadEvent);

  /**
   * @param  aStkDownloadEvent
   *         a nsIStkDownloadEvent instance.
   *
   * @return a JSON string which complies with 'dictionary MozStkXxxEvent'
   *         in MozStkCommandEvent.webidl
   */
  AString deflateDownloadEvent(in nsIStkDownloadEvent aStkDownloadEvent);

  /**
   * @param  a JSON string which complies with 'dictionary MozStkXxxEvent'
   *         in MozStkCommandEvent.webidl
   *
   * @return a nsIStkDownloadEvent instance.
   */
  nsIStkDownloadEvent inflateDownloadEvent(in AString aJSON);

  /**
   * @param aStkTimerMessage
   *        a JS object which complies with 'dictionary MozStkTimer'
   *        in MozStkCommandEvent.webidl
   *
   * @return an instance of nsIStkTimer with the same timerId and timerValue
   *         from aStkTimerMessage.
   *
   * Note: This API is specific to nsIIcc::sendStkTimerExpiration().
   */
   nsIStkTimer createTimer(in jsval aStkTimerMessage);
};