/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* 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 "nsIVariant.idl"
#include "nsIPaymentRequest.idl"
#include "nsIPaymentActionRequest.idl"
#include "nsIPaymentActionResponse.idl"
#include "nsIPaymentAddress.idl"
#include "nsISimpleEnumerator.idl"
#include "nsIPaymentUIService.idl"

/**
 *  nsPaymentRequestService is used to manage the created PaymentRequest in the
 *  chrome process. It is also the IPC agent for payment UI to communicate with
 *  merchant side.
 */
[scriptable, builtinclass, uuid(cccd665f-edf3-41fc-ab9b-fc55b37340aa)]
interface nsIPaymentRequestService : nsISupports
{
  /**
   *  Get the nsIPaymentRequest through the given payment request identifier.
   *  @param aRequestId - the payment request identifier.
   *                      This is an internal id generated by Gecko.
   *  @return           - the requested payment request. null if there is no
   *                      coressponding nsIPaymentRequest for aRequestId.
   */
  nsIPaymentRequest getPaymentRequestById(in AString aRequestId);

  /**
   *  Get the enumerator for all managed nsIPaymentRequests.
   *  @return - an enumerator for all managed nsIPaymentRequests.
   */
  nsISimpleEnumerator enumerate();

  /**
   *  Send the user's response to the merchant.
   *  @param aResponse - the user's response.
   */
  void respondPayment(in nsIPaymentActionResponse aResponse);

  /**
   *  Inform the merchant the shipping addres has changed.
   *  @param requestId - the request identifier of the payment request.
   *  @param aAddress - the new payment address.
   */
  void changeShippingAddress(in AString requestId, in nsIPaymentAddress aAddress);

  /**
   *  Inform the merchant the shipping option has changed.
   *  @param requestId - the request identifier of the payment request.
   *  @param option - the shipping option ID string.
   */
  void changeShippingOption(in AString requestId, in AString option);

  /**
   *  Following APIs are for testing or platform code only. UI implementation
   *  should not use them.
   */
  /**
   *  Clean up the all managed payment requests.
   *  This API is for testing only.
   */
  void cleanup();

  /**
   *  Setup the customized nsIPaymentUIService.
   *  This API is for testing only.
   */
  void setTestingUIService(in nsIPaymentUIService aUIService);

  /**
   *  Request a specified action on the specified PaymentRequest.
   *  @param aRequest - the requested action.
   */
  void requestPayment(in nsIPaymentActionRequest aRequest);

  /**
   *  This is a cleanup function to break the association between
   *  nsIPaymentRequestService and nsIPaymentActionCallback.
   *  nsIPaymentActionCallback is an interface that registered to
   *  nsIPaymentRequestService when the merchant asks to perform actions, and it
   *  will be called when user's response send back to nsIPaymentRequestService.
   *  @param aCallback - the specified nsIPaymentActionCallback.
   */
  void removeActionCallback(in nsIPaymentActionCallback aCallback);
};

%{C++
#define NS_PAYMENT_REQUEST_SERVICE_CID \
  { 0xcccd665f, 0xedf3, 0x41fc, { 0xab, 0x9b, 0xfc, 0x55, 0xb3, 0x73, 0x40, 0xaa } }
#define NS_PAYMENT_REQUEST_SERVICE_CONTRACT_ID \
  "@mozilla.org/dom/payments/payment-request-service;1"
%}