]>
Commit | Line | Data |
---|---|---|
eb4d0b5e FS |
1 | /** @file |
2 | This library is used to share code between UEFI network stack modules. | |
3 | It provides the helper routines to parse the HTTP message byte stream. | |
4 | ||
5 | Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> | |
6 | This program and the accompanying materials | |
7 | are licensed and made available under the terms and conditions of the BSD License | |
8 | which accompanies this distribution. The full text of the license may be found at<BR> | |
9 | http://opensource.org/licenses/bsd-license.php | |
10 | ||
11 | THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, | |
12 | WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. | |
13 | ||
14 | **/ | |
15 | ||
16 | #ifndef _HTTP_LIB_H_ | |
17 | #define _HTTP_LIB_H_ | |
18 | ||
19 | #include <Protocol/Http.h> | |
20 | ||
21 | /** | |
22 | Decode a percent-encoded URI component to the ASCII character. | |
23 | ||
24 | Decode the input component in Buffer according to RFC 3986. The caller is responsible to make | |
25 | sure ResultBuffer points to a buffer with size equal or greater than ((AsciiStrSize (Buffer)) | |
26 | in bytes. | |
27 | ||
28 | @param[in] Buffer The pointer to a percent-encoded URI component. | |
29 | @param[in] BufferLength Length of Buffer in bytes. | |
30 | @param[out] ResultBuffer Point to the buffer to store the decode result. | |
31 | @param[out] ResultLength Length of decoded string in ResultBuffer in bytes. | |
32 | ||
33 | @retval EFI_SUCCESS Successfully decoded the URI. | |
34 | @retval EFI_INVALID_PARAMETER Buffer is not a valid percent-encoded string. | |
35 | ||
36 | **/ | |
37 | EFI_STATUS | |
38 | EFIAPI | |
39 | UriPercentDecode ( | |
40 | IN CHAR8 *Buffer, | |
41 | IN UINT32 BufferLength, | |
42 | OUT CHAR8 *ResultBuffer, | |
43 | OUT UINT32 *ResultLength | |
44 | ); | |
45 | ||
46 | /** | |
47 | Create a URL parser for the input URL string. | |
48 | ||
49 | This function will parse and dereference the input HTTP URL into it components. The original | |
50 | content of the URL won't be modified and the result will be returned in UrlParser, which can | |
51 | be used in other functions like NetHttpUrlGetHostName(). It is the caller's responsibility to | |
52 | free the buffer returned in *UrlParser by HttpUrlFreeParser(). | |
53 | ||
54 | @param[in] Url The pointer to a HTTP URL string. | |
55 | @param[in] Length Length of Url in bytes. | |
56 | @param[in] IsConnectMethod Whether the Url is used in HTTP CONNECT method or not. | |
57 | @param[out] UrlParser Pointer to the returned buffer to store the parse result. | |
58 | ||
59 | @retval EFI_SUCCESS Successfully dereferenced the HTTP URL. | |
60 | @retval EFI_INVALID_PARAMETER UrlParser is NULL or Url is not a valid HTTP URL. | |
61 | @retval EFI_OUT_OF_RESOURCES Could not allocate needed resources. | |
62 | ||
63 | **/ | |
64 | EFI_STATUS | |
65 | EFIAPI | |
66 | HttpParseUrl ( | |
67 | IN CHAR8 *Url, | |
68 | IN UINT32 Length, | |
69 | IN BOOLEAN IsConnectMethod, | |
70 | OUT VOID **UrlParser | |
71 | ); | |
72 | ||
73 | /** | |
74 | Get the Hostname from a HTTP URL. | |
75 | ||
76 | This function will return the HostName according to the Url and previous parse result ,and | |
77 | it is the caller's responsibility to free the buffer returned in *HostName. | |
78 | ||
79 | @param[in] Url The pointer to a HTTP URL string. | |
80 | @param[in] UrlParser URL Parse result returned by NetHttpParseUrl(). | |
81 | @param[out] HostName Pointer to a buffer to store the HostName. | |
82 | ||
83 | @retval EFI_SUCCESS Successfully get the required component. | |
84 | @retval EFI_INVALID_PARAMETER Uri is NULL or HostName is NULL or UrlParser is invalid. | |
85 | @retval EFI_NOT_FOUND No hostName component in the URL. | |
86 | @retval EFI_OUT_OF_RESOURCES Could not allocate needed resources. | |
87 | ||
88 | **/ | |
89 | EFI_STATUS | |
90 | EFIAPI | |
91 | HttpUrlGetHostName ( | |
92 | IN CHAR8 *Url, | |
93 | IN VOID *UrlParser, | |
94 | OUT CHAR8 **HostName | |
95 | ); | |
96 | ||
97 | /** | |
98 | Get the IPv4 address from a HTTP URL. | |
99 | ||
100 | This function will return the IPv4 address according to the Url and previous parse result. | |
101 | ||
102 | @param[in] Url The pointer to a HTTP URL string. | |
103 | @param[in] UrlParser URL Parse result returned by NetHttpParseUrl(). | |
104 | @param[out] Ip4Address Pointer to a buffer to store the IP address. | |
105 | ||
106 | @retval EFI_SUCCESS Successfully get the required component. | |
107 | @retval EFI_INVALID_PARAMETER Uri is NULL or Ip4Address is NULL or UrlParser is invalid. | |
108 | @retval EFI_NOT_FOUND No IPv4 address component in the URL. | |
109 | @retval EFI_OUT_OF_RESOURCES Could not allocate needed resources. | |
110 | ||
111 | **/ | |
112 | EFI_STATUS | |
113 | EFIAPI | |
114 | HttpUrlGetIp4 ( | |
115 | IN CHAR8 *Url, | |
116 | IN VOID *UrlParser, | |
117 | OUT EFI_IPv4_ADDRESS *Ip4Address | |
118 | ); | |
119 | ||
120 | /** | |
121 | Get the IPv6 address from a HTTP URL. | |
122 | ||
123 | This function will return the IPv6 address according to the Url and previous parse result. | |
124 | ||
125 | @param[in] Url The pointer to a HTTP URL string. | |
126 | @param[in] UrlParser URL Parse result returned by NetHttpParseUrl(). | |
127 | @param[out] Ip6Address Pointer to a buffer to store the IP address. | |
128 | ||
129 | @retval EFI_SUCCESS Successfully get the required component. | |
130 | @retval EFI_INVALID_PARAMETER Uri is NULL or Ip6Address is NULL or UrlParser is invalid. | |
131 | @retval EFI_NOT_FOUND No IPv6 address component in the URL. | |
132 | @retval EFI_OUT_OF_RESOURCES Could not allocate needed resources. | |
133 | ||
134 | **/ | |
135 | EFI_STATUS | |
136 | EFIAPI | |
137 | HttpUrlGetIp6 ( | |
138 | IN CHAR8 *Url, | |
139 | IN VOID *UrlParser, | |
140 | OUT EFI_IPv6_ADDRESS *Ip6Address | |
141 | ); | |
142 | ||
143 | /** | |
144 | Get the port number from a HTTP URL. | |
145 | ||
146 | This function will return the port number according to the Url and previous parse result. | |
147 | ||
148 | @param[in] Url The pointer to a HTTP URL string. | |
149 | @param[in] UrlParser URL Parse result returned by NetHttpParseUrl(). | |
150 | @param[out] Port Pointer to a buffer to store the port number. | |
151 | ||
152 | @retval EFI_SUCCESS Successfully get the required component. | |
153 | @retval EFI_INVALID_PARAMETER Uri is NULL or Port is NULL or UrlParser is invalid. | |
154 | @retval EFI_NOT_FOUND No port number in the URL. | |
155 | @retval EFI_OUT_OF_RESOURCES Could not allocate needed resources. | |
156 | ||
157 | **/ | |
158 | EFI_STATUS | |
159 | EFIAPI | |
160 | HttpUrlGetPort ( | |
161 | IN CHAR8 *Url, | |
162 | IN VOID *UrlParser, | |
163 | OUT UINT16 *Port | |
164 | ); | |
165 | ||
166 | /** | |
167 | Release the resource of the URL parser. | |
168 | ||
169 | @param[in] UrlParser Pointer to the parser. | |
170 | ||
171 | **/ | |
172 | VOID | |
173 | EFIAPI | |
174 | HttpUrlFreeParser ( | |
175 | IN VOID *UrlParser | |
176 | ); | |
177 | ||
178 | // | |
179 | // HTTP body parser interface. | |
180 | // | |
181 | ||
182 | typedef enum { | |
183 | // | |
184 | // Part of entity data. | |
185 | // Length of entity body in Data. | |
186 | // | |
187 | BodyParseEventOnData, | |
188 | // | |
189 | // End of message body. | |
190 | // Length is 0 and Data points to next byte after the end of the message. | |
191 | // | |
192 | BodyParseEventOnComplete | |
193 | } HTTP_BODY_PARSE_EVENT; | |
194 | ||
195 | /** | |
196 | A callback function to intercept events during message parser. | |
197 | ||
198 | This function will be invoked during HttpParseMessageBody() with various events type. An error | |
199 | return status of the callback function will cause the HttpParseMessageBody() aborted. | |
200 | ||
201 | @param[in] EventType Event type of this callback call. | |
202 | @param[in] Data A pointer to data buffer. | |
203 | @param[in] Length Length in bytes of the Data. | |
204 | @param[in] Context Callback context set by HttpInitMsgParser(). | |
205 | ||
206 | @retval EFI_SUCCESS Continue to parser the message body. | |
207 | @retval Others Abort the parse. | |
208 | ||
209 | **/ | |
210 | typedef | |
211 | EFI_STATUS | |
212 | (EFIAPI *HTTP_BODY_PARSER_CALLBACK) ( | |
213 | IN HTTP_BODY_PARSE_EVENT EventType, | |
214 | IN CHAR8 *Data, | |
215 | IN UINTN Length, | |
216 | IN VOID *Context | |
217 | ); | |
218 | ||
219 | /** | |
220 | Initialize a HTTP message-body parser. | |
221 | ||
222 | This function will create and initialize a HTTP message parser according to caller provided HTTP message | |
223 | header information. It is the caller's responsibility to free the buffer returned in *UrlParser by HttpFreeMsgParser(). | |
224 | ||
225 | @param[in] Method The HTTP method (e.g. GET, POST) for this HTTP message. | |
226 | @param[in] StatusCode Response status code returned by the remote host. | |
227 | @param[in] HeaderCount Number of HTTP header structures in Headers. | |
228 | @param[in] Headers Array containing list of HTTP headers. | |
229 | @param[in] Callback Callback function that is invoked when parsing the HTTP message-body, | |
230 | set to NULL to ignore all events. | |
231 | @param[in] Context Pointer to the context that will be passed to Callback. | |
232 | @param[out] MsgParser Pointer to the returned buffer to store the message parser. | |
233 | ||
234 | @retval EFI_SUCCESS Successfully initialized the parser. | |
235 | @retval EFI_OUT_OF_RESOURCES Could not allocate needed resources. | |
236 | @retval EFI_INVALID_PARAMETER MsgParser is NULL or HeaderCount is not NULL but Headers is NULL. | |
237 | @retval Others Failed to initialize the parser. | |
238 | ||
239 | **/ | |
240 | EFI_STATUS | |
241 | EFIAPI | |
242 | HttpInitMsgParser ( | |
243 | IN EFI_HTTP_METHOD Method, | |
244 | IN EFI_HTTP_STATUS_CODE StatusCode, | |
245 | IN UINTN HeaderCount, | |
246 | IN EFI_HTTP_HEADER *Headers, | |
247 | IN HTTP_BODY_PARSER_CALLBACK Callback, | |
248 | IN VOID *Context, | |
249 | OUT VOID **MsgParser | |
250 | ); | |
251 | ||
252 | /** | |
253 | Parse message body. | |
254 | ||
255 | Parse BodyLength of message-body. This function can be called repeatedly to parse the message-body partially. | |
256 | ||
257 | @param[in, out] MsgParser Pointer to the message parser. | |
258 | @param[in] BodyLength Length in bytes of the Body. | |
259 | @param[in] Body Pointer to the buffer of the message-body to be parsed. | |
260 | ||
261 | @retval EFI_SUCCESS Successfully parse the message-body. | |
262 | @retval EFI_INVALID_PARAMETER MsgParser is NULL or Body is NULL or BodyLength is 0. | |
263 | @retval Others Operation aborted. | |
264 | ||
265 | **/ | |
266 | EFI_STATUS | |
267 | EFIAPI | |
268 | HttpParseMessageBody ( | |
269 | IN OUT VOID *MsgParser, | |
270 | IN UINTN BodyLength, | |
271 | IN CHAR8 *Body | |
272 | ); | |
273 | ||
274 | /** | |
275 | Check whether the message-body is complete or not. | |
276 | ||
277 | @param[in] MsgParser Pointer to the message parser. | |
278 | ||
279 | @retval TRUE Message-body is complete. | |
280 | @retval FALSE Message-body is not complete. | |
281 | ||
282 | **/ | |
283 | BOOLEAN | |
284 | EFIAPI | |
285 | HttpIsMessageComplete ( | |
286 | IN VOID *MsgParser | |
287 | ); | |
288 | ||
289 | /** | |
290 | Get the content length of the entity. | |
291 | ||
292 | Note that in trunk transfer, the entity length is not valid until the whole message body is received. | |
293 | ||
294 | @param[in] MsgParser Pointer to the message parser. | |
295 | @param[out] ContentLength Pointer to store the length of the entity. | |
296 | ||
297 | @retval EFI_SUCCESS Successfully to get the entity length. | |
298 | @retval EFI_NOT_READY Entity length is not valid yet. | |
299 | @retval EFI_INVALID_PARAMETER MsgParser is NULL or ContentLength is NULL. | |
300 | ||
301 | **/ | |
302 | EFI_STATUS | |
303 | EFIAPI | |
304 | HttpGetEntityLength ( | |
305 | IN VOID *MsgParser, | |
306 | OUT UINTN *ContentLength | |
307 | ); | |
308 | ||
309 | /** | |
310 | Release the resource of the message parser. | |
311 | ||
312 | @param[in] MsgParser Pointer to the message parser. | |
313 | ||
314 | **/ | |
315 | VOID | |
316 | EFIAPI | |
317 | HttpFreeMsgParser ( | |
318 | IN VOID *MsgParser | |
319 | ); | |
320 | ||
321 | ||
322 | #endif | |
323 |