2 EFI Multicast Trivial File Transfer Protocol Definition
4 Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials are licensed and made available under
6 the terms and conditions of the BSD License that accompanies this distribution.
7 The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php.
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.
13 @par Revision Reference:
14 This Protocol is introduced in UEFI Specification 2.0
18 #ifndef __EFI_MTFTP4_PROTOCOL_H__
19 #define __EFI_MTFTP4_PROTOCOL_H__
21 #define EFI_MTFTP4_SERVICE_BINDING_PROTOCOL_GUID \
23 0x2FE800BE, 0x8F01, 0x4aa6, {0x94, 0x6B, 0xD7, 0x13, 0x88, 0xE1, 0x83, 0x3F } \
26 #define EFI_MTFTP4_PROTOCOL_GUID \
28 0x78247c57, 0x63db, 0x4708, {0x99, 0xc2, 0xa8, 0xb4, 0xa9, 0xa6, 0x1f, 0x6b } \
31 typedef struct _EFI_MTFTP4_PROTOCOL EFI_MTFTP4_PROTOCOL
;
32 typedef struct _EFI_MTFTP4_TOKEN EFI_MTFTP4_TOKEN
;
35 //MTFTP4 packet opcode definition
37 #define EFI_MTFTP4_OPCODE_RRQ 1
38 #define EFI_MTFTP4_OPCODE_WRQ 2
39 #define EFI_MTFTP4_OPCODE_DATA 3
40 #define EFI_MTFTP4_OPCODE_ACK 4
41 #define EFI_MTFTP4_OPCODE_ERROR 5
42 #define EFI_MTFTP4_OPCODE_OACK 6
43 #define EFI_MTFTP4_OPCODE_DIR 7
44 #define EFI_MTFTP4_OPCODE_DATA8 8
45 #define EFI_MTFTP4_OPCODE_ACK8 9
48 // MTFTP4 error code definition
50 #define EFI_MTFTP4_ERRORCODE_NOT_DEFINED 0
51 #define EFI_MTFTP4_ERRORCODE_FILE_NOT_FOUND 1
52 #define EFI_MTFTP4_ERRORCODE_ACCESS_VIOLATION 2
53 #define EFI_MTFTP4_ERRORCODE_DISK_FULL 3
54 #define EFI_MTFTP4_ERRORCODE_ILLEGAL_OPERATION 4
55 #define EFI_MTFTP4_ERRORCODE_UNKNOWN_TRANSFER_ID 5
56 #define EFI_MTFTP4_ERRORCODE_FILE_ALREADY_EXISTS 6
57 #define EFI_MTFTP4_ERRORCODE_NO_SUCH_USER 7
58 #define EFI_MTFTP4_ERRORCODE_REQUEST_DENIED 8
61 // MTFTP4 pacekt definitions
68 } EFI_MTFTP4_REQ_HEADER
;
73 } EFI_MTFTP4_OACK_HEADER
;
79 } EFI_MTFTP4_DATA_HEADER
;
84 } EFI_MTFTP4_ACK_HEADER
;
90 } EFI_MTFTP4_DATA8_HEADER
;
95 } EFI_MTFTP4_ACK8_HEADER
;
100 UINT8 ErrorMessage
[1];
101 } EFI_MTFTP4_ERROR_HEADER
;
105 /// Type of packets as defined by the MTFTPv4 packet opcodes.
109 /// Read request packet header.
111 EFI_MTFTP4_REQ_HEADER Rrq
;
113 /// Write request packet header.
115 EFI_MTFTP4_REQ_HEADER Wrq
;
117 /// Option acknowledge packet header.
119 EFI_MTFTP4_OACK_HEADER Oack
;
121 /// Data packet header.
123 EFI_MTFTP4_DATA_HEADER Data
;
125 /// Acknowledgement packet header.
127 EFI_MTFTP4_ACK_HEADER Ack
;
129 /// Data packet header with big block number.
131 EFI_MTFTP4_DATA8_HEADER Data8
;
133 /// Acknowledgement header with big block num.
135 EFI_MTFTP4_ACK8_HEADER Ack8
;
137 /// Error packet header.
139 EFI_MTFTP4_ERROR_HEADER Error
;
145 /// MTFTP4 option definition.
154 BOOLEAN UseDefaultSetting
;
155 EFI_IPv4_ADDRESS StationIp
;
156 EFI_IPv4_ADDRESS SubnetMask
;
158 EFI_IPv4_ADDRESS GatewayIp
;
159 EFI_IPv4_ADDRESS ServerIp
;
160 UINT16 InitialServerPort
;
163 } EFI_MTFTP4_CONFIG_DATA
;
167 EFI_MTFTP4_CONFIG_DATA ConfigData
;
168 UINT8 SupportedOptionCount
;
169 UINT8
**SupportedOptoins
;
170 UINT8 UnsupportedOptionCount
;
171 UINT8
**UnsupportedOptoins
;
172 } EFI_MTFTP4_MODE_DATA
;
176 EFI_IPv4_ADDRESS GatewayIp
;
177 EFI_IPv4_ADDRESS ServerIp
;
181 } EFI_MTFTP4_OVERRIDE_DATA
;
184 // Protocol interfaces definition
188 A callback function that is provided by the caller to intercept
189 the EFI_MTFTP4_OPCODE_DATA or EFI_MTFTP4_OPCODE_DATA8 packets processed in the
190 EFI_MTFTP4_PROTOCOL.ReadFile() function, and alternatively to intercept
191 EFI_MTFTP4_OPCODE_OACK or EFI_MTFTP4_OPCODE_ERROR packets during a call to
192 EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory().
194 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
195 @param Token The token that the caller provided in the
196 EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile()
197 or ReadDirectory() function.
198 @param PacketLen Indicates the length of the packet.
199 @param Packet The pointer to an MTFTPv4 packet.
201 @retval EFI_SUCCESS The operation was successful.
202 @retval Others Aborts the transfer process.
207 (EFIAPI
*EFI_MTFTP4_CHECK_PACKET
)(
208 IN EFI_MTFTP4_PROTOCOL
*This
,
209 IN EFI_MTFTP4_TOKEN
*Token
,
211 IN EFI_MTFTP4_PACKET
*Paket
215 Timeout callback function.
217 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
218 @param Token The token that is provided in the
219 EFI_MTFTP4_PROTOCOL.ReadFile() or
220 EFI_MTFTP4_PROTOCOL.WriteFile() or
221 EFI_MTFTP4_PROTOCOL.ReadDirectory() functions
224 @retval EFI_SUCCESS The operation was successful.
225 @retval Others Aborts download process.
230 (EFIAPI
*EFI_MTFTP4_TIMEOUT_CALLBACK
)(
231 IN EFI_MTFTP4_PROTOCOL
*This
,
232 IN EFI_MTFTP4_TOKEN
*Token
236 A callback function that the caller provides to feed data to the
237 EFI_MTFTP4_PROTOCOL.WriteFile() function.
239 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
240 @param Token The token provided in the
241 EFI_MTFTP4_PROTOCOL.WriteFile() by the caller.
242 @param Length Indicates the length of the raw data wanted on input, and the
243 length the data available on output.
244 @param Buffer The pointer to the buffer where the data is stored.
246 @retval EFI_SUCCESS The operation was successful.
247 @retval Others Aborts session.
252 (EFIAPI
*EFI_MTFTP4_PACKET_NEEDED
)(
253 IN EFI_MTFTP4_PROTOCOL
*This
,
254 IN EFI_MTFTP4_TOKEN
*Token
,
255 IN OUT UINT16
*Length
,
261 Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
263 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
264 @param ModeData The pointer to storage for the EFI MTFTPv4 Protocol driver mode data.
266 @retval EFI_SUCCESS The configuration data was successfully returned.
267 @retval EFI_OUT_OF_RESOURCES The required mode data could not be allocated.
268 @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
273 (EFIAPI
*EFI_MTFTP4_GET_MODE_DATA
)(
274 IN EFI_MTFTP4_PROTOCOL
*This
,
275 OUT EFI_MTFTP4_MODE_DATA
*ModeData
280 Initializes, changes, or resets the default operational setting for this
281 EFI MTFTPv4 Protocol driver instance.
283 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
284 @param MtftpConfigData The pointer to the configuration data structure.
286 @retval EFI_SUCCESS The EFI MTFTPv4 Protocol driver was configured successfully.
287 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
288 @retval EFI_ACCESS_DENIED The EFI configuration could not be changed at this time because
289 there is one MTFTP background operation in progress.
290 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
291 RARP, etc.) has not finished yet.
292 @retval EFI_UNSUPPORTED A configuration protocol (DHCP, BOOTP, RARP, etc.) could not
293 be located when clients choose to use the default address
295 @retval EFI_OUT_OF_RESOURCES The EFI MTFTPv4 Protocol driver instance data could not be
297 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI
298 MTFTPv4 Protocol driver instance is not configured.
303 (EFIAPI
*EFI_MTFTP4_CONFIGURE
)(
304 IN EFI_MTFTP4_PROTOCOL
*This
,
305 IN EFI_MTFTP4_CONFIG_DATA
*MtftpConfigData OPTIONAL
310 Gets information about a file from an MTFTPv4 server.
312 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
313 @param OverrideData Data that is used to override the existing parameters. If NULL,
314 the default parameters that were set in the
315 EFI_MTFTP4_PROTOCOL.Configure() function are used.
316 @param Filename The pointer to null-terminated ASCII file name string.
317 @param ModeStr The pointer to null-terminated ASCII mode string. If NULL, "octet" will be used.
318 @param OptionCount Number of option/value string pairs in OptionList.
319 @param OptionList The pointer to array of option/value string pairs. Ignored if
321 @param PacketLength The number of bytes in the returned packet.
322 @param Packet The pointer to the received packet. This buffer must be freed by
325 @retval EFI_SUCCESS An MTFTPv4 OACK packet was received and is in the Packet.
326 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
329 - OptionCount is not zero and OptionList is NULL.
330 - One or more options in OptionList have wrong format.
331 - PacketLength is NULL.
332 - One or more IPv4 addresses in OverrideData are not valid
333 unicast IPv4 addresses if OverrideData is not NULL.
334 @retval EFI_UNSUPPORTED One or more options in the OptionList are in the
335 unsupported list of structure EFI_MTFTP4_MODE_DATA.
336 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
337 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
338 RARP, etc.) has not finished yet.
339 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
340 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
341 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received and is in the Packet.
342 @retval EFI_NETWORK_UNREACHABLE An ICMP network unreachable error packet was received and the Packet is set to NULL.
343 @retval EFI_HOST_UNREACHABLE An ICMP host unreachable error packet was received and the Packet is set to NULL.
344 @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received and the Packet is set to NULL.
345 @retval EFI_PORT_UNREACHABLE An ICMP port unreachable error packet was received and the Packet is set to NULL.
346 @retval EFI_ICMP_ERROR Some other ICMP ERROR packet was received and is in the Buffer.
347 @retval EFI_PROTOCOL_ERROR An unexpected MTFTPv4 packet was received and is in the Packet.
348 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
349 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
350 @retval EFI_NO_MEDIA There was a media error.
355 (EFIAPI
*EFI_MTFTP4_GET_INFO
)(
356 IN EFI_MTFTP4_PROTOCOL
*This
,
357 IN EFI_MTFTP4_OVERRIDE_DATA
*OverrideData OPTIONAL
,
359 IN UINT8
*ModeStr OPTIONAL
,
360 IN UINT8 OptionCount
,
361 IN EFI_MTFTP4_OPTION
*OptionList
,
362 OUT UINT32
*PacketLength
,
363 OUT EFI_MTFTP4_PACKET
**Packet OPTIONAL
367 Parses the options in an MTFTPv4 OACK packet.
369 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
370 @param PacketLen Length of the OACK packet to be parsed.
371 @param Packet The pointer to the OACK packet to be parsed.
372 @param OptionCount The pointer to the number of options in following OptionList.
373 @param OptionList The pointer to EFI_MTFTP4_OPTION storage. Call the EFI Boot
374 Service FreePool() to release the OptionList if the options
375 in this OptionList are not needed any more.
377 @retval EFI_SUCCESS The OACK packet was valid and the OptionCount and
378 OptionList parameters have been updated.
379 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
381 - Packet is NULL or Packet is not a valid MTFTPv4 packet.
382 - OptionCount is NULL.
383 @retval EFI_NOT_FOUND No options were found in the OACK packet.
384 @retval EFI_OUT_OF_RESOURCES Storage for the OptionList array cannot be allocated.
385 @retval EFI_PROTOCOL_ERROR One or more of the option fields is invalid.
390 (EFIAPI
*EFI_MTFTP4_PARSE_OPTIONS
)(
391 IN EFI_MTFTP4_PROTOCOL
*This
,
393 IN EFI_MTFTP4_PACKET
*Packet
,
394 OUT UINT32
*OptionCount
,
395 OUT EFI_MTFTP4_OPTION
**OptionList OPTIONAL
400 Downloads a file from an MTFTPv4 server.
402 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
403 @param Token The pointer to the token structure to provide the parameters that are
404 used in this operation.
406 @retval EFI_SUCCESS The data file has been transferred successfully.
407 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
408 @retval EFI_BUFFER_TOO_SMALL BufferSize is not zero but not large enough to hold the
409 downloaded data in downloading process.
410 @retval EFI_ABORTED Current operation is aborted by user.
411 @retval EFI_NETWORK_UNREACHABLE An ICMP network unreachable error packet was received.
412 @retval EFI_HOST_UNREACHABLE An ICMP host unreachable error packet was received.
413 @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received.
414 @retval EFI_PORT_UNREACHABLE An ICMP port unreachable error packet was received.
415 @retval EFI_ICMP_ERROR Some other ICMP ERROR packet was received.
416 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
417 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received.
418 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
419 @retval EFI_NO_MEDIA There was a media error.
424 (EFIAPI
*EFI_MTFTP4_READ_FILE
)(
425 IN EFI_MTFTP4_PROTOCOL
*This
,
426 IN EFI_MTFTP4_TOKEN
*Token
432 Sends a file to an MTFTPv4 server.
434 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
435 @param Token The pointer to the token structure to provide the parameters that are
436 used in this operation.
438 @retval EFI_SUCCESS The upload session has started.
439 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
440 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
441 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in
442 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
443 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
444 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
445 RARP, etc.) is not finished yet.
446 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4 session.
447 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
448 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
449 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
454 (EFIAPI
*EFI_MTFTP4_WRITE_FILE
)(
455 IN EFI_MTFTP4_PROTOCOL
*This
,
456 IN EFI_MTFTP4_TOKEN
*Token
461 Downloads a data file "directory" from an MTFTPv4 server. May be unsupported in some EFI
464 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
465 @param Token The pointer to the token structure to provide the parameters that are
466 used in this operation.
468 @retval EFI_SUCCESS The MTFTPv4 related file "directory" has been downloaded.
469 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
470 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
471 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in
472 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
473 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
474 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
475 RARP, etc.) is not finished yet.
476 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4 session.
477 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
478 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
479 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
484 (EFIAPI
*EFI_MTFTP4_READ_DIRECTORY
)(
485 IN EFI_MTFTP4_PROTOCOL
*This
,
486 IN EFI_MTFTP4_TOKEN
*Token
490 Polls for incoming data packets and processes outgoing data packets.
492 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
494 @retval EFI_SUCCESS Incoming or outgoing data was processed.
495 @retval EFI_NOT_STARTED This EFI MTFTPv4 Protocol instance has not been started.
496 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
497 RARP, etc.) is not finished yet.
498 @retval EFI_INVALID_PARAMETER This is NULL.
499 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
500 @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue.
501 Consider increasing the polling rate.
506 (EFIAPI
*EFI_MTFTP4_POLL
)(
507 IN EFI_MTFTP4_PROTOCOL
*This
511 /// The EFI_MTFTP4_PROTOCOL is designed to be used by UEFI drivers and applications
512 /// to transmit and receive data files. The EFI MTFTPv4 Protocol driver uses
513 /// the underlying EFI UDPv4 Protocol driver and EFI IPv4 Protocol driver.
515 struct _EFI_MTFTP4_PROTOCOL
{
516 EFI_MTFTP4_GET_MODE_DATA GetModeData
;
517 EFI_MTFTP4_CONFIGURE Configure
;
518 EFI_MTFTP4_GET_INFO GetInfo
;
519 EFI_MTFTP4_PARSE_OPTIONS ParseOptions
;
520 EFI_MTFTP4_READ_FILE ReadFile
;
521 EFI_MTFTP4_WRITE_FILE WriteFile
;
522 EFI_MTFTP4_READ_DIRECTORY ReadDirectory
;
523 EFI_MTFTP4_POLL Poll
;
526 struct _EFI_MTFTP4_TOKEN
{
528 /// The status that is returned to the caller at the end of the operation
529 /// to indicate whether this operation completed successfully.
533 /// The event that will be signaled when the operation completes. If
534 /// set to NULL, the corresponding function will wait until the read or
535 /// write operation finishes. The type of Event must be
536 /// EVT_NOTIFY_SIGNAL. The Task Priority Level (TPL) of
537 /// Event must be lower than or equal to TPL_CALLBACK.
541 /// If not NULL, the data that will be used to override the existing configure data.
543 EFI_MTFTP4_OVERRIDE_DATA
*OverrideData
;
545 /// The pointer to the null-terminated ASCII file name string.
549 /// The pointer to the null-terminated ASCII mode string. If NULL, "octet" is used.
553 /// Number of option/value string pairs.
557 /// The pointer to an array of option/value string pairs. Ignored if OptionCount is zero.
559 EFI_MTFTP4_OPTION
*OptionList
;
561 /// The size of the data buffer.
565 /// The pointer to the data buffer. Data that is downloaded from the
566 /// MTFTPv4 server is stored here. Data that is uploaded to the
567 /// MTFTPv4 server is read from here. Ignored if BufferSize is zero.
571 /// The pointer to the context that will be used by CheckPacket,
572 /// TimeoutCallback and PacketNeeded.
576 /// The pointer to the callback function to check the contents of the received packet.
578 EFI_MTFTP4_CHECK_PACKET CheckPacket
;
580 /// The pointer to the function to be called when a timeout occurs.
582 EFI_MTFTP4_TIMEOUT_CALLBACK TimeoutCallback
;
584 /// The pointer to the function to provide the needed packet contents.
586 EFI_MTFTP4_PACKET_NEEDED PacketNeeded
;
589 extern EFI_GUID gEfiMtftp4ServiceBindingProtocolGuid
;
590 extern EFI_GUID gEfiMtftp4ProtocolGuid
;