start to build get-orders-ID

4 files changed, 133 insertions, 164 deletions

diff --git a/src/backend/Makefile.am b/src/backend/Makefile.am
index e70a1884..ffcb2c6c 100644
--- a/src/backend/Makefile.am
+++ b/src/backend/Makefile.am
@@ -45,6 +45,8 @@ taler_merchant_httpd_SOURCES = \
     taler-merchant-httpd_private-get-products-ID.h \
   taler-merchant-httpd_private-get-orders.c \
     taler-merchant-httpd_private-get-orders.h \
+  taler-merchant-httpd_private-get-orders-ID.c \
+    taler-merchant-httpd_private-get-orders-ID.h \
   taler-merchant-httpd_private-get-reserves.c \
     taler-merchant-httpd_private-get-reserves.h \
   taler-merchant-httpd_private-get-reserves-ID.c \
diff --git a/src/backend/taler-merchant-httpd_get-orders-ID.h b/src/backend/taler-merchant-httpd_get-orders-ID.h
index 3aa157da..1d2d61f2 100644
--- a/src/backend/taler-merchant-httpd_get-orders-ID.h
+++ b/src/backend/taler-merchant-httpd_get-orders-ID.h
@@ -25,6 +25,23 @@
 
 
 /**
+ * Create a taler://pay/ URI for the given @a con and @a order_id
+ * and @a session_id and @a instance_id.
+ *
+ * @param con HTTP connection
+ * @param order_id the order id
+ * @param session_id session, may be NULL
+ * @param instance_id instance, may be "default"
+ * @return corresponding taler://pay/ URI, or NULL on missing "host"
+ */
+char *
+TMH_make_taler_pay_uri (struct MHD_Connection *con,
+                        const char *order_id,
+                        const char *session_id,
+                        const char *instance_id);
+
+
+/**
  * Handle a GET "/orders/$ID" request.
  *
  * @param rh context of the handler
diff --git a/src/backend/taler-merchant-httpd_private-get-orders-ID.c b/src/backend/taler-merchant-httpd_private-get-orders-ID.c
index 78fe4e19..d43c6500 100644
--- a/src/backend/taler-merchant-httpd_private-get-orders-ID.c
+++ b/src/backend/taler-merchant-httpd_private-get-orders-ID.c
@@ -21,8 +21,10 @@
  */
 #include "platform.h"
 #include "taler-merchant-httpd_private-get-orders-ID.h"
+#include "taler-merchant-httpd_get-orders-ID.h"
 #include <taler/taler_json_lib.h>
 #include "taler-merchant-httpd_mhd.h"
