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

Generated on Tue May 6 09:16:07 2003 for Earthworm Libs by doxygen1.3-rc3