Main Page Class Hierarchy Compound List File List Compound Members File Members

# request_template.h

Go to the documentation of this file.

    00001 /*
    00002  * request_template.h -- Template and example of a request message class
    00003  *                       for use in the mutable server model.
    00004  *
    00005  *                       In addition to passport handling (which is provided
    00006  *                       as a result of deriving from the MutableServerRequest
    00007  *                       class,
    00008  *                       this example class is expected to also handle
    00009  *                       an integer and a char string of undetermined length
    00010  *                       (to demonstrate memory allocation and cleanup).
    00011  */
    00012
    00013 // STEP 1: Do a global replacement of the string "RequestTemplate"
    00014 //         with the name of your new class
    00015 //
    00016 #if ! defined(_MSM_RequestTemplate_H)
    00017 #define _MSM_RequestTemplate_H
    00018
    00019
    00020 // STEP 2: If the new class should be derived from a class other than
    00021 //         MutableServerRequest, replace this with the appropriate
    00022 //         include.
    00023 //         This specific include requires the project make file to have
    00024 //         /earthworm/..../src/libsrc_cpp/servers/messaging
    00025 //         in the include path.
    00026 #include <mutableserverrequest.h>
    00027
    00028
    00029
    00030 // STEP 3: If the new class should be derived from a class other than
    00031 //         MutableServerRequest, replace it with the appropriate
    00032 //         base class name.
    00033 class RequestTemplate : public MutableServerRequest
    00034 {
    00035 protected:
    00036
    00037
    00038    // ----------------------------------------------------------
    00039    //     virtual methods from MutableServerMessage
    00040    //     to be implemented for a complete derivative class.
    00041    //
    00042    // THAT IS: These methods were declared in a base class (as
    00043    //          an interface), but they must be redeclared here
    00044    //          and implemented in request_template.cpp
    00045    //          to be able to use the final class.
    00046    //
    00047    // NONE OF THIS NEEDS TO BE CHANGED, SEARCH FOR THE STRING
    00048    // RequestTemplate TO LOCATE THE FIRST ITEMS TO CHANGE.
    00049    // ----------------------------------------------------------
    00050
    00051    // BufferInitAlloc -- when preparing to format a message
    00052    //                    using FormatBuffer()], this is
    00053    //                    first called.  The result is,
    00054    //                    for the first call, MessageBuffer
    00055    //                    will be assured to be at least this
    00056    //                    long.
    00057    //                    Overriding this method allows
    00058    //                    derivative classes to minimize
    00059    //                    reallocations as bits are appended
    00060    //                    to the message buffer;
    00061    //
    00062    // NOTE: In each derivative implementation,
    00063    //       call <super_class>::BufferInitAlloc() to get the
    00064    //       space needed by that super class (and all baser
    00065    //       classes), then add the size needed by the
    00066    //       derivative to arrive at the total size needed.
    00067    //       The 10 specified here is for the message-
    00068    //       terminating '\n' and a slight overrun space.
    00069    //
    00070    long BufferInitAlloc();
    00071
    00072
    00073    // FormatDerivativeData
    00074    //
    00075    //     Method by which derivative classes append
    00076    //     their content to MessageBuffer.
    00077    //
    00078    //  NOTE: ALWAYS CALL <super_class>::FormatDerivativeData()
    00079    //        at the start of each implementation to allow
    00080    //        base classes to append their stuff (if any)
    00081    //        to the buffer.
    00082    //        Thus the buffer is built upwards from the base-most
    00083    //        class to the most-derived class.
    00084    //        Generally, a newline is used to separate lines.
    00085    //
    00086    // THROW worm_exception for errors
    00087    //
    00088    //       (The worm_exception class is included through
    00089    //        some base class.  Example of use is in the cpp file)
    00090    //
    00091    void FormatDerivativeData();
    00092
    00093
    00094    // ParseDerivativeData
    00095    //
    00096    //     Method by which derivative classes extract
    00097    //     their content to MessageBuffer.
    00098    //
    00099    //  NOTE: Always call <super_class>::ParseDerivativeData()
    00100    //        at the top of each implementation to allow
    00101    //        base classes to get their data out of the
    00102    //        buffer first.
    00103    //
    00104    //  USAGE:
    00105    //
    00106    //     If parsing a multi-line message ('\n'-terminated lines),
    00107    //     use a loop consisting of:
    00108    //
    00109    //       i = MessageBuffer.find("\n")  to find the first line end,
    00110    //       MessageBuffer.substr(0, i)    to extract the string
    00111    //                                        (excluding the '\n')
    00112    //       MessageBuffer.erase(0, i+1)     to remove that portion
    00113    //
    00114    //     Since the message should be terminated by an additional
    00115    //     '\n', when the string returned in the second step
    00116    //     is of zero length, that is the end of the message.
    00117    //
    00118    //     (If find() does not, it returns MessageBuffer.npos)
    00119    //
    00120    // THROW worm_exception for errors
    00121    //
    00122    void ParseDerivativeData();
    00123
    00124    // ----------------------------------------------------------
    00125    //             for MutableServerRequest class
    00126    // ----------------------------------------------------------
    00127
    00128    // Only Passport-related items were implemented in the
    00129    // MutableServerRequest class, so they may be ignored here.
    00130
    00131    // IF THE NEW CLASS IS NOT DERIVED FROM MutableServerRequest
    00132    // REMOVE THESE COMMENT LINES.
    00133
    00134
    00135    // ----------------------------------------------------------
    00136    //             for RequestTemplate class
    00137    // ----------------------------------------------------------
    00138
    00139 // STEP 4: ADD CLASS-SPECIFIC VARIABLES AND FUNCTIONS/METHODS
    00140
    00141    // THIS IS THE FIRST LOCATION WHERE ITEMS FOR THE
    00142    // RequestTemplate CLASS ARE TO BE ENTERED.
    00143
    00144    // THIS IS THE APPROPRIATE LOCATIONS TO DECLARE CONTAINER
    00145    // VARIABLES.
    00146    //
    00147    // SINCE THIS REQUEST EXAMPLE IS TO SHOW AN int AND A char pointer,
    00148    // DECLARE RELEVANT VARIABLES HERE:
    00149
    00150    int  MyInt;
    00151
    00152    char MyCharPointer;
    00153
    00154    int  MyStringLength; // used to avoid unneeded reallocations.
    00155
    00156    /*
    00157    void MyExampleMethod( int some_parameter );
    00158    */
    00159
    00160 public:  // How others use this class
    00161
    00162    // ----------------------------------------------------------
    00163    //             for RequestTemplate class
    00164    // ----------------------------------------------------------
    00165
    00166 // STEP 5: ADD CLASS-SPECIFIC METHOD DECLARATIONS.
    00167
    00168    // TO PERFORM INITIALIZATION, DECLARE A CONSTRUCTOR
    00169    RequestTemplate();
    00170
    00171    // IF YOU NEED TO PERFORM [MEMORY] CLEANUP AFTER FINISHED WITH THE
    00172    // CLASS, DO SO IN THE DESTRUCTOR.
    00173    // IF NO CLEANUP IS NEEDED, THIS DECLARATION MAY BE
    00174    // REMOVED (ALONG WITH THE DEFINITION IN THE cpp FILE).
    00175    ~RequestTemplate();
    00176
    00177
    00178    // ADD DECLARATIONS FOR ACCESSOR METHODS (FUNCTIONS) TO
    00179    // GET TO THE VARIABLES SPECIFIC TO THIS CLASS:
    00180
    00181    void SetMyInteger( int p_int );
    00182
    00183    // SetMyString()
    00184    //
    00185    // PARAMETERS:
    00186    //       p_str may be NULL
    00187    //
    00188    // RETURNS:
    00189    //      true = set okay
    00190    //     false = failed to allocate memory for the buffer
    00191    bool SetMyString( const char * p_str );
    00192
    00193
    00194    // Adding 'const' at the end prevents the caller from
    00195    // changing the value in a way that would alter the contents
    00196    // of the class instance.
    00197
    00198    int GetMyInteger() const;
    00199
    00200    // GetMyString() may return NULL
    00201    char * GetMyString() const;
    00202
    00203
    00204
    00205    // ===========================================================
    00206    // EVERYTHING FOLLOWING (BETWEEN THE DOUBLE-DASHED LINES)
    00207    // MAY BE DELETED IN ACTUAL IMPLEMENTATIONS.
    00208
    00209
    00210    // THE FOLLOWING METHODS ARE ALSO AVAILABLE BY USERS OF
    00211    // THIS CLASS AS A RESULT OF ITS DERIVING FROM THESE OTHER
    00212    // BASE CLASSES.
    00213
    00214
    00215    // ----------------------------------------------------------
    00216    //     Methods from MutableServerMessage class
    00217    // ----------------------------------------------------------
    00218
    00219    // FormatBuffer()
    00220    //
    00221    //   MUST CALL THIS BEFORE CALLING
    00222    //      GetBufferLength() and GetBuffer()
    00223    //
    00224    //   -- calls BufferInitAlloc()
    00225    //   -- calls FormatDerivativeData()
    00226    //   -- terminates the buffer with an additional '\n'
    00227    //      (that is, a line of zero length)
    00228    //
    00229    // THROWs worm_exception for errors
    00230    //
    00231    //void FormatBuffer();
    00232
    00233    // GetBufferLength()
    00234    // GetBuffer()
    00235    //
    00236    //       Used to obtain an ascii buffer suitable for
    00237    //       transmission across a socket or ring.
    00238    //
    00239    //long GetBufferLength() const;
    00240    //const char * GetBuffer() const;
    00241
    00242    // ParseMessageLine -- used to handle a buffer which contains
    00243    //                     only one '\n' terminated line, and which,
    00244    //                     therefore may or may not be a complete
    00245    //                     message.
    00246    //
    00247    //   This method:
    00248    //   -- calls BufferInitAlloc()
    00249    //   -- if strlen(p_buffer) > 0:
    00250    //      -- appends buffer to MessageBuffer
    00251    //      -- if p_append_nl == true
    00252    //         -- appends '\n' to MessageBuffer
    00253    //   -- else  [[ strlen(p_buffer) == 0 ]]
    00254    //      -- if p_append_nl == true
    00255    //         -- appends '\n' to MessageBuffer
    00256    //      -- calls ParseDerivativeData()
    00257    //
    00258    // p_buffer: single line of a message
    00259    //           (terminating '\n' stripped off)
    00260    //
    00261    // p_append_nl: should '\n' be appended to p_buffer
    00262    //
    00263    // p_clearbuffer: used to clear MessageBuffer for first
    00264    //                line of message.
    00265    //
    00266    // RETURNS:
    00267    //      true  = this line completed the message and parsing completed
    00268    //      false = this line did not finish the message
    00269    //
    00270    // THROWs worm_exception for errors
    00271    //
    00272    //bool ParseMessageLine( const char * p_buffer
    00273    //                     ,       bool   p_append_nl   = true
    00274    //                     ,       bool   p_clearbuffer = false
    00275    //                     );
    00276
    00277    // ParseFromBuffer -- used to parse a buffer which is known to
    00278    //                    be complete.  Specifically, messages
    00279    //                    which arrive from a ring.
    00280    //
    00281    // THROWs worm_exception for errors
    00282    //
    00283    //void ParseFromBuffer( const char * p_buffer );
    00284
    00285
    00286    // ----------------------------------------------------------
    00287    //       Methods from MutableServerRequest class
    00288    // ----------------------------------------------------------
    00289
    00290    //void ClearPassport();
    00291
    00292    //void AddPassportLine( const char * p_line );
    00293
    00294    //void AddPassportLine( std::string p_line );
    00295
    00296    //int GetPassportLineCount();
    00297
    00298    // GetPassportLine() -- return one of the passport lines.
    00299    //
    00300    //  p_index must be in the range 0 - GetPassportLineCount()
    00301    //
    00302    // RETURNS:
    00303    //        the passport line
    00304    //     or NULL if index out of range, etc.
    00305    //
    00306    //const char * GetPassportLine( int p_index );
    00307
    00308    // EVERYTHING ABOVE (BETWEEN THE DOUBLE-DASHED LINES)
    00309    // MAY BE DELETED IN ACTUAL IMPLEMENTATIONS.
    00310    // ===========================================================
    00311
    00312
    00313 // DON'T DELETE THIS CLASS-TERMINATING BRACKET
    00314 };
    00315
    00316 #endif // _MSM_RequestTemplate_H