swap mount additions in revamp
[feisty_meow.git] / 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