]> git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Protocol/Mtftp4.h
f2c3084b8877f48d3da84f139a64f9cbecdd2622
[mirror_edk2.git] / MdePkg / Include / Protocol / Mtftp4.h
1 /** @file
2 EFI Multicast Trivial File Tranfer Protocol Definition
3
4 Copyright (c) 2006 - 2008, Intel Corporation
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 **/
14
15 #ifndef __EFI_MTFTP4_PROTOCOL_H__
16 #define __EFI_MTFTP4_PROTOCOL_H__
17
18 #define EFI_MTFTP4_SERVICE_BINDING_PROTOCOL_GUID \
19 { \
20 0x2FE800BE, 0x8F01, 0x4aa6, {0x94, 0x6B, 0xD7, 0x13, 0x88, 0xE1, 0x83, 0x3F } \
21 }
22
23 #define EFI_MTFTP4_PROTOCOL_GUID \
24 { \
25 0x78247c57, 0x63db, 0x4708, {0x99, 0xc2, 0xa8, 0xb4, 0xa9, 0xa6, 0x1f, 0x6b } \
26 }
27
28 typedef struct _EFI_MTFTP4_PROTOCOL EFI_MTFTP4_PROTOCOL;
29 typedef struct _EFI_MTFTP4_TOKEN EFI_MTFTP4_TOKEN;
30
31 //
32 //MTFTP4 packet opcode definition
33 //
34 #define EFI_MTFTP4_OPCODE_RRQ 1
35 #define EFI_MTFTP4_OPCODE_WRQ 2
36 #define EFI_MTFTP4_OPCODE_DATA 3
37 #define EFI_MTFTP4_OPCODE_ACK 4
38 #define EFI_MTFTP4_OPCODE_ERROR 5
39 #define EFI_MTFTP4_OPCODE_OACK 6
40 #define EFI_MTFTP4_OPCODE_DIR 7
41 #define EFI_MTFTP4_OPCODE_DATA8 8
42 #define EFI_MTFTP4_OPCODE_ACK8 9
43
44 //
45 // MTFTP4 error code definition
46 //
47 #define EFI_MTFTP4_ERRORCODE_NOT_DEFINED 0
48 #define EFI_MTFTP4_ERRORCODE_FILE_NOT_FOUND 1
49 #define EFI_MTFTP4_ERRORCODE_ACCESS_VIOLATION 2
50 #define EFI_MTFTP4_ERRORCODE_DISK_FULL 3
51 #define EFI_MTFTP4_ERRORCODE_ILLEGAL_OPERATION 4
52 #define EFI_MTFTP4_ERRORCODE_UNKNOWN_TRANSFER_ID 5
53 #define EFI_MTFTP4_ERRORCODE_FILE_ALREADY_EXISTS 6
54 #define EFI_MTFTP4_ERRORCODE_NO_SUCH_USER 7
55 #define EFI_MTFTP4_ERRORCODE_REQUEST_DENIED 8
56
57 //
58 // MTFTP4 pacekt definitions
59 //
60 #pragma pack(1)
61
62 typedef struct {
63 UINT16 OpCode;
64 UINT8 Filename[1];
65 } EFI_MTFTP4_REQ_HEADER;
66
67 typedef struct {
68 UINT16 OpCode;
69 UINT8 Data[1];
70 } EFI_MTFTP4_OACK_HEADER;
71
72 typedef struct {
73 UINT16 OpCode;
74 UINT16 Block;
75 UINT8 Data[1];
76 } EFI_MTFTP4_DATA_HEADER;
77
78 typedef struct {
79 UINT16 OpCode;
80 UINT16 Block[1];
81 } EFI_MTFTP4_ACK_HEADER;
82
83 typedef struct {
84 UINT16 OpCode;
85 UINT64 Block;
86 UINT8 Data[1];
87 } EFI_MTFTP4_DATA8_HEADER;
88
89 typedef struct {
90 UINT16 OpCode;
91 UINT64 Block[1];
92 } EFI_MTFTP4_ACK8_HEADER;
93
94 typedef struct {
95 UINT16 OpCode;
96 UINT16 ErrorCode;
97 UINT8 ErrorMessage[1];
98 } EFI_MTFTP4_ERROR_HEADER;
99
100 typedef union {
101 UINT16 OpCode;
102 EFI_MTFTP4_REQ_HEADER Rrq;
103 EFI_MTFTP4_REQ_HEADER Wrq;
104 EFI_MTFTP4_OACK_HEADER Oack;
105 EFI_MTFTP4_DATA_HEADER Data;
106 EFI_MTFTP4_ACK_HEADER Ack;
107 EFI_MTFTP4_DATA8_HEADER Data8;
108 EFI_MTFTP4_ACK8_HEADER Ack8;
109 EFI_MTFTP4_ERROR_HEADER Error;
110 } EFI_MTFTP4_PACKET;
111
112 #pragma pack()
113
114 ///
115 /// MTFTP4 option definition
116 ///
117 typedef struct {
118 UINT8 *OptionStr;
119 UINT8 *ValueStr;
120 } EFI_MTFTP4_OPTION;
121
122
123 typedef struct {
124 BOOLEAN UseDefaultSetting;
125 EFI_IPv4_ADDRESS StationIp;
126 EFI_IPv4_ADDRESS SubnetMask;
127 UINT16 LocalPort;
128 EFI_IPv4_ADDRESS GatewayIp;
129 EFI_IPv4_ADDRESS ServerIp;
130 UINT16 InitialServerPort;
131 UINT16 TryCount;
132 UINT16 TimeoutValue;
133 } EFI_MTFTP4_CONFIG_DATA;
134
135
136 typedef struct {
137 EFI_MTFTP4_CONFIG_DATA ConfigData;
138 UINT8 SupportedOptionCount;
139 UINT8 **SupportedOptoins;
140 UINT8 UnsupportedOptionCount;
141 UINT8 **UnsupportedOptoins;
142 } EFI_MTFTP4_MODE_DATA;
143
144
145 typedef struct {
146 EFI_IPv4_ADDRESS GatewayIp;
147 EFI_IPv4_ADDRESS ServerIp;
148 UINT16 ServerPort;
149 UINT16 TryCount;
150 UINT16 TimeoutValue;
151 } EFI_MTFTP4_OVERRIDE_DATA;
152
153 //
154 // Protocol interfaces definition
155 //
156
157 /**
158 a callback function that is provided by the caller to intercept
159 the EFI_MTFTP4_OPCODE_DATA or EFI_MTFTP4_OPCODE_DATA8 packets processed in the
160 EFI_MTFTP4_PROTOCOL.ReadFile() function, and alternatively to intercept
161 EFI_MTFTP4_OPCODE_OACK or EFI_MTFTP4_OPCODE_ERROR packets during a call to
162 EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory().
163
164 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
165 @param Token The token that the caller provided in the
166 EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile()
167 or ReadDirectory() function.
168 @param PacketLen Indicates the length of the packet.
169 @param Packet Pointer to an MTFTPv4 packet.
170
171 @retval EFI_SUCCESS Operation sucess
172 @retval Others Abort transfer process
173
174 **/
175 typedef
176 EFI_STATUS
177 (EFIAPI *EFI_MTFTP4_CHECK_PACKET)(
178 IN EFI_MTFTP4_PROTOCOL *This,
179 IN EFI_MTFTP4_TOKEN *Token,
180 IN UINT16 PacketLen,
181 IN EFI_MTFTP4_PACKET *Paket
182 );
183
184 /**
185 Timeout callback funtion.
186
187 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
188 @param Token The token that is provided in the
189 EFI_MTFTP4_PROTOCOL.ReadFile() or
190 EFI_MTFTP4_PROTOCOL.WriteFile() or
191 EFI_MTFTP4_PROTOCOL.ReadDirectory() functions
192 by the caller.
193
194 @retval EFI_SUCCESS Operation sucess
195 @retval Others Aborts download process.
196
197 **/
198 typedef
199 EFI_STATUS
200 (EFIAPI *EFI_MTFTP4_TIMEOUT_CALLBACK)(
201 IN EFI_MTFTP4_PROTOCOL *This,
202 IN EFI_MTFTP4_TOKEN *Token
203 );
204
205 /**
206 a callback function that the caller provides to feed data to the
207 EFI_MTFTP4_PROTOCOL.WriteFile() function.
208
209 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
210 @param Token The token provided in the
211 EFI_MTFTP4_PROTOCOL.WriteFile() by the caller.
212 @param Length Indicates the length of the raw data wanted on input, and the
213 length the data available on output.
214 @param Buffer Pointer to the buffer where the data is stored.
215
216 @retval EFI_SUCCESS Operation sucess
217 @retval Others Aborts session.
218
219 **/
220 typedef
221 EFI_STATUS
222 (EFIAPI *EFI_MTFTP4_PACKET_NEEDED)(
223 IN EFI_MTFTP4_PROTOCOL *This,
224 IN EFI_MTFTP4_TOKEN *Token,
225 IN OUT UINT16 *Length,
226 OUT VOID **Buffer
227 );
228
229
230 /**
231 Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
232
233 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
234 @param ModeData Pointer to storage for the EFI MTFTPv4 Protocol driver mode data.
235
236 @retval EFI_SUCCESS The configuration data was successfully returned.
237 @retval EFI_OUT_OF_RESOURCES The required mode data could not be allocated.
238 @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
239
240 **/
241 typedef
242 EFI_STATUS
243 (EFIAPI *EFI_MTFTP4_GET_MODE_DATA)(
244 IN EFI_MTFTP4_PROTOCOL *This,
245 OUT EFI_MTFTP4_MODE_DATA *ModeData
246 );
247
248
249 /**
250 Initializes, changes, or resets the default operational setting for this
251 EFI MTFTPv4 Protocol driver instance.
252
253 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
254 @param MtftpConfigData Pointer to the configuration data structure.
255
256 @retval EFI_SUCCESS The EFI MTFTPv4 Protocol driver was configured successfully.
257 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
258 @retval EFI_ACCESS_DENIED The EFI configuration could not be changed at this time because
259 there is one MTFTP background operation in progress.
260 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
261 RARP, etc.) has not finished yet.
262 @retval EFI_UNSUPPORTED A configuration protocol (DHCP, BOOTP, RARP, etc.) could not
263 be located when clients choose to use the default address
264 settings.
265 @retval EFI_OUT_OF_RESOURCES The EFI MTFTPv4 Protocol driver instance data could not be
266 allocated.
267 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI
268 MTFTPv4 Protocol driver instance is not configured.
269
270 **/
271 typedef
272 EFI_STATUS
273 (EFIAPI *EFI_MTFTP4_CONFIGURE)(
274 IN EFI_MTFTP4_PROTOCOL *This,
275 IN EFI_MTFTP4_CONFIG_DATA *MtftpConfigData OPTIONAL
276 );
277
278
279 /**
280 Gets information about a file from an MTFTPv4 server.
281
282 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
283 @param OverrideData Data that is used to override the existing parameters. If NULL,
284 the default parameters that were set in the
285 EFI_MTFTP4_PROTOCOL.Configure() function are used.
286 @param Filename Pointer to ASCIIZ file name string.
287 @param ModeStr Pointer to ASCIIZ mode string. If NULL, "octet" will be used.
288 @param OptionCount Number of option/value string pairs in OptionList.
289 @param OptionList Pointer to array of option/value string pairs. Ignored if
290 OptionCount is zero.
291 @param PacketLength The number of bytes in the returned packet.
292 @param Packet The pointer to the received packet. This buffer must be freed by
293 the caller.
294
295 @retval EFI_SUCCESS An MTFTPv4 OACK packet was received and is in the Buffer.
296 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
297 @retval EFI_UNSUPPORTED One or more options in the OptionList are in the
298 unsupported list of structure EFI_MTFTP4_MODE_DATA.
299 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
300 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
301 RARP, etc.) has not finished yet.
302 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
303 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
304 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received and is in the buffer.
305 @retval EFI_ICMP_ERROR An ICMP ERROR packet was received and is in the Buffer.
306 @retval EFI_PROTOCOL_ERROR An unexpected MTFTPv4 packet was received and is in the buffer.
307 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
308 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
309
310 **/
311 typedef
312 EFI_STATUS
313 (EFIAPI *EFI_MTFTP4_GET_INFO)(
314 IN EFI_MTFTP4_PROTOCOL *This,
315 IN EFI_MTFTP4_OVERRIDE_DATA *OverrideData OPTIONAL,
316 IN UINT8 *Filename,
317 IN UINT8 *ModeStr OPTIONAL,
318 IN UINT8 OptionCount,
319 IN EFI_MTFTP4_OPTION *OptionList,
320 OUT UINT32 *PacketLength,
321 OUT EFI_MTFTP4_PACKET **Packet OPTIONAL
322 );
323
324 /**
325 Parses the options in an MTFTPv4 OACK packet.
326
327 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
328 @param PacketLen Length of the OACK packet to be parsed.
329 @param Packet Pointer to the OACK packet to be parsed.
330 @param OptionCount Pointer to the number of options in following OptionList.
331 @param OptionList Pointer to EFI_MTFTP4_OPTION storage. Call the EFI Boot
332 Service FreePool() to release each option if they are not
333 needed any more.
334
335 @retval EFI_SUCCESS The OACK packet was valid and the OptionCount and
336 OptionList parameters have been updated.
337 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
338 - PacketLen is 0.
339 - Packet is NULL or Packet is not a valid MTFTPv4 packet.
340 - OptionCount is NULL.
341 @retval EFI_NOT_FOUND No options were found in the OACK packet.
342 @retval EFI_OUT_OF_RESOURCES Storage for the OptionList array cannot be allocated.
343 @retval EFI_PROTOCOL_ERROR One or more of the option fields is invalid.
344
345 **/
346 typedef
347 EFI_STATUS
348 (EFIAPI *EFI_MTFTP4_PARSE_OPTIONS)(
349 IN EFI_MTFTP4_PROTOCOL *This,
350 IN UINT32 PacketLen,
351 IN EFI_MTFTP4_PACKET *Packet,
352 OUT UINT32 *OptionCount,
353 OUT EFI_MTFTP4_OPTION **OptionList OPTIONAL
354 );
355
356
357 /**
358 Downloads a file from an MTFTPv4 server.
359
360 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
361 @param Token Pointer to the token structure to provide the parameters that are
362 used in this operation.
363
364 @retval EFI_SUCCESS The data file has been transferred successfully.
365 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
366 @retval EFI_BUFFER_TOO_SMALL BufferSize is not large enough to hold the downloaded data
367 in downloading process.
368 @retval EFI_ABORTED Current operation is aborted by user.
369 @retval EFI_ICMP_ERROR An ICMP ERROR packet was received.
370 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
371 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received.
372 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
373
374 **/
375 typedef
376 EFI_STATUS
377 (EFIAPI *EFI_MTFTP4_READ_FILE)(
378 IN EFI_MTFTP4_PROTOCOL *This,
379 IN EFI_MTFTP4_TOKEN *Token
380 );
381
382
383
384 /**
385 Sends a file to an MTFTPv4 server.
386
387 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
388 @param Token Pointer to the token structure to provide the parameters that are
389 used in this operation.
390
391 @retval EFI_SUCCESS The upload session has started.
392 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
393 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
394 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in
395 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
396 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
397 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
398 RARP, etc.) is not finished yet.
399 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4 session.
400 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
401 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
402 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
403
404 **/
405 typedef
406 EFI_STATUS
407 (EFIAPI *EFI_MTFTP4_WRITE_FILE)(
408 IN EFI_MTFTP4_PROTOCOL *This,
409 IN EFI_MTFTP4_TOKEN *Token
410 );
411
412
413 /**
414 Downloads a data file "directory" from an MTFTPv4 server. May be unsupported in some EFI
415 implementations.
416
417 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
418 @param Token Pointer to the token structure to provide the parameters that are
419 used in this operation.
420
421 @retval EFI_SUCCESS The MTFTPv4 related file "directory" has been downloaded.
422 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
423 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
424 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in
425 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
426 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
427 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
428 RARP, etc.) is not finished yet.
429 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4 session.
430 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
431 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
432 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
433
434 **/
435 typedef
436 EFI_STATUS
437 (EFIAPI *EFI_MTFTP4_READ_DIRECTORY)(
438 IN EFI_MTFTP4_PROTOCOL *This,
439 IN EFI_MTFTP4_TOKEN *Token
440 );
441
442 /**
443 Polls for incoming data packets and processes outgoing data packets.
444
445 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
446
447 @retval EFI_SUCCESS Incoming or outgoing data was processed.
448 @retval EFI_NOT_STARTED This EFI MTFTPv4 Protocol instance has not been started.
449 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
450 RARP, etc.) is not finished yet.
451 @retval EFI_INVALID_PARAMETER This is NULL.
452 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
453 @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue.
454 Consider increasing the polling rate.
455
456 **/
457 typedef
458 EFI_STATUS
459 (EFIAPI *EFI_MTFTP4_POLL)(
460 IN EFI_MTFTP4_PROTOCOL *This
461 );
462
463 ///
464 /// The EFI_MTFTP4_PROTOCOL is designed to be used by UEFI drivers and applications
465 /// to transmit and receive data files. The EFI MTFTPv4 Protocol driver uses
466 /// the underlying EFI UDPv4 Protocol driver and EFI IPv4 Protocol driver.
467 ///
468 struct _EFI_MTFTP4_PROTOCOL {
469 EFI_MTFTP4_GET_MODE_DATA GetModeData;
470 EFI_MTFTP4_CONFIGURE Configure;
471 EFI_MTFTP4_GET_INFO GetInfo;
472 EFI_MTFTP4_PARSE_OPTIONS ParseOptions;
473 EFI_MTFTP4_READ_FILE ReadFile;
474 EFI_MTFTP4_WRITE_FILE WriteFile;
475 EFI_MTFTP4_READ_DIRECTORY ReadDirectory;
476 EFI_MTFTP4_POLL Poll;
477 };
478
479 struct _EFI_MTFTP4_TOKEN {
480 EFI_STATUS Status;
481 EFI_EVENT Event;
482 EFI_MTFTP4_OVERRIDE_DATA *OverrideData;
483 UINT8 *Filename;
484 UINT8 *ModeStr;
485 UINT32 OptionCount;
486 EFI_MTFTP4_OPTION *OptionList;
487 OUT UINT64 BufferSize;
488 OUT VOID *Buffer;
489 EFI_MTFTP4_CHECK_PACKET CheckPacket;
490 EFI_MTFTP4_TIMEOUT_CALLBACK TimeoutCallback;
491 EFI_MTFTP4_PACKET_NEEDED PacketNeeded;
492 };
493
494 extern EFI_GUID gEfiMtftp4ServiceBindingProtocolGuid;
495 extern EFI_GUID gEfiMtftp4ProtocolGuid;
496
497 #endif
498