net/tools/balsa/balsa_visitor_interface.h

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef NET_TOOLS_BALSA_BALSA_VISITOR_INTERFACE_H_
   6 #define NET_TOOLS_BALSA_BALSA_VISITOR_INTERFACE_H_
   7
   8 #include <cstddef>
   9
  10 namespace net {
  11
  12 class BalsaFrame;
  13 class BalsaHeaders;
  14
  15 // By default the BalsaFrame instantiates a class derived from this interface
  16 // which does absolutely nothing. If you'd prefer to have interesting
  17 // functionality execute when any of the below functions are called by the
  18 // BalsaFrame, then you should subclass it, and set an instantiation of your
  19 // subclass as the current visitor for the BalsaFrame class using
  20 // BalsaFrame::set_visitor().
  21 class BalsaVisitorInterface {
  22  public:
  23   virtual ~BalsaVisitorInterface() {}
  24
  25   // Summary:
  26   //   This is how the BalsaFrame passes you the raw input which it knows to
  27   //   be a part of the body. To be clear, every byte of the Balsa which isn't
  28   //   part of the header (or its framing), or trailers will be passed through
  29   //   this function.  This includes data as well as chunking framing.
  30   // Arguments:
  31   //   input - contains the bytes available for read.
  32   //   size - contains the number of bytes it is safe to read from input.
  33   virtual void ProcessBodyInput(const char *input, size_t size) = 0;
  34
  35   // Summary:
  36   //   This is like ProcessBodyInput, but it will only include those parts of
  37   //   the body which would be stored by a program such as wget, i.e. the bytes
  38   //   indicating chunking (it will have been omitted). Trailers will not be
  39   //   passed in through this function-- they'll be passed in through
  40   //   ProcessTrailers.
  41   // Arguments:
  42   //  input - contains the bytes available for read.
  43   //  size - contains the number of bytes it is safe to read from input.
  44   virtual void ProcessBodyData(const char *input, size_t size) = 0;
  45
  46   // Summary:
  47   //   BalsaFrame passes the raw header data through this function. This is
  48   //   not cleaned up in any way.
  49   // Arguments:
  50   //  input - contains the bytes available for read.
  51   //  size - contains the number of bytes it is safe to read from input.
  52   virtual void ProcessHeaderInput(const char *input, size_t size) = 0;
  53
  54   // Summary:
  55   //   BalsaFrame passes the raw trailer data through this function. This is
  56   //   not cleaned up in any way.  Note that trailers only occur in a message
  57   //   if there was a chunked encoding, and not always then.
  58   //
  59   // Arguments:
  60   //  input - contains the bytes available for read.
  61   //  size - contains the number of bytes it is safe to read from input.
  62   virtual void ProcessTrailerInput(const char *input, size_t size) = 0;
  63
  64   // Summary:
  65   //   Since the BalsaFrame already has to parse the headers in order to
  66   //   determine proper framing, it might as well pass the parsed and
  67   //   cleaned-up results to whatever might need it.  This function exists for
  68   //   that purpose-- parsed headers are passed into this function.
  69   // Arguments:
  70   //   headers - contains the parsed headers in the order in which
  71   //             they occured in the header.
  72   virtual void ProcessHeaders(const BalsaHeaders& headers) = 0;
  73
  74   // Summary:
  75   //   Called when the first line of the message is parsed, in this case, for a
  76   //   request.
  77   // Arguments:
  78   //   line_input - pointer to the beginning of the first line string.
  79   //   line_length - length of the first line string. (i.e. the numer of
  80   //                 bytes it is safe to read from line_ptr)
  81   //   method_input - pointer to the beginning of the method string
  82   //   method_length - length of the method string (i.e. the number
  83   //                   of bytes it is safe to read from method_input)
  84   //   request_uri_input - pointer to the beginning of the request uri
  85   //                       string.
  86   //   request_uri_length - length of the method string (i.e. the number
  87   //                        of bytes it is safe to read from method_input)
  88   //   version_input - pointer to the beginning of the version string.
  89   //   version_length - length of the version string (i.e. the number
  90   //                    of bytes it i ssafe to read from version_input)
  91   virtual void ProcessRequestFirstLine(const char* line_input,
  92                                        size_t line_length,
  93                                        const char* method_input,
  94                                        size_t method_length,
  95                                        const char* request_uri_input,
  96                                        size_t request_uri_length,
  97                                        const char* version_input,
  98                                        size_t version_length) = 0;
  99
 100   // Summary:
 101   //   Called when the first line of the message is parsed, in this case, for a
 102   //   response.
 103   // Arguments:
 104   //   line_input - pointer to the beginning of the first line string.
 105   //   line_length - length of the first line string. (i.e. the numer of
 106   //                 bytes it is safe to read from line_ptr)
 107   //   version_input - pointer to the beginning of the version string.
 108   //   version_length - length of the version string (i.e. the number
 109   //                    of bytes it i ssafe to read from version_input)
 110   //   status_input - pointer to the beginning of the status string
 111   //   status_length - length of the status string (i.e. the number
 112   //                   of bytes it is safe to read from status_input)
 113   //   reason_input - pointer to the beginning of the reason string
 114   //   reason_length - length of the reason string (i.e. the number
 115   //                   of bytes it is safe to read from reason_input)
 116   virtual void ProcessResponseFirstLine(const char *line_input,
 117                                         size_t line_length,
 118                                         const char *version_input,
 119                                         size_t version_length,
 120                                         const char *status_input,
 121                                         size_t status_length,
 122                                         const char *reason_input,
 123                                         size_t reason_length) = 0;
 124
 125   // Called when a chunk length is parsed.
 126   // Arguments:
 127   //   chunk length - the length of the next incoming chunk.
 128   virtual void ProcessChunkLength(size_t chunk_length) = 0;
 129
 130   // Summary:
 131   //   BalsaFrame passes the raw chunk extension data through this function.
 132   //   The data is not cleaned up at all, use
 133   //   BalsaFrame::ProcessChunkExtentions to get the parsed and cleaned up
 134   //   chunk extensions.
 135   //
 136   // Arguments:
 137   //  input - contains the bytes available for read.
 138   //  size - contains the number of bytes it is safe to read from input.
 139   virtual void ProcessChunkExtensions(const char* input, size_t size) = 0;
 140
 141   // Summary:
 142   //   Called when the header is framed and processed.
 143   virtual void HeaderDone() = 0;
 144
 145   // Summary:
 146   //   Called when the message is framed and processed.
 147   virtual void MessageDone() = 0;
 148
 149   // Summary:
 150   //   Called when an error is detected while parsing the header.
 151   // Arguments:
 152   //   framer - the framer in which an error occured.
 153   virtual void HandleHeaderError(BalsaFrame* framer) = 0;
 154
 155   // Summary:
 156   //   Called when something meriting a warning is detected while
 157   //   parsing the header.
 158   // Arguments:
 159   //   framer - the framer in which an error occured.
 160   virtual void HandleHeaderWarning(BalsaFrame* framer) = 0;
 161
 162   // Summary:
 163   //   Called when an error is detected while parsing a chunk.
 164   // Arguments:
 165   //   framer - the framer in which an error occured.
 166   virtual void HandleChunkingError(BalsaFrame* framer) = 0;
 167
 168   // Summary:
 169   //   Called when an error is detected while handling the entity-body.
 170   //   Currently, this can only be called when there is an error
 171   //   with the BytesSpliced() function, but in the future other interesting
 172   //   errors could occur.
 173   // Arguments:
 174   //   framer - the framer in which an error occured.
 175   virtual void HandleBodyError(BalsaFrame* framer) = 0;
 176 };
 177
 178 }  // namespace net
 179
 180 #endif  // NET_TOOLS_BALSA_BALSA_VISITOR_INTERFACE_H_