taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

add-exchange.rst (2018B)

      1 .. ts:op:: addExchange
      2 
      3   Add an exchange to the wallet, or force an update of the exchange
      4   entry.
      5 
      6   **Request:**
      7 
      8   The request arguments must be an `AddExchangeRequest` object.
      9 
     10   **Response:**
     11 
     12   On success, the result is an `AddExchangeResponse` object.
     13 
     14   **Side effects:**
     15 
     16   Adds or force-updates the exchange entry.  The exchange's keys and
     17   wire information are fetched over the network, and notifications
     18   are emitted.
     19 
     20   **Expected errors:**
     21 
     22   The caller can handle the following errors inline:
     23   ``WALLET_TALER_URI_MALFORMED``, ``WALLET_EXCHANGE_UNAVAILABLE``,
     24   ``WALLET_EXCHANGE_SIGNATURE_INVALID``, ``WALLET_CORE_API_BAD_REQUEST``.
     25 
     26   **Details:**
     27 
     28   The ``uri`` is either an http(s) exchange base URL or a
     29   ``taler://add-exchange/`` URI.  An http(s) URL must already be
     30   canonical, unless ``allowCompletion`` is set; in that case the
     31   wallet tries to complete the URL as with
     32   :ts:op:`completeExchangeBaseUrl` and fails if completion is not
     33   possible.  The wallet fetches the exchange's key data before the
     34   request succeeds.  Unless ``ephemeral`` is set, the exchange is
     35   marked as explicitly added by the user.
     36 
     37 .. ts:def:: AddExchangeRequest
     38 
     39   interface AddExchangeRequest {
     40     // Either an http(s) exchange base URL or
     41     // a taler://add-exchange/ URI.
     42     uri?: string;
     43 
     44     // Only ephemerally add the exchange.
     45     ephemeral?: boolean;
     46 
     47     // Allow passing incomplete URLs.  The wallet will try to complete
     48     // the URL and throw an error if completion is not possible.
     49     allowCompletion?: boolean;
     50 
     51     // Deprecated: start a forced exchange update with a separate
     52     // updateExchangeEntry call instead.
     53     forceUpdate?: boolean;
     54 
     55     // Deprecated: use the uri field instead.
     56     exchangeBaseUrl?: string;
     57 
     58     // Correlates progress notifications and allows cancellation.
     59     progressToken?: string;
     60   }
     61 
     62 .. ts:def:: AddExchangeResponse
     63 
     64   interface AddExchangeResponse {
     65     // Base URL of the exchange that was added to the wallet.
     66     exchangeBaseUrl: string;
     67   }