protocols/http_parcom/include/http_parser.h - platform/external/opencore - Git at Google

 /* ------------------------------------------------------------------
  * Copyright (C) 1998-2009 PacketVideo
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
  * express or implied.
  * See the License for the specific language governing permissions
  * and limitations under the License.
  * -------------------------------------------------------------------
  */
 #ifndef HTTP_PARSER_H_
 #define HTTP_PARSER_H_


 ///////////////////////////////////////////////////////////////////////////////////////

 #include "oscl_base.h"
 #include "oscl_mem.h"
 #include "oscl_str_ptr_len.h"
 #include "http_parser_external.h" // define struct HTTPContentInfo and class RefCountHTTPEntityUnit

 // forward declarations
 struct HTTPContentInfoInternal;
 class  HTTPParserInput;
 class  HTTPParserHeaderObject;
 class  HTTPParserEntityBodyObject;

 class HTTPParser
 {

     public:

         /**
          * the sole parsing function to parse both HTTP header and entity body. Since the input data stream is a fragment of a complete
          * HTTP response message (for client), the input data fragment is assumed arbitrary, i.e, its starting and ending position could
          * be anywhere in a complete HTTP response message. Considering HTTP header could spread among multiple input data stream
          * fragments, like the entity body case, parsing header and parsing entity body can be handled in a unified way. The output is
          * entity unit which could be a complete HTTP header (FIRST entity unit), or a complete chunk of data for partial content, or the
          * whole input data fragment. To avoid memory copy, we do inplace processing, i.e. the output entity unit is represented by a set
          * of memory fragment pointers to point to the actual memory fragments inside the input data streams that may inlude the previous
          * input data streams. Considering an entity unit may need one or mulitple input data fragments and an input data fragment could
          * constain multiple entity units, the memory for an input data fragment can only be released after all the related entity units
          * it has have been parsed and used. So the input data fragment needs to reference counted. Also the output entity unit needs to
          * be reference counted. This lets the user not worry about how to release and re-use the existing memory fragment. Each time,
          * user just need to create new memory fragment from a memory pool and pass it down to library in normal cases. Reference counter
          * will automatically take care of memory deallocation. In the case where the previous input data fragment contains multiple entity
          * units, user needs to input EMPTY fragment or the previous fragment again to let the library send out the next entity unit (since
          * each time this function only sends out ONE enity unit if it has multiple).
          * Return value: see the following enum. For PARSE_HEADER_AVAILABLE, user need to call getHTTPStatusCode() to get status code
          * @param aInputDataStream, ref-counted input data fragment
          * @param aEntityUnit, ref-counted output entity unit
          * @return following PARSE_RETURN_CODES
          *
          * NOTE: as long as the return code is non-negative, user need to check the output entity unit to see whether there is something
          * inside, and also user needs to do concatenation for the output fragments.
          **/
         OSCL_IMPORT_REF int32 parse(const OsclRefCounterMemFrag &aInputDataStream, RefCountHTTPEntityUnit &aEntityUnit);


         /**
          * If http response header is available, status code is ok (though parse() already does some sanity check for status code),
          * there still could be some headers that need further check, i.e. some headers are only supported in HTTP/1.1, such as Transfer-Encoding
          * @return following PARSE_RETURN_CODES, list the unsupported items.
          **/
         OSCL_IMPORT_REF int32 doSanityCheckForResponseHeader();


         // return codes for parse function
         enum PARSE_RETURN_CODES
         {
             PARSE_SUCCESS                        = 0,   // success with left over of the current input, don't send the new input next time
             PARSE_SUCCESS_END_OF_INPUT           = 1,   // success with end of the current input
             PARSE_SUCCESS_END_OF_MESSAGE         = 2,   // success with end of the message (get data with the size of content-length)
             PARSE_SUCCESS_END_OF_MESSAGE_WITH_EXTRA_DATA = 3, // success with end of the message (get data with the size of content-length), but input has more extra data

             PARSE_HEADER_AVAILABLE               = 4,   // HTTP header is parsed
             PARSE_STATUS_LINE_SHOW_NOT_SUCCESSFUL = 5,  // parse the first http status line,
             // got status code >= 300, 3xx=>redirection, 4xx=>client error, 5xx=>server error
             // note that this is return code when parser just finishes parsing the first line,
             // user can continue calling parse function to get the complete http header
             PARSE_NEED_MORE_DATA                 = 6,   // no ouput, no entity units

             // errors
             PARSE_GENERAL_ERROR = -1,
             PARSE_SYNTAX_ERROR = -2,                // syntax is not understandable
             PARSE_HTTP_VERSION_NOT_SUPPORTED = -3,  // no HTTP version or HTTP version is different from 1.0 or 1.1.
             PARSE_TRANSFER_ENCODING_NOT_SUPPORTED = -4,
             PARSE_MEMORY_ALLOCATION_FAILURE = -5,   // memory allocation for entity units
             PARSE_HEADER_NOT_PARSED_YET = -6        // HTTP header hasn't been parsed yet, so shouldn't expect parsing entity body
         };


         // After parsing HTTP header(parse() return PARSE_HEADER_AVAILABLE), use the following functions to get the related information
         // get content info
         OSCL_IMPORT_REF void getContentInfo(HTTPContentInfo &aContentInfo);
         // get total fields inside the header
         OSCL_IMPORT_REF uint32 getTotalFieldsInHeader();
         // get a list of all field keys inside the header
         OSCL_IMPORT_REF uint32 getFieldKeyListInHeader(StrPtrLen *&aFieldKeyList);
         // get the field value with the given field key, which can be retrieved from getFieldKeyListInHeader()
         // There could be a case where one field key correponds to multiple field values, so input argument "index" is for
         // getting which value for the given field key
         OSCL_IMPORT_REF bool getField(const StrCSumPtrLen &aNewFieldName, StrPtrLen &aNewFieldValue, const uint32 index = 0);
         // get the number of field key-value pairs with the same field key. 0 => no such key, 1 or more => number of key-value pairs
         OSCL_IMPORT_REF uint32 getNumberOfFieldsByKey(const StrCSumPtrLen &aNewFieldName);
         // get the status code, 1xx, 2xx, 3xx, 4xx, 5xx
         OSCL_IMPORT_REF uint32 getHTTPStatusCode();
         /////////////////////////////////////////////////////////////////////////////////////////////

         // reset the parser to parse a new HTTP response
         OSCL_IMPORT_REF void reset();

         // factory method
         OSCL_IMPORT_REF static HTTPParser *create();

         // destructor
         OSCL_IMPORT_REF ~HTTPParser();

     private:
         int32 parseEntityBody(RefCountHTTPEntityUnit &aEntityUnit);

         // called by create() to construct the parser
         bool construct();

         // constructor
         HTTPParser()
         {
             oscl_memset(this, 0, sizeof(HTTPParser));
         }

     private:
         // Basically, this parser is decomposed into the following objects.
         // HTTPParserInput handles input data stream concatenation and fragment grouping for parsing and entity unit output
         // HTTPContentInfo contains content type, content length and content range information and does infomation parsing.
         // HTTPParserHeaderObject and HTTPParserEntityBodyObject handles header and entity body parsing
         HTTPParserInput         *iParserInput;
         HTTPContentInfoInternal *iContentInfo;
         HTTPParserHeaderObject  *iHeader;
         HTTPParserEntityBodyObject *iEntityBody;
 };

 #endif // HTTP_PARSER_H_
	/* ------------------------------------------------------------------
	* Copyright (C) 1998-2009 PacketVideo
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
	* express or implied.
	* See the License for the specific language governing permissions
	* and limitations under the License.
	* -------------------------------------------------------------------
	*/
	#ifndef HTTP_PARSER_H_
	#define HTTP_PARSER_H_


	///////////////////////////////////////////////////////////////////////////////////////

	#include "oscl_base.h"
	#include "oscl_mem.h"
	#include "oscl_str_ptr_len.h"
	#include "http_parser_external.h" // define struct HTTPContentInfo and class RefCountHTTPEntityUnit

	// forward declarations
	struct HTTPContentInfoInternal;
	class HTTPParserInput;
	class HTTPParserHeaderObject;
	class HTTPParserEntityBodyObject;

	class HTTPParser
	{

	public:

	/**
	* the sole parsing function to parse both HTTP header and entity body. Since the input data stream is a fragment of a complete
	* HTTP response message (for client), the input data fragment is assumed arbitrary, i.e, its starting and ending position could
	* be anywhere in a complete HTTP response message. Considering HTTP header could spread among multiple input data stream
	* fragments, like the entity body case, parsing header and parsing entity body can be handled in a unified way. The output is
	* entity unit which could be a complete HTTP header (FIRST entity unit), or a complete chunk of data for partial content, or the
	* whole input data fragment. To avoid memory copy, we do inplace processing, i.e. the output entity unit is represented by a set
	* of memory fragment pointers to point to the actual memory fragments inside the input data streams that may inlude the previous
	* input data streams. Considering an entity unit may need one or mulitple input data fragments and an input data fragment could
	* constain multiple entity units, the memory for an input data fragment can only be released after all the related entity units
	* it has have been parsed and used. So the input data fragment needs to reference counted. Also the output entity unit needs to
	* be reference counted. This lets the user not worry about how to release and re-use the existing memory fragment. Each time,
	* user just need to create new memory fragment from a memory pool and pass it down to library in normal cases. Reference counter
	* will automatically take care of memory deallocation. In the case where the previous input data fragment contains multiple entity
	* units, user needs to input EMPTY fragment or the previous fragment again to let the library send out the next entity unit (since
	* each time this function only sends out ONE enity unit if it has multiple).
	* Return value: see the following enum. For PARSE_HEADER_AVAILABLE, user need to call getHTTPStatusCode() to get status code
	* @param aInputDataStream, ref-counted input data fragment
	* @param aEntityUnit, ref-counted output entity unit
	* @return following PARSE_RETURN_CODES
	*
	* NOTE: as long as the return code is non-negative, user need to check the output entity unit to see whether there is something
	* inside, and also user needs to do concatenation for the output fragments.
	**/
	OSCL_IMPORT_REF int32 parse(const OsclRefCounterMemFrag &aInputDataStream, RefCountHTTPEntityUnit &aEntityUnit);


	/**
	* If http response header is available, status code is ok (though parse() already does some sanity check for status code),
	* there still could be some headers that need further check, i.e. some headers are only supported in HTTP/1.1, such as Transfer-Encoding
	* @return following PARSE_RETURN_CODES, list the unsupported items.
	**/
	OSCL_IMPORT_REF int32 doSanityCheckForResponseHeader();


	// return codes for parse function
	enum PARSE_RETURN_CODES
	{
	PARSE_SUCCESS = 0, // success with left over of the current input, don't send the new input next time
	PARSE_SUCCESS_END_OF_INPUT = 1, // success with end of the current input
	PARSE_SUCCESS_END_OF_MESSAGE = 2, // success with end of the message (get data with the size of content-length)
	PARSE_SUCCESS_END_OF_MESSAGE_WITH_EXTRA_DATA = 3, // success with end of the message (get data with the size of content-length), but input has more extra data

	PARSE_HEADER_AVAILABLE = 4, // HTTP header is parsed
	PARSE_STATUS_LINE_SHOW_NOT_SUCCESSFUL = 5, // parse the first http status line,
	// got status code >= 300, 3xx=>redirection, 4xx=>client error, 5xx=>server error
	// note that this is return code when parser just finishes parsing the first line,
	// user can continue calling parse function to get the complete http header
	PARSE_NEED_MORE_DATA = 6, // no ouput, no entity units

	// errors
	PARSE_GENERAL_ERROR = -1,
	PARSE_SYNTAX_ERROR = -2, // syntax is not understandable
	PARSE_HTTP_VERSION_NOT_SUPPORTED = -3, // no HTTP version or HTTP version is different from 1.0 or 1.1.
	PARSE_TRANSFER_ENCODING_NOT_SUPPORTED = -4,
	PARSE_MEMORY_ALLOCATION_FAILURE = -5, // memory allocation for entity units
	PARSE_HEADER_NOT_PARSED_YET = -6 // HTTP header hasn't been parsed yet, so shouldn't expect parsing entity body
	};


	// After parsing HTTP header(parse() return PARSE_HEADER_AVAILABLE), use the following functions to get the related information
	// get content info
	OSCL_IMPORT_REF void getContentInfo(HTTPContentInfo &aContentInfo);
	// get total fields inside the header
	OSCL_IMPORT_REF uint32 getTotalFieldsInHeader();
	// get a list of all field keys inside the header
	OSCL_IMPORT_REF uint32 getFieldKeyListInHeader(StrPtrLen *&aFieldKeyList);
	// get the field value with the given field key, which can be retrieved from getFieldKeyListInHeader()
	// There could be a case where one field key correponds to multiple field values, so input argument "index" is for
	// getting which value for the given field key
	OSCL_IMPORT_REF bool getField(const StrCSumPtrLen &aNewFieldName, StrPtrLen &aNewFieldValue, const uint32 index = 0);
	// get the number of field key-value pairs with the same field key. 0 => no such key, 1 or more => number of key-value pairs
	OSCL_IMPORT_REF uint32 getNumberOfFieldsByKey(const StrCSumPtrLen &aNewFieldName);
	// get the status code, 1xx, 2xx, 3xx, 4xx, 5xx
	OSCL_IMPORT_REF uint32 getHTTPStatusCode();
	/////////////////////////////////////////////////////////////////////////////////////////////

	// reset the parser to parse a new HTTP response
	OSCL_IMPORT_REF void reset();

	// factory method
	OSCL_IMPORT_REF static HTTPParser *create();

	// destructor
	OSCL_IMPORT_REF ~HTTPParser();

	private:
	int32 parseEntityBody(RefCountHTTPEntityUnit &aEntityUnit);

	// called by create() to construct the parser
	bool construct();

	// constructor
	HTTPParser()
	{
	oscl_memset(this, 0, sizeof(HTTPParser));
	}

	private:
	// Basically, this parser is decomposed into the following objects.
	// HTTPParserInput handles input data stream concatenation and fragment grouping for parsing and entity unit output
	// HTTPContentInfo contains content type, content length and content range information and does infomation parsing.
	// HTTPParserHeaderObject and HTTPParserEntityBodyObject handles header and entity body parsing
	HTTPParserInput *iParserInput;
	HTTPContentInfoInternal *iContentInfo;
	HTTPParserHeaderObject *iHeader;
	HTTPParserEntityBodyObject *iEntityBody;
	};

	#endif // HTTP_PARSER_H_