+#include "taler-merchant-httpd_exchanges.h"
 
 /**
  * How long do we wait on the exchange?
@@ -270,20 +272,16 @@ gorc_resume (struct GetOrderRequestContext *gorc,
       tq->dgh = NULL;
     }
   }
-  GNUNET_CONTAINER_DLL_remove (gorc_head,
-                               gorc_tail,
-                               gorc);
-  MHD_resume_connection (gorc->sc.connection);
-  GNUNET_CONTAINER_DLL_remove (gorc_head,
-                               gorc_tail,
-                               gorc);
   gorc->wire_ec = ec;
   if (NULL != exchange_hr)
   {
     gorc->exchange_hc = exchange_hr->http_status;
-    gorc->exchange_ec = exchange_hr->error_code;
+    gorc->exchange_ec = exchange_hr->ec;
   }
-  MHD_resume_connection (gorc->sc.connection);
+  GNUNET_CONTAINER_DLL_remove (gorc_head,
+                               gorc_tail,
+                               gorc);
+  MHD_resume_connection (gorc->sc.con);
 }
 
 
@@ -300,7 +298,7 @@ exchange_timeout_cb (void *cls)
 
   gorc->tt = NULL;
   gorc_resume (gorc,
-               42, // FIXME: EC
+               TALER_EC_GET_ORDERS_EXCHANGE_TIMEOUT,
                NULL);
 }
 
@@ -326,7 +324,7 @@ deposit_get_cb (void *cls,
   if (NULL == dd)
   {
     gorc_resume (gorc,
-                 42, // FIXME: EC
+                 TALER_EC_GET_ORDERS_EXCHANGE_TRACKING_FAILURE,
                  hr);
     GNUNET_free (tq);
     return;
@@ -341,7 +339,7 @@ deposit_get_cb (void *cls,
     if (qs < 0)
     {
       gorc_resume (gorc,
-                   42, // FIXME: EC
+                   TALER_EC_GET_ORDERS_DB_STORE_TRACKING_FAILURE,
                    NULL);
       GNUNET_free (tq);
       return;
@@ -353,20 +351,7 @@ deposit_get_cb (void *cls,
                           &dd->coin_contribution))
     {
       gorc_resume (gorc,
-                   42, // FIXME: EC
-                   NULL);
-      GNUNET_free (tq);
-      return;
-    }
-    /* Compute total amount including deposit fees (so how much
-       of the total deposit was properly paid by the exchange) */
-    if (0 >
-        TALER_amount_add (&gorc->value_total,
-                          &gorc->value_total,
-                          &tq->coin_value))
-    {
-      gorc_resume (gorc,
-                   42, // FIXME: EC
+                   TALER_EC_GET_ORDERS_AMOUNT_ARITHMETIC_FAILURE,
                    NULL);
       GNUNET_free (tq);
       return;
@@ -417,16 +402,16 @@ exchange_found_cb (void *cls,
                                  tq);
     GNUNET_free (tq);
     gorc_resume (gorc,
-                 42, // FIXME: EC!
+                 TALER_EC_GET_ORDERS_EXCHANGE_LOOKUP_FAILURE,
                  hr);
     return;
   }
   tq->dgh = TALER_EXCHANGE_deposits_get (eh,
-                                         &gorc->hc->instance.merchant_priv,
+                                         &gorc->hc->instance->merchant_priv,
                                          &tq->h_wire,
                                          &gorc->h_contract_terms,
                                          &tq->coin_pub,
-                                         &deposit_get_callback,
+                                         &deposit_get_cb,
                                          tq);
   if (NULL == tq->dgh)
   {
@@ -435,7 +420,7 @@ exchange_found_cb (void *cls,
                                  tq);
     GNUNET_free (tq);
     gorc_resume (gorc,
-                 42,
+                 TALER_EC_GET_ORDERS_EXCHANGE_REQUEST_FAILURE,
                  NULL);
   }
 }
@@ -452,6 +437,8 @@ exchange_found_cb (void *cls,
  * @param cls a `struct GetOrderRequestContext`
  * @param deposit_serial identifies the deposit operation
  * @param exchange_url URL of the exchange that issued @a coin_pub
+ * @param amount_with_fee amount the exchange will deposit for this coin
+ * @param deposit_fee fee the exchange will charge for this coin
  * @param h_wire hash of the merchant's wire account into which the deposit was made
  * @param coin_pub public key of the deposited coin
  */
@@ -460,6 +447,8 @@ deposit_cb (void *cls,
             uint64_t deposit_serial,
             const char *exchange_url,
             const struct GNUNET_HashCode *h_wire,
+            const struct TALER_Amount *amount_with_fee,
+            const struct TALER_Amount *deposit_fee,
             const struct TALER_CoinSpendPublicKeyP *coin_pub)
 {
   struct GetOrderRequestContext *gorc = cls;
@@ -473,15 +462,16 @@ deposit_cb (void *cls,
                                tq);
   tq->coin_pub = *coin_pub;
   tq->h_wire = *h_wire;
+  // FIXME: keep at least deposit_fee in 'tq'! needed later!
   tq->fo = TMH_EXCHANGES_find_exchange (exchange_url,
                                         NULL,
                                         GNUNET_NO,
                                         &exchange_found_cb,
                                         tq);
-  if (NULL = tq->fo)
+  if (NULL == tq->fo)
   {
     gorc_resume (gorc,
-                 42, // FIXME: EC
+                 TALER_EC_GET_ORDERS_EXCHANGE_LOOKUP_FAILURE,
                  NULL);
   }
 }
@@ -504,7 +494,6 @@ gorc_cleanup (void *cls)
   if (NULL != gorc->refund_details)
     json_decref (gorc->refund_details);
   GNUNET_assert (NULL == gorc->tt);
-  GNUNET_assert (NULL == gorc->fo);
   GNUNET_free (gorc);
 }
 
