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)