httpreadwrite.h

00001 
00002 //
00003 // Copyright (c) 2000-2003 Intel Corporation 
00004 // All rights reserved. 
00005 //
00006 // Redistribution and use in source and binary forms, with or without 
00007 // modification, are permitted provided that the following conditions are met: 
00008 //
00009 // * Redistributions of source code must retain the above copyright notice, 
00010 // this list of conditions and the following disclaimer. 
00011 // * Redistributions in binary form must reproduce the above copyright notice, 
00012 // this list of conditions and the following disclaimer in the documentation 
00013 // and/or other materials provided with the distribution. 
00014 // * Neither name of Intel Corporation nor the names of its contributors 
00015 // may be used to endorse or promote products derived from this software 
00016 // without specific prior written permission.
00017 // 
00018 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
00019 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
00020 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
00021 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR 
00022 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
00023 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
00024 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
00025 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 
00026 // OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00027 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
00028 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029 //
00031 
00032 #ifndef GENLIB_NET_HTTP_HTTPREADWRITE_H
00033 #define GENLIB_NET_HTTP_HTTPREADWRITE_H
00034 
00035 #include "config.h"
00036 #include "util.h"
00037 #include "sock.h"
00038 #include "httpparser.h"
00039 
00040 // timeout in secs
00041 #define HTTP_DEFAULT_TIMEOUT    30
00042 
00043 
00044 
00045 #ifdef __cplusplus
00046 #extern "C" {
00047 #endif
00048 
00049 int
00050 http_CancelHttpGet( IN void *Handle );
00051 
00052 /************************************************************************
00053  * Function: http_FixUrl
00054  *
00055  * Parameters:
00056  *      IN uri_type* url;               URL to be validated and fixed
00057  *      OUT uri_type* fixed_url;        URL after being fixed.
00058  *
00059  * Description:
00060  *      Validates URL
00061  *
00062  * Returns:
00063  *       UPNP_E_INVALID_URL
00064  *       UPNP_E_SUCCESS
00065  ************************************************************************/
00066 int http_FixUrl( IN uri_type* url, OUT uri_type* fixed_url );
00067 
00068 
00069 /************************************************************************
00070  * Function: http_FixStrUrl
00071  *
00072  * Parameters:
00073  *      IN char* urlstr ;               Character string as a URL
00074  *      IN int urlstrlen ;              Length of the character string
00075  *      OUT uri_type* fixed_url ;       Fixed and corrected URL
00076  *
00077  * Description:
00078  *      Parses URL and then validates URL
00079  *
00080  * Returns:
00081  *       UPNP_E_INVALID_URL
00082  *       UPNP_E_SUCCESS
00083  ************************************************************************/
00084 int http_FixStrUrl( IN const char* urlstr, IN int urlstrlen, OUT uri_type* fixed_url );
00085 
00086 
00087 /************************************************************************
00088  * Function: http_Connect
00089  *
00090  * Parameters:
00091  *      IN uri_type* destination_url;   URL containing destination information
00092  *      OUT uri_type *url;              Fixed and corrected URL
00093  *
00094  * Description:
00095  *      Gets destination address from URL and then connects to the remote end
00096  *
00097  *  Returns:
00098  *      socket descriptor on sucess
00099  *      UPNP_E_OUTOF_SOCKET
00100  *      UPNP_E_SOCKET_CONNECT on error
00101  ************************************************************************/
00102 int http_Connect( IN uri_type* destination_url, OUT uri_type *url );
00103 
00104 
00105 /************************************************************************
00106  * Function: http_RecvMessage
00107  *
00108  * Parameters:
00109  *      IN SOCKINFO *info;                      Socket information object
00110  *      OUT http_parser_t* parser;              HTTP parser object
00111  *      IN http_method_t request_method;        HTTP request method
00112  *      IN OUT int* timeout_secs;               time out
00113  *      OUT int* http_error_code;               HTTP error code returned
00114  *
00115  * Description:
00116  *      Get the data on the socket and take actions based on the read data
00117  *      to modify the parser objects buffer. If an error is reported while
00118  *      parsing the data, the error code is passed in the http_errr_code
00119  *      parameter
00120  *
00121  * Returns:
00122  *       UPNP_E_BAD_HTTPMSG
00123  *       UPNP_E_SUCCESS
00124  ************************************************************************/
00125 int http_RecvMessage( IN SOCKINFO *info, OUT http_parser_t* parser,
00126                 IN http_method_t request_method, 
00127                 IN OUT int* timeout_secs,
00128                 OUT int* http_error_code );
00129 
00130 
00131 /************************************************************************
00132  * Function: http_SendMessage
00133  *
00134  * Parameters:
00135  *      IN SOCKINFO *info ;             Socket information object
00136  *      IN OUT int * TimeOut ;          time out value
00137  *      IN const char* fmt, ...  Pattern format to take actions upon
00138  *
00139  * Description:
00140  *      Sends a message to the destination based on the
00141  *      IN const char* fmt parameter
00142  *      fmt types:
00143  *              'f':    arg = const char * file name
00144  *              'm':    arg1 = const char * mem_buffer; arg2= size_t buf_length
00145  *      E.g.:
00146  *              char *buf = "POST /xyz.cgi http/1.1\r\n\r\n";
00147  *              char *filename = "foo.dat";
00148  *              int status = http_SendMessage( tcpsock, "mf",
00149  *                      buf, strlen(buf),       // args for memory buffer
00150  *                      filename );             // arg for file
00151  *
00152  * Returns:
00153  *      UPNP_E_OUTOF_MEMORY
00154  *      UPNP_E_FILE_READ_ERROR
00155  *      UPNP_E_SUCCESS
00156  ************************************************************************/
00157 int http_SendMessage(
00158         IN SOCKINFO *info,
00159         IN OUT int* timeout_secs, 
00160         IN const char* fmt, ... );
00161 
00162 
00163 /************************************************************************
00164  * Function: http_RequestAndResponse
00165  *
00166  * Parameters:
00167  *      IN uri_type* destination;       Destination URI object which contains
00168  *                                      remote IP address among other elements
00169  *      IN const char* request;         Request to be sent
00170  *      IN size_t request_length;       Length of the request
00171  *      IN http_method_t req_method;    HTTP Request method
00172  *      IN int timeout_secs;            time out value
00173  *      OUT http_parser_t* response;    Parser object to receive the repsonse
00174  *
00175  * Description:
00176  *      Initiates socket, connects to the destination, sends a
00177  *      request and waits for the response from the remote end
00178  *
00179  * Returns:
00180  *      UPNP_E_SOCKET_ERROR
00181  *      UPNP_E_SOCKET_CONNECT
00182  *      Error Codes returned by http_SendMessage
00183  *      Error Codes returned by http_RecvMessage
00184  ************************************************************************/
00185 int http_RequestAndResponse(
00186         IN uri_type* destination,
00187         IN const char* request,
00188         IN size_t request_length,
00189         IN http_method_t req_method,
00190         IN int timeout_secs, 
00191         OUT http_parser_t* response );
00192 
00193 
00194 /************************************************************************
00195  * return codes:
00196  *      0 -- success
00197  *      UPNP_E_OUTOF_MEMORY
00198  *      UPNP_E_TIMEDOUT
00199  *      UPNP_E_BAD_REQUEST
00200  *      UPNP_E_BAD_RESPONSE
00201  *      UPNP_E_INVALID_URL
00202  *      UPNP_E_SOCKET_READ
00203  *      UPNP_E_SOCKET_WRITE
00204  ************************************************************************/
00205 
00206 
00207 /************************************************************************
00208  * Function: http_Download
00209  *
00210  * Parameters:
00211  *      IN const char* url_str; String as a URL
00212  *      IN int timeout_secs;    time out value
00213  *      OUT char** document;    buffer to store the document extracted
00214  *                              from the donloaded message.
00215  *      OUT int* doc_length;    length of the extracted document
00216  *      OUT char* content_type; Type of content
00217  *
00218  * Description:
00219  *      Download the document message and extract the document 
00220  *      from the message.
00221  *
00222  * Return: int
00223  *      UPNP_E_SUCCESS
00224  *      UPNP_E_INVALID_URL
00225  ************************************************************************/
00226 int http_Download(
00227         IN const char* url, 
00228         IN int timeout_secs,
00229         OUT char** document,
00230         OUT int* doc_length,
00231         OUT char* content_type );
00232 
00233 
00234 /************************************************************************
00235  * Function: http_WriteHttpPost
00236  *
00237  * Parameters:
00238  *      IN void *Handle:        Handle to the http post object
00239  *      IN char *buf:           Buffer to send to peer, if format used
00240  *                              is not UPNP_USING_CHUNKED, 
00241  *      IN unsigned int *size:  Size of the data to be sent.
00242  *      IN int timeout:         time out value
00243  *
00244  * Description:
00245  *      Formats data if format used is UPNP_USING_CHUNKED.
00246  *      Writes data on the socket connected to the peer.
00247  *
00248  * Return: int
00249  *      UPNP_E_SUCCESS - On Success
00250  *      UPNP_E_INVALID_PARAM - Invalid Parameter
00251  *      -1 - On Socket Error.
00252  ************************************************************************/
00253 int http_WriteHttpPost(IN void *Handle,
00254                        IN char *buf,
00255                        IN unsigned int *size,
00256                        IN int timeout);
00257 
00258 
00259 /************************************************************************
00260  * Function: http_CloseHttpPost
00261  *
00262  * Parameters:
00263  *      IN void *Handle;        Handle to the http post object
00264  *      IN OUT int *httpStatus; HTTP status returned on receiving a
00265  *                              response message
00266  *      IN int timeout;         time out value
00267  *
00268  * Description:
00269  *      Sends remaining data if using  UPNP_USING_CHUNKED 
00270  *      format. Receives any more messages. Destroys socket and any socket
00271  *      associated memory. Frees handle associated with the HTTP POST msg.
00272  *
00273  * Return: int
00274  *      UPNP_E_SUCCESS          - On Sucess
00275  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
00276  ************************************************************************/
00277 int http_CloseHttpPost(IN void *Handle, 
00278                        IN OUT int *httpStatus,
00279                        IN int timeout);
00280 
00281 
00282 /************************************************************************
00283  * Function: http_OpenHttpPost
00284  *
00285  * Parameters:
00286  *      IN const char *url_str;         String as a URL 
00287  *      IN OUT void **Handle;           Pointer to buffer to store HTTP
00288  *                                      post handle
00289  *      IN const char *contentType;     Type of content
00290  *      IN int contentLength;           length of content
00291  *      IN int timeout;                 time out value
00292  *
00293  * Description:
00294  *      Makes the HTTP POST message, connects to the peer, 
00295  *      sends the HTTP POST request. Adds the post handle to buffer of 
00296  *      such handles
00297  *
00298  * Return : int;
00299  *      UPNP_E_SUCCESS          - On Sucess
00300  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
00301  *      UPNP_E_OUTOF_MEMORY
00302  *      UPNP_E_SOCKET_ERROR
00303  *      UPNP_E_SOCKET_CONNECT
00304  ************************************************************************/
00305 int http_OpenHttpPost(IN const char *url_str,
00306                       IN OUT void **Handle,
00307                       IN const char *contentType,
00308                       IN int contentLength,
00309                       IN int timeout);
00310 
00311 
00312 /************************************************************************
00313  * Function: http_ReadHttpGet
00314  *
00315  * Parameters:
00316  *      IN void *Handle;                Handle to the HTTP get object
00317  *      IN OUT char *buf;               Buffer to get the read and parsed data
00318  *      IN OUT unsigned int *size;      Size of the buffer passed
00319  *      IN int timeout;                 time out value
00320  *
00321  * Description:
00322  *      Parses already existing data, then gets new data.
00323  *      Parses and extracts information from the new data.
00324  *
00325  * Return: int
00326  *      UPNP_E_SUCCESS          - On Sucess
00327  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
00328  *      UPNP_E_BAD_RESPONSE
00329  *      UPNP_E_BAD_HTTPMSG
00330  *      UPNP_E_CANCELED
00331  ************************************************************************/
00332 int http_ReadHttpGet(
00333         IN void *Handle,
00334         IN OUT char *buf,
00335         IN OUT unsigned int *size,
00336         IN int timeout);
00337 
00338 
00339 /************************************************************************
00340  * Function: http_HttpGetProgress
00341  *
00342  * Parameters:
00343  *      IN void *Handle;                Handle to the HTTP get object
00344  *      OUT unsigned int *length;       Buffer to get the read and parsed data
00345  *      OUT unsigned int *total;        Size of tge buffer passed
00346  *
00347  * Description:
00348  *      Extracts information from the Handle to the HTTP get object.
00349  *
00350  * Return: int
00351  *      UPNP_E_SUCCESS          - On Sucess
00352  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
00353  ************************************************************************/
00354 int http_HttpGetProgress(
00355         IN void *Handle,
00356         OUT unsigned int *length,
00357         OUT unsigned int *total );
00358 
00359 
00360 /************************************************************************
00361  * Function: http_CloseHttpGet
00362  *
00363  * Parameters:
00364  *      IN void *Handle;        Handle to HTTP get object
00365  *
00366  * Description:
00367  *      Clears the handle allocated for the HTTP GET operation
00368  *      Clears socket states and memory allocated for socket operations. 
00369  *
00370  * Return: int
00371  *      UPNP_E_SUCCESS          - On Success
00372  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
00373  ************************************************************************/
00374 int http_CloseHttpGet(IN void *Handle);
00375 
00376 
00377 /************************************************************************
00378  * Function: http_OpenHttpGet
00379  *
00380  * Parameters:
00381  *      IN const char *url_str:         String as a URL
00382  *      IN OUT void **Handle:           Pointer to buffer to store HTTP
00383  *                                      post handle
00384  *      IN OUT char **contentType:      Type of content
00385  *      OUT int *contentLength:         length of content
00386  *      OUT int *httpStatus:            HTTP status returned on receiving a
00387  *                                      response message
00388  *      IN int timeout:                 time out value
00389  *
00390  * Description:
00391  *      Makes the HTTP GET message, connects to the peer, 
00392  *      sends the HTTP GET request, gets the response and parses the 
00393  *      response.
00394  *
00395  * Return: int
00396  *      UPNP_E_SUCCESS          - On Success
00397  *      UPNP_E_INVALID_PARAM    - Invalid Paramters
00398  *      UPNP_E_OUTOF_MEMORY
00399  *      UPNP_E_SOCKET_ERROR
00400  *      UPNP_E_BAD_RESPONSE
00401  ************************************************************************/
00402 int http_OpenHttpGet(
00403         IN const char *url_str,
00404         IN OUT void **Handle,
00405         IN OUT char **contentType,
00406         OUT int *contentLength,
00407         OUT int *httpStatus,
00408         IN int timeout);
00409 
00410 
00411 /************************************************************************
00412  * Function: http_OpenHttpGetProxy
00413  *
00414  * Parameters:
00415  *      IN const char *url_str;         String as a URL
00416  *      IN const char *proxy_str;       String as a URL
00417  *      IN OUT void **Handle;           Pointer to buffer to store HTTP
00418  *                                      post handle
00419  *      IN OUT char **contentType;      Type of content
00420  *      OUT int *contentLength;         length of content
00421  *      OUT int *httpStatus;            HTTP status returned on receiving a
00422  *                                      response message
00423  *      IN int timeout:                 time out value
00424  *
00425  * Description:
00426  *      Makes the HTTP GET message, connects to the peer, 
00427  *      sends the HTTP GET request, gets the response and parses the response.
00428  *      If a proxy URL is defined then the connection is made there.
00429  *
00430  * Return: int
00431  *      UPNP_E_SUCCESS          - On Success
00432  *      UPNP_E_INVALID_PARAM    - Invalid Paramters
00433  *      UPNP_E_OUTOF_MEMORY
00434  *      UPNP_E_SOCKET_ERROR
00435  *      UPNP_E_BAD_RESPONSE
00436  ************************************************************************/
00437 int http_OpenHttpGetProxy(IN const char *url_str,
00438                                         IN const char *proxy_str,
00439                                         IN OUT void **Handle,
00440                                         IN OUT char **contentType,
00441                                         OUT int *contentLength,
00442                                         OUT int *httpStatus,
00443                                         IN int timeout);
00444 
00445 
00446 /************************************************************************
00447  * Function: http_SendStatusResponse
00448  *
00449  * Parameters:
00450  *      IN SOCKINFO *info;              Socket information object
00451  *      IN int http_status_code;        error code returned while making 
00452  *                                      or sending the response message
00453  *      IN int request_major_version;   request major version
00454  *      IN int request_minor_version;   request minor version
00455  *
00456  * Description:
00457  *      Generate a response message for the status query and send the
00458  *      status response.
00459  *
00460  * Return: int
00461  *      0 -- success
00462  *      UPNP_E_OUTOF_MEMORY
00463  *      UPNP_E_SOCKET_WRITE
00464  *      UPNP_E_TIMEDOUT
00465  ************************************************************************/
00466 int http_SendStatusResponse(
00467         IN SOCKINFO *info,
00468         IN int http_status_code,
00469         IN int request_major_version,
00470         IN int request_minor_version );
00471 
00472 
00473 /************************************************************************
00474  * Function: http_MakeMessage
00475  *
00476  * Parameters:
00477  *      INOUT membuffer* buf;           buffer with the contents of the 
00478  *                                      message
00479  *      IN int http_major_version;      HTTP major version
00480  *      IN int http_minor_version;      HTTP minor version
00481  *      IN const char* fmt;             Pattern format 
00482  *      ...;    
00483  *
00484  * Description:
00485  *      Generate an HTTP message based on the format that is specified
00486  *      in the input parameters.
00487  *
00488  * fmt types:
00489  *      'B':    arg = int status_code 
00490  *              appends content-length, content-type and HTML body
00491  *              for given code
00492  *      'b':    arg1 = const char* buf;
00493  *              arg2 = size_t buf_length memory ptr
00494  *      'C':    (no args) appends a HTTP CONNECTION: close header 
00495  *                      depending on major,minor version
00496  *      'c':    (no args) appends CRLF "\r\n"
00497  *      'D':    (no args) appends HTTP DATE: header
00498  *      'd':    arg = int number            // appends decimal number
00499  *      'G':    arg = range information     // add range header
00500  *      'h':    arg = off_t number          // appends off_t number
00501  *      'K':    (no args)                   // add chunky header
00502  *      'N':    arg1 = off_t content_length // content-length header
00503  *      'q':    arg1 = http_method_t        // request start line and HOST header
00504  *              arg2 = (uri_type *)
00505  *      'Q':    arg1 = http_method_t;       // start line of request
00506  *              arg2 = char* url; 
00507  *              arg3 = size_t url_length 
00508  *      'R':    arg = int status_code       // adds a response start line
00509  *      'S':    (no args) appends HTTP SERVER: header
00510  *      's':    arg = const char* C_string
00511  *      'T':    arg = char * content_type; format
00512  *              e.g: "text/html"; content-type header
00513  *      't':    arg = time_t * gmt_time     // appends time in RFC 1123 fmt
00514  *      'U':    (no args) appends HTTP USER-AGENT: header
00515  *      'X':    arg = const char useragent; "redsonic" HTTP X-User-Agent: useragent
00516  *
00517  * Return: int
00518  *      0 - On Success
00519  *      UPNP_E_OUTOF_MEMORY
00520  *      UPNP_E_INVALID_URL
00521  ************************************************************************/
00522 int http_MakeMessage(
00523         INOUT membuffer* buf, 
00524         IN int http_major_version,
00525         IN int http_minor_version,
00526         IN const char* fmt, ... );
00527 
00528 
00529 /************************************************************************
00530  * Function: http_CalcResponseVersion
00531  *
00532  * Parameters:
00533  *      IN int request_major_vers;      Request major version
00534  *      IN int request_minor_vers;      Request minor version
00535  *      OUT int* response_major_vers;   Response mojor version
00536  *      OUT int* response_minor_vers;   Response minor version
00537  *
00538  * Description:
00539  *      Calculate HTTP response versions based on the request versions.
00540  *
00541  * Return: void
00542  ************************************************************************/
00543 void http_CalcResponseVersion( 
00544         IN int request_major_vers,
00545         IN int request_minor_vers,
00546         OUT int* response_major_vers,
00547         OUT int* response_minor_vers );
00548 
00549 
00550 /************************************************************************
00551  * Function: http_OpenHttpGetEx
00552  *
00553  * Parameters:
00554  *      IN const char *url_str;         String as a URL
00555  *      IN OUT void **Handle;           Pointer to buffer to store HTTP
00556  *                                      post handle
00557  *      IN OUT char **contentType;      Type of content
00558  *      OUT int *contentLength;         length of content
00559  *      OUT int *httpStatus;            HTTP status returned on receiving a
00560  *                                      response message
00561  *      IN int timeout;                 time out value
00562  *
00563  * Description:
00564  *      Makes the HTTP GET message, connects to the peer, 
00565  *      sends the HTTP GET request, gets the response and parses the 
00566  *      response.
00567  *
00568  * Return: int
00569  *      UPNP_E_SUCCESS          - On Success
00570  *      UPNP_E_INVALID_PARAM    - Invalid Paramters
00571  *      UPNP_E_OUTOF_MEMORY
00572  *      UPNP_E_SOCKET_ERROR
00573  *      UPNP_E_BAD_RESPONSE
00574  ************************************************************************/
00575 int http_OpenHttpGetEx(IN const char *url_str,
00576                      IN OUT void **Handle,
00577                      IN OUT char **contentType,
00578                      OUT int *contentLength,
00579                      OUT int *httpStatus,
00580                          IN int lowRange,
00581                          IN int highRange,
00582                      IN int timeout);
00583 
00584 
00585 /************************************************************************
00586  * Function: get_sdk_info
00587  *
00588  * Parameters:
00589  *      OUT char *info; buffer to store the operating system information
00590  *
00591  * Description:
00592  *      Returns the server information for the operating system
00593  *
00594  * Return:
00595  *      UPNP_INLINE void
00596  ************************************************************************/
00597 void get_sdk_info( OUT char *info );
00598 
00599 #ifdef __cplusplus
00600 }       // #extern "C"
00601 #endif
00602 
00603 
00604 #endif // GENLIB_NET_HTTP_HTTPREADWRITE_H
00605