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