libUPnP  1.6.17
httpreadwrite.h
00001 /*******************************************************************************
00002  *
00003  * Copyright (c) 2000-2003 Intel Corporation
00004  * All rights reserved.
00005  * Copyright (c) 2012 France Telecom All rights reserved.
00006  *
00007  * Redistribution and use in source and binary forms, with or without
00008  * modification, are permitted provided that the following conditions are met:
00009  *
00010  * - Redistributions of source code must retain the above copyright notice,
00011  * this list of conditions and the following disclaimer.
00012  * - Redistributions in binary form must reproduce the above copyright notice,
00013  * this list of conditions and the following disclaimer in the documentation
00014  * and/or other materials provided with the distribution.
00015  * - Neither name of Intel Corporation nor the names of its contributors
00016  * may be used to endorse or promote products derived from this software
00017  * without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00020  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00021  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00022  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR
00023  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00024  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00025  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00026  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
00027  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00028  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00029  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00030  *
00031  ******************************************************************************/
00032 
00033 #ifndef GENLIB_NET_HTTP_HTTPREADWRITE_H
00034 #define GENLIB_NET_HTTP_HTTPREADWRITE_H
00035 
00036 /*
00037  * \file
00038  */
00039 
00040 #include "config.h"
00041 #include "upnputil.h"
00042 #include "sock.h"
00043 #include "httpparser.h"
00044 
00046 #define HTTP_DEFAULT_TIMEOUT    30
00047 
00048 #ifdef __cplusplus
00049 extern "C" {
00050 #endif
00051 
00052 int http_CancelHttpGet(IN void *Handle);
00053 
00061 int http_FixUrl(
00063         uri_type *url,
00065         uri_type *fixed_url);
00066 
00074 int http_FixStrUrl(
00076         const char *urlstr,
00078         size_t urlstrlen,
00080         uri_type *fixed_url);
00081 
00090 SOCKET http_Connect(
00092         uri_type *destination_url,
00094         uri_type *url);
00095 
00096 
00097 /************************************************************************
00098  * Function: http_RecvMessage
00099  *
00100  * Parameters:
00101  *      IN SOCKINFO *info;                      Socket information object
00102  *      OUT http_parser_t* parser;              HTTP parser object
00103  *      IN http_method_t request_method;        HTTP request method
00104  *      IN OUT int* timeout_secs;               time out
00105  *      OUT int* http_error_code;               HTTP error code returned
00106  *
00107  * Description:
00108  *      Get the data on the socket and take actions based on the read data
00109  *      to modify the parser objects buffer. If an error is reported while
00110  *      parsing the data, the error code is passed in the http_errr_code
00111  *      parameter
00112  *
00113  * Returns:
00114  *       UPNP_E_BAD_HTTPMSG
00115  *       UPNP_E_SUCCESS
00116  ************************************************************************/
00117 int http_RecvMessage( IN SOCKINFO *info, OUT http_parser_t* parser,
00118                 IN http_method_t request_method, 
00119                 IN OUT int* timeout_secs,
00120                 OUT int* http_error_code );
00121 
00122 
00145 int http_SendMessage(
00146         /* [in] Socket information object. */
00147         SOCKINFO *info,
00148         /* [in,out] Time out value. */
00149         int* timeout_secs, 
00150         /* [in] Pattern format to take actions upon. */
00151         const char* fmt,
00152         /* [in] Variable parameter list. */
00153         ...);
00154 
00155 /************************************************************************
00156  * Function: http_RequestAndResponse
00157  *
00158  * Parameters:
00159  *      IN uri_type* destination;       Destination URI object which contains
00160  *                                      remote IP address among other elements
00161  *      IN const char* request;         Request to be sent
00162  *      IN size_t request_length;       Length of the request
00163  *      IN http_method_t req_method;    HTTP Request method
00164  *      IN int timeout_secs;            time out value
00165  *      OUT http_parser_t* response;    Parser object to receive the repsonse
00166  *
00167  * Description:
00168  *      Initiates socket, connects to the destination, sends a
00169  *      request and waits for the response from the remote end
00170  *
00171  * Returns:
00172  *      UPNP_E_SOCKET_ERROR
00173  *      UPNP_E_SOCKET_CONNECT
00174  *      Error Codes returned by http_SendMessage
00175  *      Error Codes returned by http_RecvMessage
00176  ************************************************************************/
00177 int http_RequestAndResponse(
00178         IN uri_type* destination,
00179         IN const char* request,
00180         IN size_t request_length,
00181         IN http_method_t req_method,
00182         IN int timeout_secs, 
00183         OUT http_parser_t* response );
00184 
00185 
00186 /************************************************************************
00187  * return codes:
00188  *      0 -- success
00189  *      UPNP_E_OUTOF_MEMORY
00190  *      UPNP_E_TIMEDOUT
00191  *      UPNP_E_BAD_REQUEST
00192  *      UPNP_E_BAD_RESPONSE
00193  *      UPNP_E_INVALID_URL
00194  *      UPNP_E_SOCKET_READ
00195  *      UPNP_E_SOCKET_WRITE
00196  ************************************************************************/
00197 
00198 
00199 /************************************************************************
00200  * Function: http_Download
00201  *
00202  * Parameters:
00203  *      IN const char* url_str; String as a URL
00204  *      IN int timeout_secs;    time out value
00205  *      OUT char** document;    buffer to store the document extracted
00206  *                              from the donloaded message.
00207  *      OUT size_t* doc_length; length of the extracted document
00208  *      OUT char* content_type; Type of content
00209  *
00210  * Description:
00211  *      Download the document message and extract the document 
00212  *      from the message.
00213  *
00214  * Return: int
00215  *      UPNP_E_SUCCESS
00216  *      UPNP_E_INVALID_URL
00217  ************************************************************************/
00218 int http_Download(
00219         IN const char* url, 
00220         IN int timeout_secs,
00221         OUT char** document,
00222         OUT size_t *doc_length,
00223         OUT char* content_type );
00224 
00225 
00226 /************************************************************************
00227  * Function: http_WriteHttpPost
00228  *
00229  * Parameters:
00230  *      IN void *Handle:        Handle to the http post object
00231  *      IN char *buf:           Buffer to send to peer, if format used
00232  *                              is not UPNP_USING_CHUNKED, 
00233  *      IN size_t *size:        Size of the data to be sent.
00234  *      IN int timeout:         time out value
00235  *
00236  * Description:
00237  *      Formats data if format used is UPNP_USING_CHUNKED.
00238  *      Writes data on the socket connected to the peer.
00239  *
00240  * Return: int
00241  *      UPNP_E_SUCCESS - On Success
00242  *      UPNP_E_INVALID_PARAM - Invalid Parameter
00243  *      -1 - On Socket Error.
00244  ************************************************************************/
00245 int http_WriteHttpPost(IN void *Handle,
00246                        IN char *buf,
00247                        IN size_t *size,
00248                        IN int timeout);
00249 
00250 
00251 /************************************************************************
00252  * Function: http_CloseHttpPost
00253  *
00254  * Parameters:
00255  *      IN void *Handle;        Handle to the http post object
00256  *      IN OUT int *httpStatus; HTTP status returned on receiving a
00257  *                              response message
00258  *      IN int timeout;         time out value
00259  *
00260  * Description:
00261  *      Sends remaining data if using  UPNP_USING_CHUNKED 
00262  *      format. Receives any more messages. Destroys socket and any socket
00263  *      associated memory. Frees handle associated with the HTTP POST msg.
00264  *
00265  * Return: int
00266  *      UPNP_E_SUCCESS          - On success
00267  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
00268  ************************************************************************/
00269 int http_CloseHttpPost(IN void *Handle, 
00270                        IN OUT int *httpStatus,
00271                        IN int timeout);
00272 
00273 
00274 /************************************************************************
00275  * Function: http_OpenHttpPost
00276  *
00277  * Parameters:
00278  *      IN const char *url_str;         String as a URL 
00279  *      IN OUT void **Handle;           Pointer to buffer to store HTTP
00280  *                                      post handle
00281  *      IN const char *contentType;     Type of content
00282  *      IN int contentLength;           length of content
00283  *      IN int timeout;                 time out value
00284  *
00285  * Description:
00286  *      Makes the HTTP POST message, connects to the peer, 
00287  *      sends the HTTP POST request. Adds the post handle to buffer of 
00288  *      such handles
00289  *
00290  * Return : int;
00291  *      UPNP_E_SUCCESS          - On success
00292  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
00293  *      UPNP_E_OUTOF_MEMORY
00294  *      UPNP_E_SOCKET_ERROR
00295  *      UPNP_E_SOCKET_CONNECT
00296  ************************************************************************/
00297 int http_OpenHttpPost(IN const char *url_str,
00298                       IN OUT void **Handle,
00299                       IN const char *contentType,
00300                       IN int contentLength,
00301                       IN int timeout);
00302 
00303 
00304 /************************************************************************
00305  * Function: http_ReadHttpGet
00306  *
00307  * Parameters:
00308  *      IN void *Handle;        Handle to the HTTP get object
00309  *      IN OUT char *buf;       Buffer to get the read and parsed data
00310  *      IN OUT size_t *size;    Size of the buffer passed
00311  *      IN int timeout;         time out value
00312  *
00313  * Description:
00314  *      Parses already existing data, then gets new data.
00315  *      Parses and extracts information from the new data.
00316  *
00317  * Return: int
00318  *      UPNP_E_SUCCESS          - On success
00319  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
00320  *      UPNP_E_BAD_RESPONSE
00321  *      UPNP_E_BAD_HTTPMSG
00322  *      UPNP_E_CANCELED
00323  ************************************************************************/
00324 int http_ReadHttpGet(
00325         IN void *Handle,
00326         IN OUT char *buf,
00327         IN OUT size_t *size,
00328         IN int timeout);
00329 
00330 
00331 /************************************************************************
00332  * Function: http_HttpGetProgress
00333  *
00334  * Parameters:
00335  *      IN void *Handle;        Handle to the HTTP get object
00336  *      OUT size_t *length;     Buffer to get the read and parsed data
00337  *      OUT size_t *total;      Size of tge buffer passed
00338  *
00339  * Description:
00340  *      Extracts information from the Handle to the HTTP get object.
00341  *
00342  * Return: int
00343  *      UPNP_E_SUCCESS          - On Sucess
00344  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
00345  ************************************************************************/
00346 int http_HttpGetProgress(
00347         IN void *Handle,
00348         OUT size_t *length,
00349         OUT size_t *total);
00350 
00351 /************************************************************************
00352  * Function: http_CloseHttpGet
00353  *
00354  * Parameters:
00355  *      IN void *Handle;        Handle to HTTP get object
00356  *
00357  * Description:
00358  *      Clears the handle allocated for the HTTP GET operation
00359  *      Clears socket states and memory allocated for socket operations. 
00360  *
00361  * Return: int
00362  *      UPNP_E_SUCCESS          - On Success
00363  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
00364  ************************************************************************/
00365 int http_CloseHttpGet(IN void *Handle);
00366 
00380 int http_OpenHttpGet(
00381         /* [in] String as a URL. */
00382         const char *url_str,
00383         /* [in,out] Pointer to buffer to store HTTP post handle. */
00384         void **Handle,
00385         /* [in,out] Type of content. */
00386         char **contentType,
00387         /* [out] length of content. */
00388         int *contentLength,
00389         /* [out] HTTP status returned on receiving a response message. */
00390         int *httpStatus,
00391         /* [in] time out value. */
00392         int timeout);
00393 
00407 int http_OpenHttpGetProxy(
00408         /* [in] String as a URL. */
00409         const char *url_str,
00410         /* [in] String as a URL. */
00411         const char *proxy_str,
00412         /* [in,out] Pointer to buffer to store HTTP post handle. */
00413         void **Handle,
00414         /* [in,out] Type of content. */
00415         char **contentType,
00416         /* [out] length of content. */
00417         int *contentLength,
00418         /* [out] HTTP status returned on receiving a response message. */
00419         int *httpStatus,
00420         /* [in] time out value. */
00421         int timeout);
00422 
00423 
00424 /************************************************************************
00425  * Function: http_SendStatusResponse
00426  *
00427  * Parameters:
00428  *      IN SOCKINFO *info;              Socket information object
00429  *      IN int http_status_code;        error code returned while making 
00430  *                                      or sending the response message
00431  *      IN int request_major_version;   request major version
00432  *      IN int request_minor_version;   request minor version
00433  *
00434  * Description:
00435  *      Generate a response message for the status query and send the
00436  *      status response.
00437  *
00438  * Return: int
00439  *      0 -- success
00440  *      UPNP_E_OUTOF_MEMORY
00441  *      UPNP_E_SOCKET_WRITE
00442  *      UPNP_E_TIMEDOUT
00443  ************************************************************************/
00444 int http_SendStatusResponse(
00445         IN SOCKINFO *info,
00446         IN int http_status_code,
00447         IN int request_major_version,
00448         IN int request_minor_version );
00449 
00488 int http_MakeMessage(
00489         /* [in,out] Buffer with the contents of the message. */
00490         INOUT membuffer* buf, 
00491         /* [in] HTTP major version. */
00492         IN int http_major_version,
00493         /* [in] HTTP minor version. */
00494         IN int http_minor_version,
00495         /* [in] Pattern format. */
00496         IN const char* fmt,
00497         /* [in] Format arguments. */
00498         ... );
00499 
00500 
00501 /************************************************************************
00502  * Function: http_CalcResponseVersion
00503  *
00504  * Parameters:
00505  *      IN int request_major_vers;      Request major version
00506  *      IN int request_minor_vers;      Request minor version
00507  *      OUT int* response_major_vers;   Response mojor version
00508  *      OUT int* response_minor_vers;   Response minor version
00509  *
00510  * Description:
00511  *      Calculate HTTP response versions based on the request versions.
00512  *
00513  * Return: void
00514  ************************************************************************/
00515 void http_CalcResponseVersion( 
00516         IN int request_major_vers,
00517         IN int request_minor_vers,
00518         OUT int* response_major_vers,
00519         OUT int* response_minor_vers );
00520 
00521 
00522 /************************************************************************
00523  * Function: http_OpenHttpGetEx
00524  *
00525  * Parameters:
00526  *      IN const char *url_str;         String as a URL
00527  *      IN OUT void **Handle;           Pointer to buffer to store HTTP
00528  *                                      post handle
00529  *      IN OUT char **contentType;      Type of content
00530  *      OUT int *contentLength;         length of content
00531  *      OUT int *httpStatus;            HTTP status returned on receiving a
00532  *                                      response message
00533  *      IN int timeout;                 time out value
00534  *
00535  * Description:
00536  *      Makes the HTTP GET message, connects to the peer, 
00537  *      sends the HTTP GET request, gets the response and parses the 
00538  *      response.
00539  *
00540  * Return: int
00541  *      UPNP_E_SUCCESS          - On Success
00542  *      UPNP_E_INVALID_PARAM    - Invalid Paramters
00543  *      UPNP_E_OUTOF_MEMORY
00544  *      UPNP_E_SOCKET_ERROR
00545  *      UPNP_E_BAD_RESPONSE
00546  ************************************************************************/
00547 int http_OpenHttpGetEx(IN const char *url_str,
00548                      IN OUT void **Handle,
00549                      IN OUT char **contentType,
00550                      OUT int *contentLength,
00551                      OUT int *httpStatus,
00552                          IN int lowRange,
00553                          IN int highRange,
00554                      IN int timeout);
00555 
00556 
00557 /************************************************************************
00558  * Function: get_sdk_info
00559  *
00560  * Parameters:
00561  *      OUT char *info; buffer to store the operating system information
00562  *      IN size_t infoSize; size of buffer
00563  *
00564  * Description:
00565  *      Returns the server information for the operating system
00566  *
00567  * Return:
00568  *      UPNP_INLINE void
00569  ************************************************************************/
00570 void get_sdk_info( OUT char *info, IN size_t infoSize );
00571 
00572 #ifdef __cplusplus
00573 }       /* #extern "C" */
00574 #endif
00575 
00576 
00577 #endif /* GENLIB_NET_HTTP_HTTPREADWRITE_H */
00578