taler-docs

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

refresh-mailbox.rst (1556B)


      1 .. ts:op:: refreshMailbox
      2 
      3   Download new messages from a mailbox service: messages are fetched
      4   in batches, decrypted with the mailbox's private encryption key,
      5   stored in the wallet's local database and deleted on the mailbox
      6   service.
      7 
      8   **Request:**
      9 
     10   The request arguments are a `MailboxConfiguration` object for the
     11   mailbox to refresh.
     12 
     13   **Response:**
     14 
     15   On success, the result is a `MailboxMessageRecordsResponse` object
     16   with the newly downloaded messages.
     17 
     18   **Side effects:**
     19 
     20   Downloads new messages from the mailbox service over the network,
     21   stores them in the wallet's local database and deletes them on the
     22   service.  A ``mailbox-message-added`` notification is emitted for
     23   each stored message.
     24 
     25   **Expected errors:**
     26 
     27   The caller can handle the following errors inline:
     28   ``WALLET_MAILBOX_UNAVAILABLE``, ``WALLET_RECEIVED_MALFORMED_RESPONSE``.
     29 
     30   **Details:**
     31 
     32   The configuration of the mailbox service (message size and response
     33   limit) is fetched before the first batch.  Each downloaded message
     34   is stored like in :ts:op:`addMailboxMessage`.  Messages that cannot
     35   be decrypted are skipped.  At most 100 batches are fetched in one
     36   call.  ``WALLET_RECEIVED_MALFORMED_RESPONSE`` indicates that the
     37   mailbox service returned an invalid response (invalid response
     38   limit, or a message list whose size is not a multiple of the
     39   advertised message size).
     40 
     41 .. ts:def:: MailboxMessageRecordsResponse
     42 
     43   interface MailboxMessageRecordsResponse {
     44     // Newly downloaded messages.
     45     messages: MailboxMessageRecord[];
     46   }