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

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