@@ -537,19 +526,19 @@ process_refunds_cb (void *cls,
 
   if (NULL == gorc->refund_details)
   {
-    gorc->refund_details = json_array_new ();
+    gorc->refund_details = json_array ();
     GNUNET_assert (NULL != gorc->refund_details);
   }
   GNUNET_assert (0 ==
-                 json_array_append_new (json_pack ("{s:o, s:o, s:s}",
-                                                   "amount",
-                                                   TALER_JSON_from_amount (
-                                                     refund_amount),
-                                                   "timestamp",
-                                                   GNUNET_JSON_from_time_absolute (
-                                                     timestamp),
-                                                   "reason",
-                                                   reason)));
+                 json_array_append_new (
+                   gorc->refund_details,
+                   json_pack ("{s:o, s:o, s:s}",
+                              "amount",
+                              TALER_JSON_from_amount (refund_amount),
+                              "timestamp",
+                              GNUNET_JSON_from_time_abs (timestamp),
+                              "reason",
+                              reason)));
   if (gorc->refunded)
   {
     GNUNET_assert (0 <=
@@ -608,7 +597,7 @@ process_transfer_details (void *cls,
                               "amount",
                               TALER_JSON_from_amount (&wired),
                               "execution_time",
-                              GNUNET_JSON_from_time_absolute (execution_time),
+                              GNUNET_JSON_from_time_abs (execution_time),
                               "confirmed",
                               transfer_confirmed)));
 }
@@ -695,7 +684,7 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
 
     TMH_db->preflight (TMH_db->cls);
     qs = TMH_db->lookup_contract_terms (TMH_db->cls,
-                                        hc->instance.settings->id,
+                                        hc->instance->settings.id,
                                         hc->infix,
                                         &gorc->contract_terms,
                                         &gorc->order_serial);
@@ -708,7 +697,7 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
       GNUNET_break (GNUNET_DB_STATUS_HARD_ERROR == qs);
       return TALER_MHD_reply_with_error (connection,
                                          MHD_HTTP_INTERNAL_SERVER_ERROR,
-                                         TALER_EC_CHECK_PAYMENT_DB_FETCH_CONTRACT_TERMS_ERROR,
+                                         TALER_EC_GET_ORDERS_DB_FETCH_CONTRACT_TERMS_ERROR,
                                          "db error fetching contract terms");
     }
     if (GNUNET_DB_STATUS_SUCCESS_NO_RESULTS == qs)
@@ -716,7 +705,7 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
       GNUNET_break_op (0);
       return TALER_MHD_reply_with_error (connection,
                                          MHD_HTTP_NOT_FOUND,
-                                         TALER_EC_ORDERS_GET_ORDER_NOT_FOUND,
+                                         TALER_EC_GET_ORDERS_ORDER_NOT_FOUND,
                                          "Did not find order in DB");
     }
 
@@ -739,7 +728,7 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
         return TALER_MHD_reply_with_error (
           connection,
           MHD_HTTP_INTERNAL_SERVER_ERROR,
-          TALER_EC_CHECK_PAYMENT_DB_FETCH_CONTRACT_TERMS_ERROR,
+          TALER_EC_GET_ORDERS_DB_FETCH_CONTRACT_TERMS_ERROR,
           "Merchant database error (contract terms corrupted)");
       }
       // FIXME: sanity check on gorc->contract_amount.currency!
@@ -752,7 +741,7 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
       return (MHD_YES ==
               TALER_MHD_reply_with_error (connection,
                                           MHD_HTTP_INTERNAL_SERVER_ERROR,
-                                          TALER_EC_ORDERS_GET_FAILED_COMPUTE_PROPOSAL_HASH,
+                                          TALER_EC_GET_ORDERS_FAILED_COMPUTE_PROPOSAL_HASH,
                                           "Failed to hash contract terms"))
              ? GNUNET_NO
              : GNUNET_SYSERR;
