From: Amos Jeffries Date: Sun, 11 May 2008 11:37:14 +0000 (+1200) Subject: Auto-Doc Server.h and HttpReply.h X-Git-Tag: SQUID_3_1_0_1~49^2~246 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e0459b286f0ffcbc33aafb99053686e92a7621ac;p=thirdparty%2Fsquid.git Auto-Doc Server.h and HttpReply.h --- diff --git a/src/HttpReply.h b/src/HttpReply.h index bf8fb42f41..2fe554cd29 100644 --- a/src/HttpReply.h +++ b/src/HttpReply.h @@ -1,4 +1,3 @@ - /* * $Id: HttpReply.h,v 1.24 2008/02/26 21:49:34 amosjeffries Exp $ * @@ -30,7 +29,6 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA. * */ - #ifndef SQUID_HTTPREPLY_H #define SQUID_HTTPREPLY_H @@ -38,7 +36,8 @@ #include "HttpStatusLine.h" extern void httpReplyInitModule(void); -/* do everything in one call: init, set, pack, clean, return MemBuf */ + +/** do everything in one call: init, set, pack, clean, return MemBuf */ extern MemBuf *httpPackedReply(HttpVersion ver, http_status status, const char *ctype, int64_t clen, time_t lmt, time_t expires); /* Sync changes here with HttpReply.cc */ @@ -57,20 +56,21 @@ public: virtual void reset(); - // use HTTPMSGLOCK() instead of calling this directly - virtual HttpReply *_lock() - { + /// \par use HTTPMSGLOCK() instead of calling this directly + virtual HttpReply *_lock() { return static_cast(HttpMsg::_lock()); }; //virtual void unlock(); // only needed for debugging - // returns true on success - // returns false and sets *error to zero when needs more data - // returns false and sets *error to a positive http_status code on error + /** + \retval true on success + \retval false and sets *error to zero when needs more data + \retval false and sets *error to a positive http_status code on error + */ virtual bool sanityCheckStartLine(MemBuf *buf, http_status *error); - /* public, readable; never update these or their .hdr equivalents directly */ + /** \par public, readable; never update these or their .hdr equivalents directly */ time_t date; time_t last_modified; @@ -85,12 +85,12 @@ public: short int keep_alive; - /* public, writable, but use httpReply* interfaces when possible */ + /** \par public, writable, but use httpReply* interfaces when possible */ HttpStatusLine sline; - HttpBody body; /* for small constant memory-resident text bodies only */ + HttpBody body; /**< for small constant memory-resident text bodies only */ - String protoPrefix; // e.g., "HTTP/" + String protoPrefix; /**< e.g., "HTTP/" */ bool do_clean; @@ -101,39 +101,41 @@ public: void updateOnNotModified(HttpReply const *other); - /* set commonly used info with one call */ + /** set commonly used info with one call */ void setHeaders(HttpVersion ver, http_status status, const char *reason, const char *ctype, int64_t clen, time_t lmt, time_t expires); - /* mem-pack: returns a ready to use mem buffer with a packed reply */ + /** \return a ready to use mem buffer with a packed reply */ MemBuf *pack(); - /* construct a 304 reply and return it */ + /** construct a 304 reply and return it */ HttpReply *make304() const; void redirect(http_status, const char *); int64_t bodySize(const HttpRequestMethod&) const; - /// Checks whether received body exceeds known maximum size. - /// Requires a prior call to calcMaxBodySize(). + /** Checks whether received body exceeds known maximum size. + * Requires a prior call to calcMaxBodySize(). + */ bool receivedBodyTooLarge(HttpRequest&, int64_t receivedBodySize); - /// Checks whether expected body exceeds known maximum size. - /// Requires a prior call to calcMaxBodySize(). + /** Checks whether expected body exceeds known maximum size. + * Requires a prior call to calcMaxBodySize(). + */ bool expectedBodyTooLarge(HttpRequest& request); int validatorsMatch (HttpReply const *other) const; void packHeadersInto(Packer * p) const; - /// Clone this reply. - /// Could be done as a copy-contructor but we do not want to - /// accidently copy a HttpReply.. + /** Clone this reply. + * Could be done as a copy-contructor but we do not want to accidently copy a HttpReply.. + */ HttpReply *clone() const; private: - /* initialize */ + /** initialize */ void init(); void clean(); @@ -143,17 +145,18 @@ private: void packInto(Packer * p); /* ez-routines */ - /* construct 304 reply and pack it into MemBuf, return MemBuf */ + /** \return construct 304 reply and pack it into a MemBuf */ MemBuf *packed304Reply(); /* header manipulation */ time_t hdrExpirationTime(); - // Calculates and stores maximum body size if needed. Used by - // receivedBodyTooLarge() and expectedBodyTooLarge(). + /** Calculates and stores maximum body size if needed. + * Used by receivedBodyTooLarge() and expectedBodyTooLarge(). + */ void calcMaxBodySize(HttpRequest& request); - mutable int64_t bodySizeMax; // cached result of calcMaxBodySize + mutable int64_t bodySizeMax; /**< cached result of calcMaxBodySize */ protected: virtual void packFirstLineInto(Packer * p, bool) const; @@ -163,6 +166,6 @@ protected: virtual void hdrCacheInit(); }; -MEMPROXY_CLASS_INLINE(HttpReply) /**DOCS_NOSEMI*/ +MEMPROXY_CLASS_INLINE(HttpReply); #endif /* SQUID_HTTPREPLY_H */ diff --git a/src/Server.h b/src/Server.h index 807d08e5f8..1680ee3ef7 100644 --- a/src/Server.h +++ b/src/Server.h @@ -31,18 +31,6 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA. * */ - -/* - * ServerStateData is a common base for server-side classes such as - * HttpStateData and FtpStateData. All such classes must be able to - * consume request bodies from the client-side or ICAP producer, adapt - * virgin responses using ICAP, and provide the client-side consumer with - * responses. - * - * TODO: Rename to ServerStateDataInfoRecordHandler. - */ - - #ifndef SQUID_SERVER_H #define SQUID_SERVER_H @@ -57,6 +45,15 @@ #include "adaptation/Initiator.h" #endif +/** + * ServerStateData is a common base for server-side classes such as + * HttpStateData and FtpStateData. All such classes must be able to + * consume request bodies from the client-side or ICAP producer, adapt + * virgin responses using ICAP, and provide the client-side consumer with + * responses. + * + \todo TODO: Rename to ServerStateDataInfoRecordHandler. + */ class ServerStateData: #if USE_ADAPTATION public Adaptation::Initiator, @@ -69,7 +66,7 @@ public: ServerStateData(FwdState *); virtual ~ServerStateData(); - // returns primary or "request data connection" fd + /// \return primary or "request data connection" fd virtual int dataDescriptor() const = 0; // BodyConsumer: consume request body or adapted response body. @@ -79,13 +76,13 @@ public: virtual void noteBodyProductionEnded(BodyPipe::Pointer); virtual void noteBodyProducerAborted(BodyPipe::Pointer); - // read response data from the network + /// read response data from the network virtual void maybeReadVirginBody() = 0; - // abnormal transaction termination; reason is for debugging only + /// abnormal transaction termination; reason is for debugging only virtual void abortTransaction(const char *reason) = 0; - // a hack to reach HttpStateData::orignal_request + /// a hack to reach HttpStateData::orignal_request virtual HttpRequest *originalRequest(); #if USE_ADAPTATION @@ -111,16 +108,16 @@ public: BodyConsumer::doneAll() && false;} public: // should be protected - void serverComplete(); // call when no server communication is expected + void serverComplete(); /**< call when no server communication is expected */ private: - void serverComplete2(); // Continuation of serverComplete - bool completed; // serverComplete() has been called + void serverComplete2(); /**< Continuation of serverComplete */ + bool completed; /**< serverComplete() has been called */ protected: // kids customize these - virtual void haveParsedReplyHeaders(); // default does nothing - virtual void completeForwarding(); // default calls fwd->complete() + virtual void haveParsedReplyHeaders(); /**< default does nothing */ + virtual void completeForwarding(); /**< default calls fwd->complete() */ // BodyConsumer for HTTP: consume request body. bool startRequestBodyFlow(); @@ -134,17 +131,17 @@ protected: virtual void sentRequestBody(const CommIoCbParams &io) = 0; virtual void doneSendingRequestBody() = 0; - virtual void closeServer() = 0; // end communication with the server - virtual bool doneWithServer() const = 0; // did we end communication? + virtual void closeServer() = 0; /**< end communication with the server */ + virtual bool doneWithServer() const = 0; /**< did we end communication? */ - // Entry-dependent callbacks use this check to quit if the entry went bad + /// Entry-dependent callbacks use this check to quit if the entry went bad bool abortOnBadEntry(const char *abortReason); #if USE_ADAPTATION bool startAdaptation(Adaptation::ServicePointer service, HttpRequest *cause); void adaptVirginReplyBody(const char *buf, ssize_t len); void cleanAdaptation(); - virtual bool doneWithAdaptation() const; // did we end ICAP communication? + virtual bool doneWithAdaptation() const; /**< did we end ICAP communication? */ // BodyConsumer for ICAP: consume adapted response body. void handleMoreAdaptedBodyAvailable(); @@ -170,8 +167,8 @@ protected: size_t replyBodySpace(size_t space = 4096 * 10); // These should be private - int64_t currentOffset; // Our current offset in the StoreEntry - MemBuf *responseBodyBuffer; // Data temporarily buffered for ICAP + int64_t currentOffset; /**< Our current offset in the StoreEntry */ + MemBuf *responseBodyBuffer; /**< Data temporarily buffered for ICAP */ public: // should not be StoreEntry *entry; @@ -179,24 +176,24 @@ public: // should not be HttpRequest *request; protected: - BodyPipe::Pointer requestBodySource; // to consume request body - AsyncCall::Pointer requestSender; // set if we are expecting comm_write to call us back + BodyPipe::Pointer requestBodySource; /**< to consume request body */ + AsyncCall::Pointer requestSender; /**< set if we are expecting comm_write to call us back */ #if USE_ADAPTATION - BodyPipe::Pointer virginBodyDestination; // to provide virgin response body - Adaptation::Initiate *adaptedHeadSource; // to get adapted response headers - BodyPipe::Pointer adaptedBodySource; // to consume adated response body + BodyPipe::Pointer virginBodyDestination; /**< to provide virgin response body */ + Adaptation::Initiate *adaptedHeadSource; /**< to get adapted response headers */ + BodyPipe::Pointer adaptedBodySource; /**< to consume adated response body */ bool adaptationAccessCheckPending; bool startedAdaptation; #endif private: - void quitIfAllDone(); // successful termination + void quitIfAllDone(); /**< successful termination */ void sendBodyIsTooLargeError(); - HttpReply *theVirginReply; // reply received from the origin server - HttpReply *theFinalReply; // adapted reply from ICAP or virgin reply + HttpReply *theVirginReply; /**< reply received from the origin server */ + HttpReply *theFinalReply; /**< adapted reply from ICAP or virgin reply */ }; #endif /* SQUID_SERVER_H */