2 EFI Multicast Trivial File Transfer Protocol Definition
4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
7 @par Revision Reference:
8 This Protocol is introduced in UEFI Specification 2.0
12 #ifndef __EFI_MTFTP4_PROTOCOL_H__
13 #define __EFI_MTFTP4_PROTOCOL_H__
15 #define EFI_MTFTP4_SERVICE_BINDING_PROTOCOL_GUID \
17 0x2FE800BE, 0x8F01, 0x4aa6, {0x94, 0x6B, 0xD7, 0x13, 0x88, 0xE1, 0x83, 0x3F } \
20 #define EFI_MTFTP4_PROTOCOL_GUID \
22 0x78247c57, 0x63db, 0x4708, {0x99, 0xc2, 0xa8, 0xb4, 0xa9, 0xa6, 0x1f, 0x6b } \
25 typedef struct _EFI_MTFTP4_PROTOCOL EFI_MTFTP4_PROTOCOL
;
26 typedef struct _EFI_MTFTP4_TOKEN EFI_MTFTP4_TOKEN
;
29 // MTFTP4 packet opcode definition
31 #define EFI_MTFTP4_OPCODE_RRQ 1
32 #define EFI_MTFTP4_OPCODE_WRQ 2
33 #define EFI_MTFTP4_OPCODE_DATA 3
34 #define EFI_MTFTP4_OPCODE_ACK 4
35 #define EFI_MTFTP4_OPCODE_ERROR 5
36 #define EFI_MTFTP4_OPCODE_OACK 6
37 #define EFI_MTFTP4_OPCODE_DIR 7
38 #define EFI_MTFTP4_OPCODE_DATA8 8
39 #define EFI_MTFTP4_OPCODE_ACK8 9
42 // MTFTP4 error code definition
44 #define EFI_MTFTP4_ERRORCODE_NOT_DEFINED 0
45 #define EFI_MTFTP4_ERRORCODE_FILE_NOT_FOUND 1
46 #define EFI_MTFTP4_ERRORCODE_ACCESS_VIOLATION 2
47 #define EFI_MTFTP4_ERRORCODE_DISK_FULL 3
48 #define EFI_MTFTP4_ERRORCODE_ILLEGAL_OPERATION 4
49 #define EFI_MTFTP4_ERRORCODE_UNKNOWN_TRANSFER_ID 5
50 #define EFI_MTFTP4_ERRORCODE_FILE_ALREADY_EXISTS 6
51 #define EFI_MTFTP4_ERRORCODE_NO_SUCH_USER 7
52 #define EFI_MTFTP4_ERRORCODE_REQUEST_DENIED 8
55 // MTFTP4 pacekt definitions
62 } EFI_MTFTP4_REQ_HEADER
;
67 } EFI_MTFTP4_OACK_HEADER
;
73 } EFI_MTFTP4_DATA_HEADER
;
78 } EFI_MTFTP4_ACK_HEADER
;
84 } EFI_MTFTP4_DATA8_HEADER
;
89 } EFI_MTFTP4_ACK8_HEADER
;
94 UINT8 ErrorMessage
[1];
95 } EFI_MTFTP4_ERROR_HEADER
;
99 /// Type of packets as defined by the MTFTPv4 packet opcodes.
103 /// Read request packet header.
105 EFI_MTFTP4_REQ_HEADER Rrq
;
107 /// Write request packet header.
109 EFI_MTFTP4_REQ_HEADER Wrq
;
111 /// Option acknowledge packet header.
113 EFI_MTFTP4_OACK_HEADER Oack
;
115 /// Data packet header.
117 EFI_MTFTP4_DATA_HEADER Data
;
119 /// Acknowledgement packet header.
121 EFI_MTFTP4_ACK_HEADER Ack
;
123 /// Data packet header with big block number.
125 EFI_MTFTP4_DATA8_HEADER Data8
;
127 /// Acknowledgement header with big block num.
129 EFI_MTFTP4_ACK8_HEADER Ack8
;
131 /// Error packet header.
133 EFI_MTFTP4_ERROR_HEADER Error
;
139 /// MTFTP4 option definition.
147 BOOLEAN UseDefaultSetting
;
148 EFI_IPv4_ADDRESS StationIp
;
149 EFI_IPv4_ADDRESS SubnetMask
;
151 EFI_IPv4_ADDRESS GatewayIp
;
152 EFI_IPv4_ADDRESS ServerIp
;
153 UINT16 InitialServerPort
;
156 } EFI_MTFTP4_CONFIG_DATA
;
159 EFI_MTFTP4_CONFIG_DATA ConfigData
;
160 UINT8 SupportedOptionCount
;
161 UINT8
**SupportedOptoins
;
162 UINT8 UnsupportedOptionCount
;
163 UINT8
**UnsupportedOptoins
;
164 } EFI_MTFTP4_MODE_DATA
;
167 EFI_IPv4_ADDRESS GatewayIp
;
168 EFI_IPv4_ADDRESS ServerIp
;
172 } EFI_MTFTP4_OVERRIDE_DATA
;
175 // Protocol interfaces definition
179 A callback function that is provided by the caller to intercept
180 the EFI_MTFTP4_OPCODE_DATA or EFI_MTFTP4_OPCODE_DATA8 packets processed in the
181 EFI_MTFTP4_PROTOCOL.ReadFile() function, and alternatively to intercept
182 EFI_MTFTP4_OPCODE_OACK or EFI_MTFTP4_OPCODE_ERROR packets during a call to
183 EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory().
185 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
186 @param Token The token that the caller provided in the
187 EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile()
188 or ReadDirectory() function.
189 @param PacketLen Indicates the length of the packet.
190 @param Packet The pointer to an MTFTPv4 packet.
192 @retval EFI_SUCCESS The operation was successful.
193 @retval Others Aborts the transfer process.
198 (EFIAPI
*EFI_MTFTP4_CHECK_PACKET
)(
199 IN EFI_MTFTP4_PROTOCOL
*This
,
200 IN EFI_MTFTP4_TOKEN
*Token
,
202 IN EFI_MTFTP4_PACKET
*Paket
206 Timeout callback function.
208 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
209 @param Token The token that is provided in the
210 EFI_MTFTP4_PROTOCOL.ReadFile() or
211 EFI_MTFTP4_PROTOCOL.WriteFile() or
212 EFI_MTFTP4_PROTOCOL.ReadDirectory() functions
215 @retval EFI_SUCCESS The operation was successful.
216 @retval Others Aborts download process.
221 (EFIAPI
*EFI_MTFTP4_TIMEOUT_CALLBACK
)(
222 IN EFI_MTFTP4_PROTOCOL
*This
,
223 IN EFI_MTFTP4_TOKEN
*Token
227 A callback function that the caller provides to feed data to the
228 EFI_MTFTP4_PROTOCOL.WriteFile() function.
230 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
231 @param Token The token provided in the
232 EFI_MTFTP4_PROTOCOL.WriteFile() by the caller.
233 @param Length Indicates the length of the raw data wanted on input, and the
234 length the data available on output.
235 @param Buffer The pointer to the buffer where the data is stored.
237 @retval EFI_SUCCESS The operation was successful.
238 @retval Others Aborts session.
243 (EFIAPI
*EFI_MTFTP4_PACKET_NEEDED
)(
244 IN EFI_MTFTP4_PROTOCOL
*This
,
245 IN EFI_MTFTP4_TOKEN
*Token
,
246 IN OUT UINT16
*Length
,
251 Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
253 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
254 @param ModeData The pointer to storage for the EFI MTFTPv4 Protocol driver mode data.
256 @retval EFI_SUCCESS The configuration data was successfully returned.
257 @retval EFI_OUT_OF_RESOURCES The required mode data could not be allocated.
258 @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
263 (EFIAPI
*EFI_MTFTP4_GET_MODE_DATA
)(
264 IN EFI_MTFTP4_PROTOCOL
*This
,
265 OUT EFI_MTFTP4_MODE_DATA
*ModeData
269 Initializes, changes, or resets the default operational setting for this
270 EFI MTFTPv4 Protocol driver instance.
272 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
273 @param MtftpConfigData The pointer to the configuration data structure.
275 @retval EFI_SUCCESS The EFI MTFTPv4 Protocol driver was configured successfully.
276 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
277 @retval EFI_ACCESS_DENIED The EFI configuration could not be changed at this time because
278 there is one MTFTP background operation in progress.
279 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
280 RARP, etc.) has not finished yet.
281 @retval EFI_UNSUPPORTED A configuration protocol (DHCP, BOOTP, RARP, etc.) could not
282 be located when clients choose to use the default address
284 @retval EFI_OUT_OF_RESOURCES The EFI MTFTPv4 Protocol driver instance data could not be
286 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI
287 MTFTPv4 Protocol driver instance is not configured.
292 (EFIAPI
*EFI_MTFTP4_CONFIGURE
)(
293 IN EFI_MTFTP4_PROTOCOL
*This
,
294 IN EFI_MTFTP4_CONFIG_DATA
*MtftpConfigData OPTIONAL
298 Gets information about a file from an MTFTPv4 server.
300 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
301 @param OverrideData Data that is used to override the existing parameters. If NULL,
302 the default parameters that were set in the
303 EFI_MTFTP4_PROTOCOL.Configure() function are used.
304 @param Filename The pointer to null-terminated ASCII file name string.
305 @param ModeStr The pointer to null-terminated ASCII mode string. If NULL, "octet" will be used.
306 @param OptionCount Number of option/value string pairs in OptionList.
307 @param OptionList The pointer to array of option/value string pairs. Ignored if
309 @param PacketLength The number of bytes in the returned packet.
310 @param Packet The pointer to the received packet. This buffer must be freed by
313 @retval EFI_SUCCESS An MTFTPv4 OACK packet was received and is in the Packet.
314 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
317 - OptionCount is not zero and OptionList is NULL.
318 - One or more options in OptionList have wrong format.
319 - PacketLength is NULL.
320 - One or more IPv4 addresses in OverrideData are not valid
321 unicast IPv4 addresses if OverrideData is not NULL.
322 @retval EFI_UNSUPPORTED One or more options in the OptionList are in the
323 unsupported list of structure EFI_MTFTP4_MODE_DATA.
324 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
325 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
326 RARP, etc.) has not finished yet.
327 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
328 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
329 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received and is in the Packet.
330 @retval EFI_NETWORK_UNREACHABLE An ICMP network unreachable error packet was received and the Packet is set to NULL.
331 @retval EFI_HOST_UNREACHABLE An ICMP host unreachable error packet was received and the Packet is set to NULL.
332 @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received and the Packet is set to NULL.
333 @retval EFI_PORT_UNREACHABLE An ICMP port unreachable error packet was received and the Packet is set to NULL.
334 @retval EFI_ICMP_ERROR Some other ICMP ERROR packet was received and is in the Buffer.
335 @retval EFI_PROTOCOL_ERROR An unexpected MTFTPv4 packet was received and is in the Packet.
336 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
337 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
338 @retval EFI_NO_MEDIA There was a media error.
343 (EFIAPI
*EFI_MTFTP4_GET_INFO
)(
344 IN EFI_MTFTP4_PROTOCOL
*This
,
345 IN EFI_MTFTP4_OVERRIDE_DATA
*OverrideData OPTIONAL
,
347 IN UINT8
*ModeStr OPTIONAL
,
348 IN UINT8 OptionCount
,
349 IN EFI_MTFTP4_OPTION
*OptionList
,
350 OUT UINT32
*PacketLength
,
351 OUT EFI_MTFTP4_PACKET
**Packet OPTIONAL
355 Parses the options in an MTFTPv4 OACK packet.
357 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
358 @param PacketLen Length of the OACK packet to be parsed.
359 @param Packet The pointer to the OACK packet to be parsed.
360 @param OptionCount The pointer to the number of options in following OptionList.
361 @param OptionList The pointer to EFI_MTFTP4_OPTION storage. Call the EFI Boot
362 Service FreePool() to release the OptionList if the options
363 in this OptionList are not needed any more.
365 @retval EFI_SUCCESS The OACK packet was valid and the OptionCount and
366 OptionList parameters have been updated.
367 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
369 - Packet is NULL or Packet is not a valid MTFTPv4 packet.
370 - OptionCount is NULL.
371 @retval EFI_NOT_FOUND No options were found in the OACK packet.
372 @retval EFI_OUT_OF_RESOURCES Storage for the OptionList array cannot be allocated.
373 @retval EFI_PROTOCOL_ERROR One or more of the option fields is invalid.
378 (EFIAPI
*EFI_MTFTP4_PARSE_OPTIONS
)(
379 IN EFI_MTFTP4_PROTOCOL
*This
,
381 IN EFI_MTFTP4_PACKET
*Packet
,
382 OUT UINT32
*OptionCount
,
383 OUT EFI_MTFTP4_OPTION
**OptionList OPTIONAL
387 Downloads a file from an MTFTPv4 server.
389 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
390 @param Token The pointer to the token structure to provide the parameters that are
391 used in this operation.
393 @retval EFI_SUCCESS The data file has been transferred successfully.
394 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
395 @retval EFI_BUFFER_TOO_SMALL BufferSize is not zero but not large enough to hold the
396 downloaded data in downloading process.
397 @retval EFI_ABORTED Current operation is aborted by user.
398 @retval EFI_NETWORK_UNREACHABLE An ICMP network unreachable error packet was received.
399 @retval EFI_HOST_UNREACHABLE An ICMP host unreachable error packet was received.
400 @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received.
401 @retval EFI_PORT_UNREACHABLE An ICMP port unreachable error packet was received.
402 @retval EFI_ICMP_ERROR Some other ICMP ERROR packet was received.
403 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
404 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received.
405 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
406 @retval EFI_NO_MEDIA There was a media error.
411 (EFIAPI
*EFI_MTFTP4_READ_FILE
)(
412 IN EFI_MTFTP4_PROTOCOL
*This
,
413 IN EFI_MTFTP4_TOKEN
*Token
417 Sends a file to an MTFTPv4 server.
419 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
420 @param Token The pointer to the token structure to provide the parameters that are
421 used in this operation.
423 @retval EFI_SUCCESS The upload session has started.
424 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
425 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
426 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in
427 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
428 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
429 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
430 RARP, etc.) is not finished yet.
431 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4 session.
432 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
433 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
434 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
439 (EFIAPI
*EFI_MTFTP4_WRITE_FILE
)(
440 IN EFI_MTFTP4_PROTOCOL
*This
,
441 IN EFI_MTFTP4_TOKEN
*Token
445 Downloads a data file "directory" from an MTFTPv4 server. May be unsupported in some EFI
448 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
449 @param Token The pointer to the token structure to provide the parameters that are
450 used in this operation.
452 @retval EFI_SUCCESS The MTFTPv4 related file "directory" has been downloaded.
453 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
454 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
455 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in
456 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
457 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
458 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
459 RARP, etc.) is not finished yet.
460 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4 session.
461 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
462 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
463 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
468 (EFIAPI
*EFI_MTFTP4_READ_DIRECTORY
)(
469 IN EFI_MTFTP4_PROTOCOL
*This
,
470 IN EFI_MTFTP4_TOKEN
*Token
474 Polls for incoming data packets and processes outgoing data packets.
476 @param This The pointer to the EFI_MTFTP4_PROTOCOL instance.
478 @retval EFI_SUCCESS Incoming or outgoing data was processed.
479 @retval EFI_NOT_STARTED This EFI MTFTPv4 Protocol instance has not been started.
480 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
481 RARP, etc.) is not finished yet.
482 @retval EFI_INVALID_PARAMETER This is NULL.
483 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
484 @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue.
485 Consider increasing the polling rate.
490 (EFIAPI
*EFI_MTFTP4_POLL
)(
491 IN EFI_MTFTP4_PROTOCOL
*This
495 /// The EFI_MTFTP4_PROTOCOL is designed to be used by UEFI drivers and applications
496 /// to transmit and receive data files. The EFI MTFTPv4 Protocol driver uses
497 /// the underlying EFI UDPv4 Protocol driver and EFI IPv4 Protocol driver.
499 struct _EFI_MTFTP4_PROTOCOL
{
500 EFI_MTFTP4_GET_MODE_DATA GetModeData
;
501 EFI_MTFTP4_CONFIGURE Configure
;
502 EFI_MTFTP4_GET_INFO GetInfo
;
503 EFI_MTFTP4_PARSE_OPTIONS ParseOptions
;
504 EFI_MTFTP4_READ_FILE ReadFile
;
505 EFI_MTFTP4_WRITE_FILE WriteFile
;
506 EFI_MTFTP4_READ_DIRECTORY ReadDirectory
;
507 EFI_MTFTP4_POLL Poll
;
510 struct _EFI_MTFTP4_TOKEN
{
512 /// The status that is returned to the caller at the end of the operation
513 /// to indicate whether this operation completed successfully.
517 /// The event that will be signaled when the operation completes. If
518 /// set to NULL, the corresponding function will wait until the read or
519 /// write operation finishes. The type of Event must be
520 /// EVT_NOTIFY_SIGNAL. The Task Priority Level (TPL) of
521 /// Event must be lower than or equal to TPL_CALLBACK.
525 /// If not NULL, the data that will be used to override the existing configure data.
527 EFI_MTFTP4_OVERRIDE_DATA
*OverrideData
;
529 /// The pointer to the null-terminated ASCII file name string.
533 /// The pointer to the null-terminated ASCII mode string. If NULL, "octet" is used.
537 /// Number of option/value string pairs.
541 /// The pointer to an array of option/value string pairs. Ignored if OptionCount is zero.
543 EFI_MTFTP4_OPTION
*OptionList
;
545 /// The size of the data buffer.
549 /// The pointer to the data buffer. Data that is downloaded from the
550 /// MTFTPv4 server is stored here. Data that is uploaded to the
551 /// MTFTPv4 server is read from here. Ignored if BufferSize is zero.
555 /// The pointer to the context that will be used by CheckPacket,
556 /// TimeoutCallback and PacketNeeded.
560 /// The pointer to the callback function to check the contents of the received packet.
562 EFI_MTFTP4_CHECK_PACKET CheckPacket
;
564 /// The pointer to the function to be called when a timeout occurs.
566 EFI_MTFTP4_TIMEOUT_CALLBACK TimeoutCallback
;
568 /// The pointer to the function to provide the needed packet contents.
570 EFI_MTFTP4_PACKET_NEEDED PacketNeeded
;
573 extern EFI_GUID gEfiMtftp4ServiceBindingProtocolGuid
;
574 extern EFI_GUID gEfiMtftp4ProtocolGuid
;