@@ -774,7 +763,7 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
     GNUNET_break (GNUNET_DB_STATUS_HARD_ERROR == qs);
     return TALER_MHD_reply_with_error (connection,
                                        MHD_HTTP_INTERNAL_SERVER_ERROR,
-                                       TALER_EC_CHECK_PAYMENT_DB_FETCH_PAYMENT_STATUS,
+                                       TALER_EC_GET_ORDERS_DB_FETCH_PAYMENT_STATUS,
                                        "DB error fetching payment status");
   }
   if (! paid)
@@ -793,7 +782,7 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
       GNUNET_break (GNUNET_DB_STATUS_HARD_ERROR == qs);
       return TALER_MHD_reply_with_error (connection,
                                          MHD_HTTP_INTERNAL_SERVER_ERROR,
-                                         TALER_EC_CHECK_PAYMENT_DB_FETCH_PAYMENT_STATUS,
+                                         TALER_EC_GET_ORDERS_DB_FETCH_PAYMENT_STATUS,
                                          "DB error fetching payment status");
     }
     if (GNUNET_DB_STATUS_SUCCESS_ONE_RESULT == qs)
@@ -806,7 +795,7 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
       taler_pay_uri = TMH_make_taler_pay_uri (connection,
                                               hc->infix,
                                               gorc->session_id,
-                                              hc->instance.settings->id);
+                                              hc->instance->settings.id);
       ret = TALER_MHD_reply_json_pack (connection,
                                        MHD_HTTP_OK,
                                        "{s:s, s:b, s:s}",
@@ -828,11 +817,11 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
   {
     /* suspend connection, wait for exchange to check wire transfer status there */
     gorc->transfer_status_requested = false;   /* only try ONCE */
-    TMH_db->lookup_deposits (TMH_db->cls,
-                             gorc->order_serial,
-                             &deposit_cb,
-                             gorc);
-    if (NULL != gorc->tq)
+    TMH_db->lookup_deposits_by_order (TMH_db->cls,
+                                      gorc->order_serial,
+                                      &deposit_cb,
+                                      gorc);
+    if (NULL != gorc->tq_head)
     {
       GNUNET_CONTAINER_DLL_insert (gorc_head,
                                    gorc_tail,
@@ -846,7 +835,7 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
   }
 
   if ( (! paid) &&
-       (0 != gorc.sc.long_poll_timeout.abs_value_us) )
+       (0 != gorc->sc.long_poll_timeout.abs_value_us) )
   {
     GNUNET_log (GNUNET_ERROR_TYPE_INFO,
                 "Suspending GET /private/orders/%s\n",
@@ -867,7 +856,7 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
     taler_pay_uri = TMH_make_taler_pay_uri (connection,
                                             hc->infix,
                                             gorc->session_id,
-                                            hc->instance.settings->id);
+                                            hc->instance->settings.id);
     ret = TALER_MHD_reply_json_pack (connection,
                                      MHD_HTTP_OK,
                                      "{s:s, s:b}",
@@ -884,8 +873,8 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
   /* Accumulate refunds, if any. */
   {
     qs = TMH_db->lookup_refunds_detailed (TMH_db->cls,
-                                          hc->instance.settings->id,
-                                          &h_contract_terms,
+                                          hc->instance->settings.id,
+                                          &gorc->h_contract_terms,
                                           &process_refunds_cb,
                                           gorc);
   }
@@ -894,7 +883,7 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
     GNUNET_break (0);
     return TALER_MHD_reply_with_error (connection,
                                        MHD_HTTP_INTERNAL_SERVER_ERROR,
-                                       TALER_EC_ORDERS_GET_DB_FETCH_TRANSACTION_ERROR,
+                                       TALER_EC_GET_ORDERS_DB_FETCH_TRANSACTION_ERROR,
                                        "Merchant database error");
   }
 
@@ -902,13 +891,11 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
   {
     MHD_RESULT ret;
 
-    gorc->wire_details = json_array_new ();
+    gorc->wire_details = json_array ();
     GNUNET_assert (NULL != gorc->wire_details);
-    // FIXME: assert on return codes:
-    TALER_amount_get_zero (&gorc->value_total,
-                           TMH_currency);
-    TALER_amount_get_zero (&gorc->deposits_total,
-                           TMH_currency);
+    GNUNET_assert (GNUNET_OK ==
+                   TALER_amount_get_zero (TMH_currency,
+                                          &gorc->deposits_total));
     qs = TMH_db->lookup_transfer_details_by_order (TMH_db->cls,
                                                    gorc->order_serial,
                                                    &process_transfer_details,
@@ -936,12 +923,13 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
         GNUNET_break (0);
         return TALER_MHD_reply_with_error (connection,
                                            MHD_HTTP_INTERNAL_SERVER_ERROR,
-                                           42, // FIXME: EC
+                                           TALER_EC_GET_ORDERS_CONTRACT_CONTENT_INVALID,
                                            "Inconsistent contract terms in DB");
       }
+      // FIXME: what about fees?
       if (0 >= // FIXME: right cmp?
           TALER_amount_cmp (&expect_total,
-                            &gorc->value_total))
+                            &gorc->deposits_total))
       {
         wired = true;
         qs = TMH_db->mark_order_wired (TMH_db->cls,
@@ -952,36 +940,32 @@ TMH_private_get_orders_ID (const struct TMH_RequestHandler *rh,
 
     ret = TALER_MHD_reply_json_pack (connection,
                                      MHD_HTTP_OK,
-                                     "{s:I, s:I, s:I, s:o, s:o,"
-                                     " s:O, s:b, s:b, s:o?, s:o?, s:o?}",
+                                     "{s:I, s:I, s:I, s:o, s:O,"
+                                     " s:b, s:b, s:o?, s:o?, s:o?}",
                                      "wire_ec",
                                      (json_int_t) gorc->wire_ec,
                                      "exchange_ec",
                                      (json_int_t) gorc->exchange_ec,
                                      "exchange_hc",
                                      (json_int_t) gorc->exchange_hc,
-                                     "transfer_value_total",
-                                     TALER_JSON_from_amount (
-                                       &gorc->value_total)
                                      "deposit_total",
                                      TALER_JSON_from_amount (
-                                       &gorc->deposits_total)
-                                       : NULL,
-                                       "contract_terms",
-                                       gorc->contract_terms,
-                                       "paid",
-                                       true,
-                                       "refunded",
-                                       gorc->refunded,
-                                       "refund_amount",
-                                       (gorc->refunded)
-                                       ? TALER_JSON_from_amount (
-                                         &gorc->refund_amount)
-                                       : NULL,
-                                       "wire_details",
-                                       gorc->wire_details,
-                                       "refund_details",
-                                       gorc->refund_details);
+                                       &gorc->deposits_total),
+                                     "contract_terms",
+                                     gorc->contract_terms,
+                                     "paid",
+                                     true,
+                                     "refunded",
+                                     gorc->refunded,
+                                     "refund_amount",
+                                     (gorc->refunded)
+                                     ? TALER_JSON_from_amount (
+                                       &gorc->refund_amount)
+                                     : NULL,
+                                     "wire_details",
+                                     gorc->wire_details,
+                                     "refund_details",
+                                     gorc->refund_details);
     gorc->wire_details = NULL;
     gorc->refund_details = NULL;
     return ret;
diff --git a/src/include/taler_merchantdb_plugin.h b/src/include/taler_merchantdb_plugin.h
index 44a316ad..6f3db87c 100644
--- a/src/include/taler_merchantdb_plugin.h
+++ b/src/include/taler_merchantdb_plugin.h
@@ -531,6 +531,28 @@ struct TALER_MERCHANTDB_TipDetails
 
 
 /**
+ * Function called with information about a coin that was deposited.
+ *
+ * @param cls closure
+ * @param deposit_serial which deposit operation is this about
+ * @param exchange_url URL of the exchange that issued the coin
+ * @param amount_with_fee amount the exchange will deposit for this coin
+ * @param deposit_fee fee the exchange will charge for this coin
+ * @param h_wire hash of merchant's wire details
+ * @param coin_pub public key of the coin
+ */
+typedef void
+(*TALER_MERCHANTDB_DepositedCoinsCallback)(
+  void *cls,
+  uint64_t deposit_serial,
+  const char *exchange_url,
+  const struct GNUNET_HashCode *h_wire,
+  const struct TALER_Amount *amount_with_fee,
+  const struct TALER_Amount *deposit_fee,
+  const struct TALER_CoinSpendPublicKeyP *coin_pub);
+
+
+/**
  * Callback with reserve details.
  *
  * @param cls closure
@@ -558,45 +580,6 @@ typedef void
   const struct TALER_MERCHANTDB_TipDetails *tips);
 
 
-/* **************** OLD: ******************** */
-
-/**
- * Typically called by `find_contract_terms_by_date`.
- *
- * @param cls closure
- * @param order_id order id
- * @param row_id serial numer of the transaction in the table,
- * @param contract_terms proposal data related to order id
- */
-typedef void
-(*TALER_MERCHANTDB_ProposalDataCallback)(void *cls,
-                                         const char *order_id,
-                                         uint64_t row_id,
-                                         const json_t *contract_terms);
-
-
-/**
- * Function called with information about a transaction.
- *
- * @param cls closure
- * @param merchant_pub merchant's public key
- * @param h_contract_terms proposal data's hashcode
- * @param h_wire hash of our wire details
- * @param timestamp time of the confirmation
- * @param refund refund deadline
- * @param total_amount total amount we receive for the contract after fees
- */
-typedef void
-(*TALER_MERCHANTDB_TransactionCallback)(
-  void *cls,
-  const struct TALER_MerchantPublicKeyP *merchant_pub,
-  const struct GNUNET_HashCode *h_contract_terms,
-  const struct GNUNET_HashCode *h_wire,
-  struct GNUNET_TIME_Absolute timestamp,
-  struct GNUNET_TIME_Absolute refund,
-  const struct TALER_Amount *total_amount);
-
-
 /**
  * Function called with information about a coin that was deposited.
  *
@@ -628,39 +611,6 @@ typedef void
 
 
 /**
- * Function called with information about a wire transfer identifier.
- *
- * @param cls closure
- * @param proof proof from exchange about what the wire transfer was for
- */
-typedef void
-(*TALER_MERCHANTDB_ProofCallback)(void *cls,
-                                  const json_t *proof);
-
-
-/**
- * Function called with information about a refund.
- *
- * @param cls closure
- * @param coin_pub public coin from which the refund comes from
- * @param exchange_url URL of the exchange that issued @a coin_pub
- * @param rtransaction_id identificator of the refund
- * @param reason human-readable explanation of the refund
- * @param refund_amount refund amount which is being taken from @a coin_pub
- * @param refund_fee cost of this refund operation
- */
-typedef void
-(*TALER_MERCHANTDB_CoinRefundCallback)(
-  void *cls,
-  const struct TALER_CoinSpendPublicKeyP *coin_pub,
-  const char *exchange_url,
-  uint64_t rtransaction_id,
-  const char *reason,
-  const struct TALER_Amount *refund_amount,
-  const struct TALER_Amount *refund_fee);
-
-
-/**
  * Details about a pickup operation executed by the merchant.
  */
 struct TALER_MERCHANTDB_PickupDetails
@@ -1287,6 +1237,22 @@ struct TALER_MERCHANTDB_Plugin
 
 
   /**
+   * Retrieve details about coins that were deposited for an order.
+   *
+   * @param cls closure
+   * @param order_serial identifies the order
+   * @param cb function to call for each deposited coin
+   * @param cb_cls closure for @a cb
+   * @return transaction status
+   */
+  enum GNUNET_DB_QueryStatus
+  (*lookup_deposits_by_order)(void *cls,
+                              uint64_t order_serial,
+                              TALER_MERCHANTDB_DepositedCoinsCallback cb,
+                              void *cb_cls);
+
+
+  /**
    * Retrieve wire transfer details for all deposits associated with
    * a given @a order_serial.
    * FIXME: not implemented yet!