/* -*- 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 "nsIPaymentActionResponse.idl"

/**
 * nsIPaymentUIService is the interface used by Gecko to communicate with the
 * payment UI.
 * In general, the implementation of this interface should be a service that
 * manages all payment UI components and receives the requested payment actions
 * from Gecko and perform the corresponding UI behavior.
 */
[scriptable, uuid(01f8bd55-9017-438b-85ec-7c15d2b35cdc)]
interface nsIPaymentUIService : nsISupports
{
  /**
   *  Show the payment UI to users.
   *  The implementation gets the payment data through nsIPaymentRequestService
   *  by the passed in requestId, then shows the payment UI and start to interact
   *  with users.
   *  According to user's action, nsIPaymentRequestService's APIs respondPayment,
   *  changeShippingAddress, or changeShippingOtpion is possible to called in the
   *  implementation.
   *  @param requestId - the request identify of the payment request.
   *                     Notice that this requestId is an internal request Id
   *                     generated by Gecko
   */
  void showPayment(in AString requestId);

  /**
   *  Abort the payment.
   *  The implementation must abort and close the showing payment UI then call
   *  nsIPaymentRequestService respondPayment with nsIPaymentAbortActionResponse
   *  to inform Gecko of the abort status.
   *  @param requestId - the request identify of the payment request.
   *                     Notice that this requestId is an internal request Id
   *                     generated by Gecko
   */
  void abortPayment(in AString requestId);

  /**
   *  Complete the payment.
   *  The implementation should close the showing payment UI, then call
   *  nsIPaymentRequestService respondPayment with nsIPaymentCompleteActionResponse
   *  to inform Gecko of the complete status.
   *  @param requestId - the request identify of the payment request.
   *                     Notice that this requestId is an internal request Id
   *                     generated by Gecko
   */
  void completePayment(in AString requestId);

  /**
   *  Update the payment data in the payment UI.
   *  The implementation should get the updated payment data through the
   *  nsIPaymentRequestService again, and update the UI.
   *  @param requestId - the request identify of the payment request.
   *                     Notice that this requestId is an internal request Id
   *                     generated by Gecko
   */
  void updatePayment(in AString requestId);

  /**
   *  Close the payment UI for the specified PaymentRequest.
   *  The implementation should clean up the PaymentRequest data saved in the UI
   *  component and close the UI if the specified PaymentRequest is showing to
   *  the user.
   *  Notice when the method is called, that means the PaymentRequest is invalid
   *  in nsIPaymentRequestService.
   *  @param requestId - the request identify of the payment request.
   *                     Notice that this requestId is an internal request Id
   *                     generated by Gecko
   */
  void closePayment(in AString requestId);

};

%{C++
#define NS_PAYMENT_UI_SERVICE_CID \
  { 0x01f8bd55, 0x9017, 0x438b, { 0x85, 0xec, 0x7c, 0x15, 0xd2, 0xb3, 0x5c, 0xdc } }
#define NS_PAYMENT_UI_SERVICE_CONTRACT_ID \
  "@mozilla.org/dom/payments/payment-ui-service;1"
%}