iPXE
efi_download.h
Go to the documentation of this file.
1 #ifndef _IPXE_DOWNLOAD_H
2 #define _IPXE_DOWNLOAD_H
3 
4 /*
5  * Copyright (C) 2010 VMware, Inc. All Rights Reserved.
6  *
7  * This program is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License as
9  * published by the Free Software Foundation; either version 2 of the
10  * License, or any later version.
11  *
12  * This program is distributed in the hope that it will be useful, but
13  * WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  * General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with this program; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  */
21 
22 FILE_LICENCE ( GPL2_OR_LATER );
23 
24 /** @file
25  *
26  * iPXE Download Protocol
27  *
28  * EFI applications started by iPXE may use this interface to download files.
29  */
30 
32 
33 /** Token to represent a currently downloading file */
35 
36 /**
37  * Callback function that is invoked when data arrives for a particular file.
38  *
39  * Not all protocols will deliver data in order. Clients should not rely on the
40  * order of data delivery matching the order in the file.
41  *
42  * Some protocols are capable of determining the file size near the beginning
43  * of data transfer. To allow the client to allocate memory more efficiently,
44  * iPXE may give a hint about the file size by calling the Data callback with
45  * a zero BufferLength and the file size in FileOffset. Clients should be
46  * prepared to deal with more or less data than the hint actually arriving.
47  *
48  * @v Context Context provided to the Start function
49  * @v Buffer New data
50  * @v BufferLength Length of new data in bytes
51  * @v FileOffset Offset of new data in the file
52  * @ret Status EFI_SUCCESS to continue the download,
53  * or any error code to abort.
54  */
55 typedef
58  IN VOID *Context,
59  IN VOID *Buffer,
61  IN UINTN FileOffset
62  );
63 
64 /**
65  * Callback function that is invoked when the file is finished downloading, or
66  * when a connection unexpectedly closes or times out.
67  *
68  * The finish callback is also called when a download is aborted by the Abort
69  * function (below).
70  *
71  * @v Context Context provided to the Start function
72  * @v Status Reason for termination: EFI_SUCCESS when the entire
73  * file was transferred successfully, or an error
74  * otherwise
75  */
76 typedef
77 void
79  IN VOID *Context,
81  );
82 
83 /**
84  * Start downloading a file, and register callback functions to handle the
85  * download.
86  *
87  * @v This iPXE Download Protocol instance
88  * @v Url URL to download from
89  * @v DataCallback Callback that will be invoked when data arrives
90  * @v FinishCallback Callback that will be invoked when the download ends
91  * @v Context Context passed to the Data and Finish callbacks
92  * @v File Token that can be used to abort the download
93  * @ret Status EFI status code
94  */
95 typedef
99  IN CHAR8 *Url,
100  IN IPXE_DOWNLOAD_DATA_CALLBACK DataCallback,
101  IN IPXE_DOWNLOAD_FINISH_CALLBACK FinishCallback,
102  IN VOID *Context,
103  OUT IPXE_DOWNLOAD_FILE *File
104  );
105 
106 /**
107  * Forcibly abort downloading a file that is currently in progress.
108  *
109  * It is not safe to call this function after the Finish callback has executed.
110  *
111  * @v This iPXE Download Protocol instance
112  * @v File Token obtained from Start
113  * @v Status Reason for aborting the download
114  * @ret Status EFI status code
115  */
116 typedef
120  IN IPXE_DOWNLOAD_FILE File,
122  );
123 
124 /**
125  * Poll for more data from iPXE. This function will invoke the registered
126  * callbacks if data is available or if downloads complete.
127  *
128  * @v This iPXE Download Protocol instance
129  * @ret Status EFI status code
130  */
131 typedef
135  );
136 
137 /**
138  * The iPXE Download Protocol.
139  *
140  * iPXE will attach a iPXE Download Protocol to the DeviceHandle in the Loaded
141  * Image Protocol of all child EFI applications.
142  */
147 };
148 
149 #define IPXE_DOWNLOAD_PROTOCOL_GUID \
150  { \
151  0x3eaeaebd, 0xdecf, 0x493b, { 0x9b, 0xd1, 0xcd, 0xb2, 0xde, 0xca, 0xe7, 0x19 } \
152  }
153 
154 extern int efi_download_install ( EFI_HANDLE handle );
156 
157 #endif /* _IPXE_DOWNLOAD_H */
IPXE_DOWNLOAD_POLL Poll
Definition: efi_download.h:146
The iPXE Download Protocol.
Definition: efi_download.h:143
PXENV_STATUS_t Status
PXE status code.
Definition: pxe_api.h:57
EFI_STATUS(EFIAPI * IPXE_DOWNLOAD_START)(IN IPXE_DOWNLOAD_PROTOCOL *This, IN CHAR8 *Url, IN IPXE_DOWNLOAD_DATA_CALLBACK DataCallback, IN IPXE_DOWNLOAD_FINISH_CALLBACK FinishCallback, IN VOID *Context, OUT IPXE_DOWNLOAD_FILE *File)
Start downloading a file, and register callback functions to handle the download.
Definition: efi_download.h:97
VOID * IPXE_DOWNLOAD_FILE
Token to represent a currently downloading file.
Definition: efi_download.h:34
EFI_STATUS(EFIAPI * IPXE_DOWNLOAD_ABORT)(IN IPXE_DOWNLOAD_PROTOCOL *This, IN IPXE_DOWNLOAD_FILE File, IN EFI_STATUS Status)
Forcibly abort downloading a file that is currently in progress.
Definition: efi_download.h:118
IPXE_DOWNLOAD_START Start
Definition: efi_download.h:144
void(EFIAPI * IPXE_DOWNLOAD_FINISH_CALLBACK)(IN VOID *Context, IN EFI_STATUS Status)
Callback function that is invoked when the file is finished downloading, or when a connection unexpec...
Definition: efi_download.h:78
#define OUT
Definition: mlx_utils.h:29
EFI_STATUS(EFIAPI * IPXE_DOWNLOAD_POLL)(IN IPXE_DOWNLOAD_PROTOCOL *This)
Poll for more data from iPXE.
Definition: efi_download.h:133
UINT16_t BufferLength
Data buffer length.
Definition: pxe_api.h:67
FILE_LICENCE(GPL2_OR_LATER)
#define EFIAPI
SEGOFF16_t Buffer
Buffer address.
Definition: pxe_api.h:65
int efi_download_install(EFI_HANDLE handle)
Install iPXE download protocol.
Definition: efi_download.c:211
UINT64 UINTN
Unsigned value of native width.
Definition: ProcessorBind.h:71
void efi_download_uninstall(EFI_HANDLE handle)
Uninstall iPXE download protocol.
Definition: efi_download.c:236
#define VOID
Undeclared type.
Definition: Base.h:319
#define IN
Definition: mlx_utils.h:28
IPXE_DOWNLOAD_ABORT Abort
Definition: efi_download.h:145
char CHAR8
Definition: ProcessorBind.h:63
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:35
uint16_t handle
Handle.
Definition: smbios.h:16
EFI_STATUS(EFIAPI * IPXE_DOWNLOAD_DATA_CALLBACK)(IN VOID *Context, IN VOID *Buffer, IN UINTN BufferLength, IN UINTN FileOffset)
Callback function that is invoked when data arrives for a particular file.
Definition: efi_download.h:57
Definition: efi.h:55