libUPnP  1.6.17
httpreadwrite.h
1 /*******************************************************************************
2  *
3  * Copyright (c) 2000-2003 Intel Corporation
4  * All rights reserved.
5  * Copyright (c) 2012 France Telecom All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions are met:
9  *
10  * - Redistributions of source code must retain the above copyright notice,
11  * this list of conditions and the following disclaimer.
12  * - Redistributions in binary form must reproduce the above copyright notice,
13  * this list of conditions and the following disclaimer in the documentation
14  * and/or other materials provided with the distribution.
15  * - Neither name of Intel Corporation nor the names of its contributors
16  * may be used to endorse or promote products derived from this software
17  * without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR
23  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
26  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
27  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
28  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30  *
31  ******************************************************************************/
32 
33 #ifndef GENLIB_NET_HTTP_HTTPREADWRITE_H
34 #define GENLIB_NET_HTTP_HTTPREADWRITE_H
35 
36 /*
37  * \file
38  */
39 
40 #include "config.h"
41 #include "upnputil.h"
42 #include "sock.h"
43 #include "httpparser.h"
44 
46 #define HTTP_DEFAULT_TIMEOUT 30
47 
48 #ifdef __cplusplus
49 extern "C" {
50 #endif
51 
52 int http_CancelHttpGet(IN void *Handle);
53 
61 int http_FixUrl(
63  uri_type *url,
65  uri_type *fixed_url);
66 
74 int http_FixStrUrl(
76  const char *urlstr,
78  size_t urlstrlen,
80  uri_type *fixed_url);
81 
90 SOCKET http_Connect(
92  uri_type *destination_url,
94  uri_type *url);
95 
96 
97 /************************************************************************
98  * Function: http_RecvMessage
99  *
100  * Parameters:
101  * IN SOCKINFO *info; Socket information object
102  * OUT http_parser_t* parser; HTTP parser object
103  * IN http_method_t request_method; HTTP request method
104  * IN OUT int* timeout_secs; time out
105  * OUT int* http_error_code; HTTP error code returned
106  *
107  * Description:
108  * Get the data on the socket and take actions based on the read data
109  * to modify the parser objects buffer. If an error is reported while
110  * parsing the data, the error code is passed in the http_errr_code
111  * parameter
112  *
113  * Returns:
114  * UPNP_E_BAD_HTTPMSG
115  * UPNP_E_SUCCESS
116  ************************************************************************/
117 int http_RecvMessage( IN SOCKINFO *info, OUT http_parser_t* parser,
118  IN http_method_t request_method,
119  IN OUT int* timeout_secs,
120  OUT int* http_error_code );
121 
122 
145 int http_SendMessage(
146  /* [in] Socket information object. */
147  SOCKINFO *info,
148  /* [in,out] Time out value. */
149  int* timeout_secs,
150  /* [in] Pattern format to take actions upon. */
151  const char* fmt,
152  /* [in] Variable parameter list. */
153  ...);
154 
155 /************************************************************************
156  * Function: http_RequestAndResponse
157  *
158  * Parameters:
159  * IN uri_type* destination; Destination URI object which contains
160  * remote IP address among other elements
161  * IN const char* request; Request to be sent
162  * IN size_t request_length; Length of the request
163  * IN http_method_t req_method; HTTP Request method
164  * IN int timeout_secs; time out value
165  * OUT http_parser_t* response; Parser object to receive the repsonse
166  *
167  * Description:
168  * Initiates socket, connects to the destination, sends a
169  * request and waits for the response from the remote end
170  *
171  * Returns:
172  * UPNP_E_SOCKET_ERROR
173  * UPNP_E_SOCKET_CONNECT
174  * Error Codes returned by http_SendMessage
175  * Error Codes returned by http_RecvMessage
176  ************************************************************************/
177 int http_RequestAndResponse(
178  IN uri_type* destination,
179  IN const char* request,
180  IN size_t request_length,
181  IN http_method_t req_method,
182  IN int timeout_secs,
183  OUT http_parser_t* response );
184 
185 
186 /************************************************************************
187  * return codes:
188  * 0 -- success
189  * UPNP_E_OUTOF_MEMORY
190  * UPNP_E_TIMEDOUT
191  * UPNP_E_BAD_REQUEST
192  * UPNP_E_BAD_RESPONSE
193  * UPNP_E_INVALID_URL
194  * UPNP_E_SOCKET_READ
195  * UPNP_E_SOCKET_WRITE
196  ************************************************************************/
197 
198 
199 /************************************************************************
200  * Function: http_Download
201  *
202  * Parameters:
203  * IN const char* url_str; String as a URL
204  * IN int timeout_secs; time out value
205  * OUT char** document; buffer to store the document extracted
206  * from the donloaded message.
207  * OUT size_t* doc_length; length of the extracted document
208  * OUT char* content_type; Type of content
209  *
210  * Description:
211  * Download the document message and extract the document
212  * from the message.
213  *
214  * Return: int
215  * UPNP_E_SUCCESS
216  * UPNP_E_INVALID_URL
217  ************************************************************************/
218 int http_Download(
219  IN const char* url,
220  IN int timeout_secs,
221  OUT char** document,
222  OUT size_t *doc_length,
223  OUT char* content_type );
224 
225 
226 /************************************************************************
227  * Function: http_WriteHttpPost
228  *
229  * Parameters:
230  * IN void *Handle: Handle to the http post object
231  * IN char *buf: Buffer to send to peer, if format used
232  * is not UPNP_USING_CHUNKED,
233  * IN size_t *size: Size of the data to be sent.
234  * IN int timeout: time out value
235  *
236  * Description:
237  * Formats data if format used is UPNP_USING_CHUNKED.
238  * Writes data on the socket connected to the peer.
239  *
240  * Return: int
241  * UPNP_E_SUCCESS - On Success
242  * UPNP_E_INVALID_PARAM - Invalid Parameter
243  * -1 - On Socket Error.
244  ************************************************************************/
245 int http_WriteHttpPost(IN void *Handle,
246  IN char *buf,
247  IN size_t *size,
248  IN int timeout);
249 
250 
251 /************************************************************************
252  * Function: http_CloseHttpPost
253  *
254  * Parameters:
255  * IN void *Handle; Handle to the http post object
256  * IN OUT int *httpStatus; HTTP status returned on receiving a
257  * response message
258  * IN int timeout; time out value
259  *
260  * Description:
261  * Sends remaining data if using UPNP_USING_CHUNKED
262  * format. Receives any more messages. Destroys socket and any socket
263  * associated memory. Frees handle associated with the HTTP POST msg.
264  *
265  * Return: int
266  * UPNP_E_SUCCESS - On success
267  * UPNP_E_INVALID_PARAM - Invalid Parameter
268  ************************************************************************/
269 int http_CloseHttpPost(IN void *Handle,
270  IN OUT int *httpStatus,
271  IN int timeout);
272 
273 
274 /************************************************************************
275  * Function: http_OpenHttpPost
276  *
277  * Parameters:
278  * IN const char *url_str; String as a URL
279  * IN OUT void **Handle; Pointer to buffer to store HTTP
280  * post handle
281  * IN const char *contentType; Type of content
282  * IN int contentLength; length of content
283  * IN int timeout; time out value
284  *
285  * Description:
286  * Makes the HTTP POST message, connects to the peer,
287  * sends the HTTP POST request. Adds the post handle to buffer of
288  * such handles
289  *
290  * Return : int;
291  * UPNP_E_SUCCESS - On success
292  * UPNP_E_INVALID_PARAM - Invalid Parameter
293  * UPNP_E_OUTOF_MEMORY
294  * UPNP_E_SOCKET_ERROR
295  * UPNP_E_SOCKET_CONNECT
296  ************************************************************************/
297 int http_OpenHttpPost(IN const char *url_str,
298  IN OUT void **Handle,
299  IN const char *contentType,
300  IN int contentLength,
301  IN int timeout);
302 
303 
304 /************************************************************************
305  * Function: http_ReadHttpGet
306  *
307  * Parameters:
308  * IN void *Handle; Handle to the HTTP get object
309  * IN OUT char *buf; Buffer to get the read and parsed data
310  * IN OUT size_t *size; Size of the buffer passed
311  * IN int timeout; time out value
312  *
313  * Description:
314  * Parses already existing data, then gets new data.
315  * Parses and extracts information from the new data.
316  *
317  * Return: int
318  * UPNP_E_SUCCESS - On success
319  * UPNP_E_INVALID_PARAM - Invalid Parameter
320  * UPNP_E_BAD_RESPONSE
321  * UPNP_E_BAD_HTTPMSG
322  * UPNP_E_CANCELED
323  ************************************************************************/
324 int http_ReadHttpGet(
325  IN void *Handle,
326  IN OUT char *buf,
327  IN OUT size_t *size,
328  IN int timeout);
329 
330 
331 /************************************************************************
332  * Function: http_HttpGetProgress
333  *
334  * Parameters:
335  * IN void *Handle; Handle to the HTTP get object
336  * OUT size_t *length; Buffer to get the read and parsed data
337  * OUT size_t *total; Size of tge buffer passed
338  *
339  * Description:
340  * Extracts information from the Handle to the HTTP get object.
341  *
342  * Return: int
343  * UPNP_E_SUCCESS - On Sucess
344  * UPNP_E_INVALID_PARAM - Invalid Parameter
345  ************************************************************************/
346 int http_HttpGetProgress(
347  IN void *Handle,
348  OUT size_t *length,
349  OUT size_t *total);
350 
351 /************************************************************************
352  * Function: http_CloseHttpGet
353  *
354  * Parameters:
355  * IN void *Handle; Handle to HTTP get object
356  *
357  * Description:
358  * Clears the handle allocated for the HTTP GET operation
359  * Clears socket states and memory allocated for socket operations.
360  *
361  * Return: int
362  * UPNP_E_SUCCESS - On Success
363  * UPNP_E_INVALID_PARAM - Invalid Parameter
364  ************************************************************************/
365 int http_CloseHttpGet(IN void *Handle);
366 
380 int http_OpenHttpGet(
381  /* [in] String as a URL. */
382  const char *url_str,
383  /* [in,out] Pointer to buffer to store HTTP post handle. */
384  void **Handle,
385  /* [in,out] Type of content. */
386  char **contentType,
387  /* [out] length of content. */
388  int *contentLength,
389  /* [out] HTTP status returned on receiving a response message. */
390  int *httpStatus,
391  /* [in] time out value. */
392  int timeout);
393 
408  /* [in] String as a URL. */
409  const char *url_str,
410  /* [in] String as a URL. */
411  const char *proxy_str,
412  /* [in,out] Pointer to buffer to store HTTP post handle. */
413  void **Handle,
414  /* [in,out] Type of content. */
415  char **contentType,
416  /* [out] length of content. */
417  int *contentLength,
418  /* [out] HTTP status returned on receiving a response message. */
419  int *httpStatus,
420  /* [in] time out value. */
421  int timeout);
422 
423 
424 /************************************************************************
425  * Function: http_SendStatusResponse
426  *
427  * Parameters:
428  * IN SOCKINFO *info; Socket information object
429  * IN int http_status_code; error code returned while making
430  * or sending the response message
431  * IN int request_major_version; request major version
432  * IN int request_minor_version; request minor version
433  *
434  * Description:
435  * Generate a response message for the status query and send the
436  * status response.
437  *
438  * Return: int
439  * 0 -- success
440  * UPNP_E_OUTOF_MEMORY
441  * UPNP_E_SOCKET_WRITE
442  * UPNP_E_TIMEDOUT
443  ************************************************************************/
444 int http_SendStatusResponse(
445  IN SOCKINFO *info,
446  IN int http_status_code,
447  IN int request_major_version,
448  IN int request_minor_version );
449 
488 int http_MakeMessage(
489  /* [in,out] Buffer with the contents of the message. */
490  INOUT membuffer* buf,
491  /* [in] HTTP major version. */
492  IN int http_major_version,
493  /* [in] HTTP minor version. */
494  IN int http_minor_version,
495  /* [in] Pattern format. */
496  IN const char* fmt,
497  /* [in] Format arguments. */
498  ... );
499 
500 
501 /************************************************************************
502  * Function: http_CalcResponseVersion
503  *
504  * Parameters:
505  * IN int request_major_vers; Request major version
506  * IN int request_minor_vers; Request minor version
507  * OUT int* response_major_vers; Response mojor version
508  * OUT int* response_minor_vers; Response minor version
509  *
510  * Description:
511  * Calculate HTTP response versions based on the request versions.
512  *
513  * Return: void
514  ************************************************************************/
515 void http_CalcResponseVersion(
516  IN int request_major_vers,
517  IN int request_minor_vers,
518  OUT int* response_major_vers,
519  OUT int* response_minor_vers );
520 
521 
522 /************************************************************************
523  * Function: http_OpenHttpGetEx
524  *
525  * Parameters:
526  * IN const char *url_str; String as a URL
527  * IN OUT void **Handle; Pointer to buffer to store HTTP
528  * post handle
529  * IN OUT char **contentType; Type of content
530  * OUT int *contentLength; length of content
531  * OUT int *httpStatus; HTTP status returned on receiving a
532  * response message
533  * IN int timeout; time out value
534  *
535  * Description:
536  * Makes the HTTP GET message, connects to the peer,
537  * sends the HTTP GET request, gets the response and parses the
538  * response.
539  *
540  * Return: int
541  * UPNP_E_SUCCESS - On Success
542  * UPNP_E_INVALID_PARAM - Invalid Paramters
543  * UPNP_E_OUTOF_MEMORY
544  * UPNP_E_SOCKET_ERROR
545  * UPNP_E_BAD_RESPONSE
546  ************************************************************************/
547 int http_OpenHttpGetEx(IN const char *url_str,
548  IN OUT void **Handle,
549  IN OUT char **contentType,
550  OUT int *contentLength,
551  OUT int *httpStatus,
552  IN int lowRange,
553  IN int highRange,
554  IN int timeout);
555 
556 
557 /************************************************************************
558  * Function: get_sdk_info
559  *
560  * Parameters:
561  * OUT char *info; buffer to store the operating system information
562  * IN size_t infoSize; size of buffer
563  *
564  * Description:
565  * Returns the server information for the operating system
566  *
567  * Return:
568  * UPNP_INLINE void
569  ************************************************************************/
570 void get_sdk_info( OUT char *info, IN size_t infoSize );
571 
572 #ifdef __cplusplus
573 } /* #extern "C" */
574 #endif
575 
576 
577 #endif /* GENLIB_NET_HTTP_HTTPREADWRITE_H */
578