HttpResponse.h

00001 /*****************************************************************************
00002 *
00003 *  HttpResponse.h
00004 *  Copyright (C) 2011 Texas Instruments Incorporated - http://www.ti.com/
00005 *
00006 *  Redistribution and use in source and binary forms, with or without
00007 *  modification, are permitted provided that the following conditions
00008 *  are met:
00009 *
00010 *    Redistributions of source code must retain the above copyright
00011 *    notice, this list of conditions and the following disclaimer.
00012 *
00013 *    Redistributions in binary form must reproduce the above copyright
00014 *    notice, this list of conditions and the following disclaimer in the
00015 *    documentation and/or other materials provided with the   
00016 *    distribution.
00017 *
00018 *    Neither the name of Texas Instruments Incorporated nor the names of
00019 *    its contributors may be used to endorse or promote products derived
00020 *    from this software without specific prior written permission.
00021 *
00022 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
00023 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
00024 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00025 *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
00026 *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
00027 *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
00028 *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
00029 *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
00030 *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
00031 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
00032 *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00033 *
00034 *****************************************************************************/
00035 #ifndef _HTTP_RESPONSE_H_
00036 #define _HTTP_RESPONSE_H_
00037 
00038 #include "Common.h"
00039 #include "HttpString.h"
00040 
00041 /** 
00042  * @defgroup HttpResponse HTTP Response modules
00043  * This module implements routines to allow content handler modules to build and send HTTP responses back to the client.
00044  * There are two layers in this module:
00045  * - The lower layer consists of HttpResponse_Headers() and HttpResponse_Content(). These routines allow the caller to specify all details of the response.
00046  * - The higher layer consists of HttpResponse_Canned*(). These routines emit canned (pre-made) responses, such as redirects and errors, which are useful in many situations.
00047  *
00048  * @{
00049  */
00050 
00051 /**
00052  * @defgroup HttpStatus Supported HTTP status codes
00053  * @{
00054  */
00055 #define HTTP_STATUS_OK                 200
00056 #define HTTP_STATUS_REDIRECT_PERMANENT 301
00057 #define HTTP_STATUS_REDIRECT_TEMPORARY 302
00058 #define HTTP_STATUS_ERROR_UNAUTHORIZED 401
00059 #define HTTP_STATUS_ERROR_NOT_FOUND    404
00060 #define HTTP_STATUS_ERROR_NOT_ACCEPTED 406
00061 #define HTTP_STATUS_ERROR_INTERNAL     500
00062 
00063 /// @}
00064 
00065 /// The response data is gzip-compressed. Implies the header Content-Encoding: gzip
00066 #define HTTP_RESPONSE_FLAG_COMPRESSED   (1 << 0)
00067 
00068 /**
00069  * Respond with the specified HTTP status and headers
00070  * @param uConnection The connection number, as it appears in the HttpRequest structure
00071  * @param uHttpStatus The HTTP status number to response with. Must be one of HTTP_STATUS_*
00072  * @param uFlags Flags which are manifested in the response headers. See HTTP_RESPONSE_FLAG_*
00073  * @param uContentLength The total length of content which will be sent via HttpResponse_Content()
00074  * @param contentType The content type string, or NULL to omit the content type
00075  * @param location A string which will be used for the Location header, or NULL to omit the Location header
00076  */
00077 void HttpResponse_Headers(uint16 uConnection, uint16 uHttpStatus, uint16 uFlags, uint32 uContentLength, struct HttpBlob contentType, struct HttpBlob location);
00078 
00079 /**
00080  * Retrieves the pointer and size of the packet-send buffer
00081  * This function should be called by content handlers that wish to use the already-allocated packet-send buffer in calls to HttpResponse_Content()
00082  * @param[out] pPacketSendBuffer Returns the pointer and size of the packet-send buffer
00083  */
00084 void HttpResponse_GetPacketSendBuffer(struct HttpBlob* pPacketSendBuffer);
00085 
00086 /**
00087  * Send response content to the client.
00088  * This function may be called more than once, until all the content is sent.
00089  * @param uConnection The connection number, as it appears in the HttpRequest structure
00090  * @param content Content blob to send to the client.
00091  */
00092 void HttpResponse_Content(uint16 uConnection, struct HttpBlob content);
00093 
00094 /**
00095  * Sends a canned response, with an HTTP redirect
00096  * This function should be called *instead* of HttpResponse_Status(), HttpResponse_Headers() and HttpResponse_Content()
00097  * @param uConnection The connection number, as it appears in the HttpRequest structure
00098  * @param pLocation The redirect URL
00099  * @param bPermanent zero for temporary redirect, nonzero for permanent redirect
00100  */
00101 void HttpResponse_CannedRedirect(uint16 uConnection, struct HttpBlob location, uint16 bPermanent);
00102 
00103 /**
00104  * Sends a canned response, with an error message
00105  * This function should be called *instead* of HttpResponse_Status(), HttpResponse_Headers() and HttpResponse_Content()
00106  * @param uConnection The connection number, as it appears in the HttpRequest structure
00107  * @param uHttpStatus The HTTP error status. Must be one of HTTP_STATUS_ERROR_*
00108  */
00109 void HttpResponse_CannedError(uint16 uConnection, uint16 uHttpStatus);
00110 
00111 /// @}
00112 
00113 #endif //_HTTP_RESPONSE_H_
00114