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

# result_template.h

Go to the documentation of this file.

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