1 #ifndef _IPXE_DOWNLOAD_H
2 #define _IPXE_DOWNLOAD_H
5 * Copyright (C) 2010 VMware, Inc. All Rights Reserved.
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.
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.
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.
22 FILE_LICENCE ( GPL2_OR_LATER );
26 * iPXE Download Protocol
28 * EFI applications started by iPXE may use this interface to download files.
31 typedef struct _IPXE_DOWNLOAD_PROTOCOL IPXE_DOWNLOAD_PROTOCOL;
33 /** Token to represent a currently downloading file */
34 typedef VOID *IPXE_DOWNLOAD_FILE;
37 * Callback function that is invoked when data arrives for a particular file.
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.
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.
48 * @v Context Context provided to the Start function
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.
57 (EFIAPI *IPXE_DOWNLOAD_DATA_CALLBACK)(
60 IN UINTN BufferLength,
65 * Callback function that is invoked when the file is finished downloading, or
66 * when a connection unexpectedly closes or times out.
68 * The finish callback is also called when a download is aborted by the Abort
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
78 (EFIAPI *IPXE_DOWNLOAD_FINISH_CALLBACK)(
84 * Start downloading a file, and register callback functions to handle the
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
97 (EFIAPI *IPXE_DOWNLOAD_START)(
98 IN IPXE_DOWNLOAD_PROTOCOL *This,
100 IN IPXE_DOWNLOAD_DATA_CALLBACK DataCallback,
101 IN IPXE_DOWNLOAD_FINISH_CALLBACK FinishCallback,
103 OUT IPXE_DOWNLOAD_FILE *File
107 * Forcibly abort downloading a file that is currently in progress.
109 * It is not safe to call this function after the Finish callback has executed.
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
118 (EFIAPI *IPXE_DOWNLOAD_ABORT)(
119 IN IPXE_DOWNLOAD_PROTOCOL *This,
120 IN IPXE_DOWNLOAD_FILE File,
125 * Poll for more data from iPXE. This function will invoke the registered
126 * callbacks if data is available or if downloads complete.
128 * @v This iPXE Download Protocol instance
129 * @ret Status EFI status code
133 (EFIAPI *IPXE_DOWNLOAD_POLL)(
134 IN IPXE_DOWNLOAD_PROTOCOL *This
138 * The iPXE Download Protocol.
140 * iPXE will attach a iPXE Download Protocol to the DeviceHandle in the Loaded
141 * Image Protocol of all child EFI applications.
143 struct _IPXE_DOWNLOAD_PROTOCOL {
144 IPXE_DOWNLOAD_START Start;
145 IPXE_DOWNLOAD_ABORT Abort;
146 IPXE_DOWNLOAD_POLL Poll;
149 #define IPXE_DOWNLOAD_PROTOCOL_GUID \
151 0x3eaeaebd, 0xdecf, 0x493b, { 0x9b, 0xd1, 0xcd, 0xb2, 0xde, 0xca, 0xe7, 0x19 } \
154 extern int efi_download_install ( EFI_HANDLE handle );
155 extern void efi_download_uninstall ( EFI_HANDLE handle );
157 #endif /* _IPXE_DOWNLOAD_H */