octopi/library/cromp/cromp_transaction.h

   1 #ifndef CROMP_TRANSACTION_CLASS
   2 #define CROMP_TRANSACTION_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : cromp_transaction                                                 *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *  Purpose:                                                                   *
  10 *                                                                             *
  11 *    The basic structure passed around the network for CROMP requests and     *
  12 *  responses.                                                                 *
  13 *                                                                             *
  14 *******************************************************************************
  15 * Copyright (c) 2000-$now By Author.  This program is free software; you can  *
  16 * redistribute it and/or modify it under the terms of the GNU General Public  *
  17 * License as published by the Free Software Foundation; either version 2 of   *
  18 * the License or (at your option) any later version.  This is online at:      *
  19 *     http://www.fsf.org/copyleft/gpl.html                                    *
  20 * Please send any updates to: fred@gruntose.com                               *
  21 \*****************************************************************************/
  22
  23 #include <basis/contracts.h>
  24 #include <octopus/infoton.h>
  25 #include <octopus/entity_defs.h>
  26
  27 namespace cromp {
  28
  29 //////////////
  30
  31 class cromp_transaction
  32 {
  33 public:
  34   virtual ~cromp_transaction();
  35   DEFINE_CLASS_NAME("cromp_transaction");
  36
  37   enum outcomes {
  38     OKAY = basis::common::OKAY,
  39     GARBAGE = basis::common::GARBAGE,
  40     PARTIAL = basis::common::PARTIAL,  // header is good but not all data is there yet.
  41
  42     DEFINE_OUTCOME(WAY_TOO_SMALL, -41, "The package is too small for even "
  43         "a header"),
  44     DEFINE_OUTCOME(ILLEGAL_LENGTH, -42, "The package claims a length larger "
  45         "than we allow")
  46   };
  47   static const char *outcome_name(const basis::outcome &to_name);
  48
  49   static void flatten(basis::byte_array &packed_form, const octopi::infoton &request,
  50           const octopi::octopus_request_id &id);
  51     // encapsulate the "request" with the "id" in a wire-friendly format in the
  52     // "packed_form".  this makes the infoton a bit more seaworthy out on the
  53     // network using a recognizable header.
  54
  55   static bool unflatten(basis::byte_array &packed_form, basis::byte_array &still_flat,
  56           octopi::octopus_request_id &id);
  57     // re-inflates the infoton from the "packed_form" as far as retrieving
  58     // the original chunk of bytes in "still_flat".  the "id" is also unpacked.
  59
  60   static int minimum_flat_size(const octopi::octopus_request_id &id);
  61   static int minimum_flat_size(const structures::string_array &classifier,
  62           const octopi::octopus_request_id &id);
  63     // returns the amount of packing overhead added by this class given the
  64     // request "id" that will be used.  the second method can include the
  65     // "classifier" also, in order to add in overhead from infoton::fast_pack.
  66     // neither of these methods considers the flat size of the associated
  67     // infoton.
  68
  69   static bool resynchronize(basis::byte_array &packed_form);
  70     // chows down on the "packed_form" until we see a header or there's
  71     // nothing left in the array.  note that if there's a header already
  72     // present, this will stop immediately.  be sure to zap at least one
  73     // byte from the front if there was already a header present.
  74
  75   static basis::outcome peek_header(const basis::byte_array &packed_form, int &length);
  76     // examines the data in "packed_form" and judges whether we think it's
  77     // got a valid transaction there yet or not.  the outcome returned is one
  78     // of the peek_outcomes.  if the outcome is OKAY or PARTIAL, then
  79     // the operation can be considered successful and the "length" is set to
  80     // the expected size of the "packed_form".  however, OKAY is the only
  81     // outcome denoting that the whole package is present.
  82 };
  83
  84 } //namespace.
  85
  86 #endif
  87