1/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2/* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6#include "nsISupports.idl"
7#include "nsIPaymentActionResponse.idl"
8
9/**
10 * nsIPaymentUIService is the interface used by Gecko to communicate with the
11 * payment UI.
12 * In general, the implementation of this interface should be a service that
13 * manages all payment UI components and receives the requested payment actions
14 * from Gecko and perform the corresponding UI behavior.
15 */
16[scriptable, uuid(01f8bd55-9017-438b-85ec-7c15d2b35cdc)]
17interface nsIPaymentUIService : nsISupports
18{
19  /**
20   *  Show the payment UI to users.
21   *  The implementation gets the payment data through nsIPaymentRequestService
22   *  by the passed in requestId, then shows the payment UI and start to interact
23   *  with users.
24   *  According to user's action, nsIPaymentRequestService's APIs respondPayment,
25   *  changeShippingAddress, or changeShippingOtpion is possible to called in the
26   *  implementation.
27   *  @param requestId - the request identify of the payment request.
28   *                     Notice that this requestId is an internal request Id
29   *                     generated by Gecko
30   */
31  void showPayment(in AString requestId);
32
33  /**
34   *  Abort the payment.
35   *  The implementation must abort and close the showing payment UI then call
36   *  nsIPaymentRequestService respondPayment with nsIPaymentAbortActionResponse
37   *  to inform Gecko of the abort status.
38   *  @param requestId - the request identify of the payment request.
39   *                     Notice that this requestId is an internal request Id
40   *                     generated by Gecko
41   */
42  void abortPayment(in AString requestId);
43
44  /**
45   *  Complete the payment.
46   *  The implementation should close the showing payment UI, then call
47   *  nsIPaymentRequestService respondPayment with nsIPaymentCompleteActionResponse
48   *  to inform Gecko of the complete status.
49   *  @param requestId - the request identify of the payment request.
50   *                     Notice that this requestId is an internal request Id
51   *                     generated by Gecko
52   */
53  void completePayment(in AString requestId);
54
55  /**
56   *  Update the payment data in the payment UI.
57   *  The implementation should get the updated payment data through the
58   *  nsIPaymentRequestService again, and update the UI.
59   *  @param requestId - the request identify of the payment request.
60   *                     Notice that this requestId is an internal request Id
61   *                     generated by Gecko
62   */
63  void updatePayment(in AString requestId);
64
65  /**
66   *  Close the payment UI for the specified PaymentRequest.
67   *  The implementation should clean up the PaymentRequest data saved in the UI
68   *  component and close the UI if the specified PaymentRequest is showing to
69   *  the user.
70   *  Notice when the method is called, that means the PaymentRequest is invalid
71   *  in nsIPaymentRequestService.
72   *  @param requestId - the request identify of the payment request.
73   *                     Notice that this requestId is an internal request Id
74   *                     generated by Gecko
75   */
76  void closePayment(in AString requestId);
77
78};
79
80%{C++
81#define NS_PAYMENT_UI_SERVICE_CID \
82  { 0x01f8bd55, 0x9017, 0x438b, { 0x85, 0xec, 0x7c, 0x15, 0xd2, 0xb3, 0x5c, 0xdc } }
83#define NS_PAYMENT_UI_SERVICE_CONTRACT_ID \
84  "@mozilla.org/dom/payments/payment-ui-service;1"
85%}
86