Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
http_client.h
Go to the documentation of this file.
1 /**
2  * @file
3  * HTTP client
4  */
5 
6 /*
7  * Copyright (c) 2018 Simon Goldschmidt <goldsimon@gmx.de>
8  * All rights reserved.
9  *
10  * Redistribution and use in source and binary forms, with or without modification,
11  * are permitted provided that the following conditions are met:
12  *
13  * 1. Redistributions of source code must retain the above copyright notice,
14  * this list of conditions and the following disclaimer.
15  * 2. Redistributions in binary form must reproduce the above copyright notice,
16  * this list of conditions and the following disclaimer in the documentation
17  * and/or other materials provided with the distribution.
18  * 3. The name of the author may not be used to endorse or promote products
19  * derived from this software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
22  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
23  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
24  * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
26  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
29  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
30  * OF SUCH DAMAGE.
31  *
32  * This file is part of the lwIP TCP/IP stack.
33  *
34  * Author: Simon Goldschmidt <goldsimon@gmx.de>
35  *
36  */
37 
38 #ifndef LWIP_HDR_APPS_HTTP_CLIENT_H
39 #define LWIP_HDR_APPS_HTTP_CLIENT_H
40 
41 #include "lwip/opt.h"
42 #include "lwip/ip_addr.h"
43 #include "lwip/err.h"
44 #include "lwip/altcp.h"
45 #include "lwip/prot/iana.h"
46 #include "lwip/pbuf.h"
47 
48 #if LWIP_TCP && LWIP_CALLBACK_API
49 
50 #ifdef __cplusplus
51 extern "C" {
52 #endif
53 
54 /**
55  * @ingroup httpc
56  * HTTPC_HAVE_FILE_IO: define this to 1 to have functions dowloading directly
57  * to disk via fopen/fwrite.
58  * These functions are example implementations of the interface only.
59  */
60 #ifndef LWIP_HTTPC_HAVE_FILE_IO
61 #define LWIP_HTTPC_HAVE_FILE_IO 0
62 #endif
63 
64 /**
65  * @ingroup httpc
66  * The default TCP port used for HTTP
67  */
68 #define HTTP_DEFAULT_PORT LWIP_IANA_PORT_HTTP
69 
70 /**
71  * @ingroup httpc
72  * HTTP client result codes
73  */
74 typedef enum ehttpc_result {
75  /** File successfully received */
76  HTTPC_RESULT_OK = 0,
77  /** Unknown error */
78  HTTPC_RESULT_ERR_UNKNOWN = 1,
79  /** Connection to server failed */
80  HTTPC_RESULT_ERR_CONNECT = 2,
81  /** Failed to resolve server hostname */
82  HTTPC_RESULT_ERR_HOSTNAME = 3,
83  /** Connection unexpectedly closed by remote server */
84  HTTPC_RESULT_ERR_CLOSED = 4,
85  /** Connection timed out (server didn't respond in time) */
86  HTTPC_RESULT_ERR_TIMEOUT = 5,
87  /** Server responded with an error code */
88  HTTPC_RESULT_ERR_SVR_RESP = 6,
89  /** Local memory error */
90  HTTPC_RESULT_ERR_MEM = 7,
91  /** Local abort */
92  HTTPC_RESULT_LOCAL_ABORT = 8,
93  /** Content length mismatch */
94  HTTPC_RESULT_ERR_CONTENT_LEN = 9
95 } httpc_result_t;
96 
97 typedef struct _httpc_state httpc_state_t;
98 
99 /**
100  * @ingroup httpc
101  * Prototype of a http client callback function
102  *
103  * @param arg argument specified when initiating the request
104  * @param httpc_result result of the http transfer (see enum httpc_result_t)
105  * @param rx_content_len number of bytes received (without headers)
106  * @param srv_res this contains the http status code received (if any)
107  * @param err an error returned by internal lwip functions, can help to specify
108  * the source of the error but must not necessarily be != ERR_OK
109  */
110 typedef void (*httpc_result_fn)(void *arg, httpc_result_t httpc_result, u32_t rx_content_len, u32_t srv_res, err_t err);
111 
112 /**
113  * @ingroup httpc
114  * Prototype of http client callback: called when the headers are received
115  *
116  * @param connection http client connection
117  * @param arg argument specified when initiating the request
118  * @param hdr header pbuf(s) (may contain data also)
119  * @param hdr_len length of the heders in 'hdr'
120  * @param content_len content length as received in the headers (-1 if not received)
121  * @return if != ERR_OK is returned, the connection is aborted
122  */
123 typedef err_t (*httpc_headers_done_fn)(httpc_state_t *connection, void *arg, struct pbuf *hdr, u16_t hdr_len, u32_t content_len);
124 
125 typedef struct _httpc_connection {
126  ip_addr_t proxy_addr;
127  u16_t proxy_port;
128  u8_t use_proxy;
129  /* @todo: add username:pass? */
130 
131 #if LWIP_ALTCP
132  altcp_allocator_t *altcp_allocator;
133 #endif
134 
135  /* this callback is called when the transfer is finished (or aborted) */
136  httpc_result_fn result_fn;
137  /* this callback is called after receiving the http headers
138  It can abort the connection by returning != ERR_OK */
139  httpc_headers_done_fn headers_done_fn;
140 } httpc_connection_t;
141 
142 err_t httpc_get_file(const ip_addr_t* server_addr, u16_t port, const char* uri, const httpc_connection_t *settings,
143  altcp_recv_fn recv_fn, void* callback_arg, httpc_state_t **connection);
144 err_t httpc_get_file_dns(const char* server_name, u16_t port, const char* uri, const httpc_connection_t *settings,
145  altcp_recv_fn recv_fn, void* callback_arg, httpc_state_t **connection);
146 
147 #if LWIP_HTTPC_HAVE_FILE_IO
148 err_t httpc_get_file_to_disk(const ip_addr_t* server_addr, u16_t port, const char* uri, const httpc_connection_t *settings,
149  void* callback_arg, const char* local_file_name, httpc_state_t **connection);
150 err_t httpc_get_file_dns_to_disk(const char* server_name, u16_t port, const char* uri, const httpc_connection_t *settings,
151  void* callback_arg, const char* local_file_name, httpc_state_t **connection);
152 #endif /* LWIP_HTTPC_HAVE_FILE_IO */
153 
154 #ifdef __cplusplus
155 }
156 #endif
157 
158 #endif /* LWIP_TCP && LWIP_CALLBACK_API */
159 
160 #endif /* LWIP_HDR_APPS_HTTP_CLIENT_H */
opt.h
lwIP Options Configuration
pbuf
Main packet buffer struct.
Definition: ppp_service_if.h:136
err.h
lwIP Error codes
err_t
s8_t err_t
Define LWIP_ERR_T in cc.h if you want to use a different type for your platform (must be signed)...
Definition: err.h:96
altcp.h
Application layered TCP connection API (to be used from TCPIP thread) .
iana.h
IANA assigned numbers (RFC 1700 and successors)
pbuf.h
pbuf API
nsapi_addr
IP address structure for passing IP addresses by value.
Definition: nsapi_types.h:235
ip_addr.h
IP address API (common IPv4 and IPv6)
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.