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