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

mutableservermessage.h

Go to the documentation of this file.
00001 // mutableserverresult.h: interface for the MutableServerResult class.
00002 //
00004 
00005 #if !defined(MUTABLESERVERMESSAGE_H)
00006 #define MUTABLESERVERMESSAGE_H
00007 
00008 #if _MSC_VER > 1000
00009 #pragma once
00010 #endif // _MSC_VER > 1000
00011 
00012 
00013 // microsoft pragma to avoid warnings relating to the container
00014 // template names being too long
00015 #pragma warning(disable:4786)
00016 
00017 #include <string>  // for std::string
00018 #include <vector>  // for std::vector
00019 #include <worm_exceptions.h>
00020 
00021 /*
00022 enum MSR_PARSE_STATE
00023 {
00024   MSR_PARSE_COMPLETE   = 0
00025 , MSR_PARSE_INCOMPLETE = 1
00026 , MSR_PARSE_ERROR      = 2
00027 };
00028 */
00029 
00030 
00031 class MutableServerMessage 
00032 {
00033 protected:
00034    
00035    std::string MessageBuffer;
00036 
00037    // ----------------------------------------------------------
00038    //     virtual methods from MutableServerMessage
00039    //     to be implemented for a complete derivative classes
00040    // ----------------------------------------------------------
00041 
00042    // BufferInitAlloc -- when preparing to format a message
00043    //                    using FormatBuffer()], this is
00044    //                    first called.  The result is,
00045    //                    for the first call, MessageBuffer
00046    //                    will be assured to be at least this
00047    //                    long.
00048    //                    Overriding this method allows
00049    //                    derivative classes to minimize
00050    //                    reallocations as message bits are appended
00051    //                    to the message buffer;
00052    //
00053    // NOTE: In each derivative implementation,
00054    //       call <super_class>::BufferInitAlloc() to get the
00055    //       space needed by that super class (and all baser
00056    //       classes), then add the size needed by the
00057    //       derivative to arrive at the total size needed.
00058    //       The 10 specified here is for the message-
00059    //       terminating '\n' and a slight overrun space.
00060    //
00061    virtual long BufferInitAlloc() { return 10L; }
00062 
00063 
00064    // FormatDerivativeData
00065    //
00066    //     Method by which derivative classes append
00067    //     their content to MessageBuffer.
00068    //
00069    //
00070    //  NOTE: ALWAYS CALL <super_class>::FormatDerivativeData()
00071    //        at the start of each implementation to allow
00072    //        base classes to append their stuff (if any)
00073    //        to the buffer.
00074    //        Thus the buffer is built up from the base-most class.
00075    //
00076    // THROW worm_exception for errors
00077    //
00078    virtual void FormatDerivativeData() { return; }
00079 
00080 
00081    // ParseDerivativeData
00082    //
00083    //     Method by which derivative classes extract
00084    //     their content to MessageBuffer.
00085    //
00086    //  NOTE: Always call <super_class>::ParseDerivativeData()
00087    //        at the top of each implementation to allow
00088    //        base classes to get their data out of the
00089    //        buffer first.
00090    //
00091    //  USAGE:
00092    //
00093    //     If parsing a multi-line message ('\n'-terminated lines),
00094    //     use a loop consisting of:
00095    //
00096    //       i = MessageBuffer.find("\n")  to find the first line end,
00097    //       MessageBuffer.substr(0, i)    to extract the string
00098    //                                        (excluding the '\n')
00099    //       MessageBuffer.erase(0, i+1)     to remove that portion
00100    //
00101    //     Since the message should be terminated by an additional
00102    //     '\n', when the string returned in the second step
00103    //     is of zero length, that is the end of the message.
00104    //
00105    //     (If find() does not, it returns MessageBuffer.npos)
00106    //
00107    // THROW worm_exception for errors
00108    //
00109    virtual void ParseDerivativeData() { return; }
00110 
00111 public:
00112 
00113         MutableServerMessage();
00114 
00115    // FormatBuffer()
00116    //
00117    //   -- calls BufferInitAlloc()
00118    //   -- calls FormatDerivativeData()
00119    //   -- terminates the buffer with an additional '\n'
00120    //      (that is, a line of zero length)
00121    //
00122    // THROWs worm_exception for errors
00123    //
00124    void FormatBuffer();
00125 
00126    // GetBufferLength()
00127    // GetBuffer()
00128    //
00129    //       Used to obtain an ascii buffer suitable for
00130    //       transmission across a socket or ring.
00131    // 
00132    long GetBufferLength() const;
00133    const char * GetBuffer() const;
00134 
00135    // ParseMessageLine -- used to handle a buffer which contains
00136    //                     only one '\n' terminated line, and which,
00137    //                     therefore may or may not be a complete
00138    //                     message.
00139    //
00140    //   This method:
00141    //   -- calls BufferInitAlloc()
00142    //   -- if strlen(p_buffer) > 0:
00143    //      -- appends buffer to MessageBuffer
00144    //      -- if p_append_nl == true
00145    //         -- appends '\n' to MessageBuffer
00146    //   -- else  [[ strlen(p_buffer) == 0 ]]
00147    //      -- if p_append_nl == true
00148    //         -- appends '\n' to MessageBuffer
00149    //      -- calls ParseDerivativeData()
00150    //
00151    // p_buffer: single line of a message
00152    //           (terminating '\n' stripped off)
00153    //
00154    // p_append_nl: should '\n' be appended to p_buffer
00155    //           
00156    // p_clearbuffer: used to clear MessageBuffer for first
00157    //                line of message.
00158    //
00159    // RETURNS:
00160    //      true  = this line completed the message and parsing completed
00161    //      false = this line did not finish the message
00162    //
00163    // THROWs worm_exception for errors
00164    //
00165    bool ParseMessageLine( const char * p_buffer
00166                         ,       bool   p_append_nl   = true
00167                         ,       bool   p_clearbuffer = false
00168                         );
00169 
00170    // ParseFromBuffer -- used to parse a buffer which is known to
00171    //                    be complete.  Specifically, messages
00172    //                    which arrive from a ring.
00173    //
00174    // THROWs worm_exception for errors
00175    //
00176    void ParseFromBuffer( const char * p_buffer );
00177 };
00178 
00179 #endif // !defined(MUTABLESERVERMESSAGE_H)

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