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)