]> git.proxmox.com Git - mirror_edk2.git/blob - NetworkPkg/HttpBootDxe/HttpBootSupport.h
EmulatorPkg/PeiEmuSerialPortLib: Update the INF file Guid
[mirror_edk2.git] / NetworkPkg / HttpBootDxe / HttpBootSupport.h
1 /** @file
2 Support functions declaration for UEFI HTTP boot driver.
3
4 Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
6
7 **/
8
9 #ifndef __EFI_HTTP_BOOT_SUPPORT_H__
10 #define __EFI_HTTP_BOOT_SUPPORT_H__
11
12 /**
13 Get the Nic handle using any child handle in the IPv4 stack.
14
15 @param[in] ControllerHandle Pointer to child handle over IPv4.
16
17 @return NicHandle The pointer to the Nic handle.
18 @return NULL Can't find the Nic handle.
19
20 **/
21 EFI_HANDLE
22 HttpBootGetNicByIp4Children (
23 IN EFI_HANDLE ControllerHandle
24 );
25
26 /**
27 Get the Nic handle using any child handle in the IPv6 stack.
28
29 @param[in] ControllerHandle Pointer to child handle over IPv6.
30
31 @return NicHandle The pointer to the Nic handle.
32 @return NULL Can't find the Nic handle.
33
34 **/
35 EFI_HANDLE
36 HttpBootGetNicByIp6Children (
37 IN EFI_HANDLE ControllerHandle
38 );
39
40 /**
41 This function is to convert UINTN to ASCII string with the required formatting.
42
43 @param[in] Number Numeric value to be converted.
44 @param[in] Buffer The pointer to the buffer for ASCII string.
45 @param[in] Length The length of the required format.
46
47 **/
48 VOID
49 HttpBootUintnToAscDecWithFormat (
50 IN UINTN Number,
51 IN UINT8 *Buffer,
52 IN INTN Length
53 );
54
55
56 /**
57 This function is to display the IPv4 address.
58
59 @param[in] Ip The pointer to the IPv4 address.
60
61 **/
62 VOID
63 HttpBootShowIp4Addr (
64 IN EFI_IPv4_ADDRESS *Ip
65 );
66
67 /**
68 This function is to display the IPv6 address.
69
70 @param[in] Ip The pointer to the IPv6 address.
71
72 **/
73 VOID
74 HttpBootShowIp6Addr (
75 IN EFI_IPv6_ADDRESS *Ip
76 );
77
78 /**
79 This function is to display the HTTP error status.
80
81 @param[in] StatusCode The status code value in HTTP message.
82
83 **/
84 VOID
85 HttpBootPrintErrorMessage (
86 EFI_HTTP_STATUS_CODE StatusCode
87 );
88
89 //
90 // A wrapper structure to hold the HTTP headers.
91 //
92 typedef struct {
93 UINTN MaxHeaderCount;
94 UINTN HeaderCount;
95 EFI_HTTP_HEADER *Headers;
96 } HTTP_IO_HEADER;
97
98 /**
99 Create a HTTP_IO_HEADER to hold the HTTP header items.
100
101 @param[in] MaxHeaderCount The maximun number of HTTP header in this holder.
102
103 @return A pointer of the HTTP header holder or NULL if failed.
104
105 **/
106 HTTP_IO_HEADER *
107 HttpBootCreateHeader (
108 IN UINTN MaxHeaderCount
109 );
110
111 /**
112 Destroy the HTTP_IO_HEADER and release the resouces.
113
114 @param[in] HttpIoHeader Point to the HTTP header holder to be destroyed.
115
116 **/
117 VOID
118 HttpBootFreeHeader (
119 IN HTTP_IO_HEADER *HttpIoHeader
120 );
121
122 /**
123 Set or update a HTTP header with the field name and corresponding value.
124
125 @param[in] HttpIoHeader Point to the HTTP header holder.
126 @param[in] FieldName Null terminated string which describes a field name.
127 @param[in] FieldValue Null terminated string which describes the corresponding field value.
128
129 @retval EFI_SUCCESS The HTTP header has been set or updated.
130 @retval EFI_INVALID_PARAMETER Any input parameter is invalid.
131 @retval EFI_OUT_OF_RESOURCES Insufficient resource to complete the operation.
132 @retval Other Unexpected error happened.
133
134 **/
135 EFI_STATUS
136 HttpBootSetHeader (
137 IN HTTP_IO_HEADER *HttpIoHeader,
138 IN CHAR8 *FieldName,
139 IN CHAR8 *FieldValue
140 );
141
142 ///
143 /// HTTP_IO_CALLBACK_EVENT
144 ///
145 typedef enum {
146 HttpIoRequest,
147 HttpIoResponse
148 } HTTP_IO_CALLBACK_EVENT;
149
150 /**
151 HttpIo Callback function which will be invoked when specified HTTP_IO_CALLBACK_EVENT happened.
152
153 @param[in] EventType Indicate the Event type that occurs in the current callback.
154 @param[in] Message HTTP message which will be send to, or just received from HTTP server.
155 @param[in] Context The Callback Context pointer.
156
157 @retval EFI_SUCCESS Tells the HttpIo to continue the HTTP process.
158 @retval Others Tells the HttpIo to abort the current HTTP process.
159 **/
160 typedef
161 EFI_STATUS
162 (EFIAPI * HTTP_IO_CALLBACK) (
163 IN HTTP_IO_CALLBACK_EVENT EventType,
164 IN EFI_HTTP_MESSAGE *Message,
165 IN VOID *Context
166 );
167
168 //
169 // HTTP_IO configuration data for IPv4
170 //
171 typedef struct {
172 EFI_HTTP_VERSION HttpVersion;
173 UINT32 RequestTimeOut; // In milliseconds.
174 UINT32 ResponseTimeOut; // In milliseconds.
175 BOOLEAN UseDefaultAddress;
176 EFI_IPv4_ADDRESS LocalIp;
177 EFI_IPv4_ADDRESS SubnetMask;
178 UINT16 LocalPort;
179 } HTTP4_IO_CONFIG_DATA;
180
181 //
182 // HTTP_IO configuration data for IPv6
183 //
184 typedef struct {
185 EFI_HTTP_VERSION HttpVersion;
186 UINT32 RequestTimeOut; // In milliseconds.
187 BOOLEAN UseDefaultAddress;
188 EFI_IPv6_ADDRESS LocalIp;
189 UINT16 LocalPort;
190 } HTTP6_IO_CONFIG_DATA;
191
192
193 //
194 // HTTP_IO configuration
195 //
196 typedef union {
197 HTTP4_IO_CONFIG_DATA Config4;
198 HTTP6_IO_CONFIG_DATA Config6;
199 } HTTP_IO_CONFIG_DATA;
200
201 //
202 // HTTP_IO wrapper of the EFI HTTP service.
203 //
204 typedef struct {
205 UINT8 IpVersion;
206 EFI_HANDLE Image;
207 EFI_HANDLE Controller;
208 EFI_HANDLE Handle;
209
210 EFI_HTTP_PROTOCOL *Http;
211
212 HTTP_IO_CALLBACK Callback;
213 VOID *Context;
214
215 EFI_HTTP_TOKEN ReqToken;
216 EFI_HTTP_MESSAGE ReqMessage;
217 EFI_HTTP_TOKEN RspToken;
218 EFI_HTTP_MESSAGE RspMessage;
219
220 BOOLEAN IsTxDone;
221 BOOLEAN IsRxDone;
222
223 EFI_EVENT TimeoutEvent;
224 } HTTP_IO;
225
226 //
227 // A wrapper structure to hold the received HTTP response data.
228 //
229 typedef struct {
230 EFI_HTTP_RESPONSE_DATA Response;
231 UINTN HeaderCount;
232 EFI_HTTP_HEADER *Headers;
233 UINTN BodyLength;
234 CHAR8 *Body;
235 EFI_STATUS Status;
236 } HTTP_IO_RESPONSE_DATA;
237
238 /**
239 Retrieve the host address using the EFI_DNS6_PROTOCOL.
240
241 @param[in] Private The pointer to the driver's private data.
242 @param[in] HostName Pointer to buffer containing hostname.
243 @param[out] IpAddress On output, pointer to buffer containing IPv6 address.
244
245 @retval EFI_SUCCESS Operation succeeded.
246 @retval EFI_DEVICE_ERROR An unexpected network error occurred.
247 @retval Others Other errors as indicated.
248 **/
249 EFI_STATUS
250 HttpBootDns (
251 IN HTTP_BOOT_PRIVATE_DATA *Private,
252 IN CHAR16 *HostName,
253 OUT EFI_IPv6_ADDRESS *IpAddress
254 );
255
256 /**
257 Notify the callback function when an event is triggered.
258
259 @param[in] Event The triggered event.
260 @param[in] Context The opaque parameter to the function.
261
262 **/
263 VOID
264 EFIAPI
265 HttpBootCommonNotify (
266 IN EFI_EVENT Event,
267 IN VOID *Context
268 );
269
270 /**
271 Create a HTTP_IO to access the HTTP service. It will create and configure
272 a HTTP child handle.
273
274 @param[in] Image The handle of the driver image.
275 @param[in] Controller The handle of the controller.
276 @param[in] IpVersion IP_VERSION_4 or IP_VERSION_6.
277 @param[in] ConfigData The HTTP_IO configuration data.
278 @param[in] Callback Callback function which will be invoked when specified
279 HTTP_IO_CALLBACK_EVENT happened.
280 @param[in] Context The Context data which will be passed to the Callback function.
281 @param[out] HttpIo The HTTP_IO.
282
283 @retval EFI_SUCCESS The HTTP_IO is created and configured.
284 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
285 @retval EFI_UNSUPPORTED One or more of the control options are not
286 supported in the implementation.
287 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
288 @retval Others Failed to create the HTTP_IO or configure it.
289
290 **/
291 EFI_STATUS
292 HttpIoCreateIo (
293 IN EFI_HANDLE Image,
294 IN EFI_HANDLE Controller,
295 IN UINT8 IpVersion,
296 IN HTTP_IO_CONFIG_DATA *ConfigData,
297 IN HTTP_IO_CALLBACK Callback,
298 IN VOID *Context,
299 OUT HTTP_IO *HttpIo
300 );
301
302 /**
303 Destroy the HTTP_IO and release the resouces.
304
305 @param[in] HttpIo The HTTP_IO which wraps the HTTP service to be destroyed.
306
307 **/
308 VOID
309 HttpIoDestroyIo (
310 IN HTTP_IO *HttpIo
311 );
312
313 /**
314 Synchronously send a HTTP REQUEST message to the server.
315
316 @param[in] HttpIo The HttpIo wrapping the HTTP service.
317 @param[in] Request A pointer to storage such data as URL and HTTP method.
318 @param[in] HeaderCount Number of HTTP header structures in Headers list.
319 @param[in] Headers Array containing list of HTTP headers.
320 @param[in] BodyLength Length in bytes of the HTTP body.
321 @param[in] Body Body associated with the HTTP request.
322
323 @retval EFI_SUCCESS The HTTP request is trasmitted.
324 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
325 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
326 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
327 @retval Others Other errors as indicated.
328
329 **/
330 EFI_STATUS
331 HttpIoSendRequest (
332 IN HTTP_IO *HttpIo,
333 IN EFI_HTTP_REQUEST_DATA *Request, OPTIONAL
334 IN UINTN HeaderCount,
335 IN EFI_HTTP_HEADER *Headers, OPTIONAL
336 IN UINTN BodyLength,
337 IN VOID *Body OPTIONAL
338 );
339
340 /**
341 Synchronously receive a HTTP RESPONSE message from the server.
342
343 @param[in] HttpIo The HttpIo wrapping the HTTP service.
344 @param[in] RecvMsgHeader TRUE to receive a new HTTP response (from message header).
345 FALSE to continue receive the previous response message.
346 @param[out] ResponseData Point to a wrapper of the received response data.
347
348 @retval EFI_SUCCESS The HTTP response is received.
349 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
350 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
351 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
352 @retval Others Other errors as indicated.
353
354 **/
355 EFI_STATUS
356 HttpIoRecvResponse (
357 IN HTTP_IO *HttpIo,
358 IN BOOLEAN RecvMsgHeader,
359 OUT HTTP_IO_RESPONSE_DATA *ResponseData
360 );
361
362 /**
363 This function checks the HTTP(S) URI scheme.
364
365 @param[in] Uri The pointer to the URI string.
366
367 @retval EFI_SUCCESS The URI scheme is valid.
368 @retval EFI_INVALID_PARAMETER The URI scheme is not HTTP or HTTPS.
369 @retval EFI_ACCESS_DENIED HTTP is disabled and the URI is HTTP.
370
371 **/
372 EFI_STATUS
373 HttpBootCheckUriScheme (
374 IN CHAR8 *Uri
375 );
376
377 /**
378 Get the URI address string from the input device path.
379
380 Caller need to free the buffer in the UriAddress pointer.
381
382 @param[in] FilePath Pointer to the device path which contains a URI device path node.
383 @param[out] UriAddress The URI address string extract from the device path.
384
385 @retval EFI_SUCCESS The URI string is returned.
386 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
387
388 **/
389 EFI_STATUS
390 HttpBootParseFilePath (
391 IN EFI_DEVICE_PATH_PROTOCOL *FilePath,
392 OUT CHAR8 **UriAddress
393 );
394
395 /**
396 This function returns the image type according to server replied HTTP message
397 and also the image's URI info.
398
399 @param[in] Uri The pointer to the image's URI string.
400 @param[in] UriParser URI Parse result returned by NetHttpParseUrl().
401 @param[in] HeaderCount Number of HTTP header structures in Headers list.
402 @param[in] Headers Array containing list of HTTP headers.
403 @param[out] ImageType The image type of the downloaded file.
404
405 @retval EFI_SUCCESS The image type is returned in ImageType.
406 @retval EFI_INVALID_PARAMETER ImageType, Uri or UriParser is NULL.
407 @retval EFI_INVALID_PARAMETER HeaderCount is not zero, and Headers is NULL.
408 @retval EFI_NOT_FOUND Failed to identify the image type.
409 @retval Others Unexpect error happened.
410
411 **/
412 EFI_STATUS
413 HttpBootCheckImageType (
414 IN CHAR8 *Uri,
415 IN VOID *UriParser,
416 IN UINTN HeaderCount,
417 IN EFI_HTTP_HEADER *Headers,
418 OUT HTTP_BOOT_IMAGE_TYPE *ImageType
419 );
420
421 /**
422 This function register the RAM disk info to the system.
423
424 @param[in] Private The pointer to the driver's private data.
425 @param[in] BufferSize The size of Buffer in bytes.
426 @param[in] Buffer The base address of the RAM disk.
427 @param[in] ImageType The image type of the file in Buffer.
428
429 @retval EFI_SUCCESS The RAM disk has been registered.
430 @retval EFI_NOT_FOUND No RAM disk protocol instances were found.
431 @retval EFI_UNSUPPORTED The ImageType is not supported.
432 @retval Others Unexpected error happened.
433
434 **/
435 EFI_STATUS
436 HttpBootRegisterRamDisk (
437 IN HTTP_BOOT_PRIVATE_DATA *Private,
438 IN UINTN BufferSize,
439 IN VOID *Buffer,
440 IN HTTP_BOOT_IMAGE_TYPE ImageType
441 );
442
443 /**
444 Indicate if the HTTP status code indicates a redirection.
445
446 @param[in] StatusCode HTTP status code from server.
447
448 @return TRUE if it's redirection.
449
450 **/
451 BOOLEAN
452 HttpBootIsHttpRedirectStatusCode (
453 IN EFI_HTTP_STATUS_CODE StatusCode
454 );
455 #endif