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