Mtftp4.h File Reference

Data Structures
struct	EFI_MTFTP4_REQ_HEADER
struct	EFI_MTFTP4_OACK_HEADER
struct	EFI_MTFTP4_DATA_HEADER
struct	EFI_MTFTP4_ACK_HEADER
struct	EFI_MTFTP4_DATA8_HEADER
struct	EFI_MTFTP4_ACK8_HEADER
struct	EFI_MTFTP4_ERROR_HEADER
union	EFI_MTFTP4_PACKET
struct	EFI_MTFTP4_OPTION
struct	EFI_MTFTP4_CONFIG_DATA
struct	EFI_MTFTP4_MODE_DATA
struct	EFI_MTFTP4_OVERRIDE_DATA
struct	_EFI_MTFTP4_PROTOCOL
struct	_EFI_MTFTP4_TOKEN

Macros
#define	EFI_MTFTP4_SERVICE_BINDING_PROTOCOL_GUID
#define	EFI_MTFTP4_PROTOCOL_GUID
#define	EFI_MTFTP4_OPCODE_RRQ   1
#define	EFI_MTFTP4_OPCODE_WRQ   2
#define	EFI_MTFTP4_OPCODE_DATA   3
#define	EFI_MTFTP4_OPCODE_ACK   4
#define	EFI_MTFTP4_OPCODE_ERROR   5
#define	EFI_MTFTP4_OPCODE_OACK   6
#define	EFI_MTFTP4_OPCODE_DIR   7
#define	EFI_MTFTP4_OPCODE_DATA8   8
#define	EFI_MTFTP4_OPCODE_ACK8   9
#define	EFI_MTFTP4_ERRORCODE_NOT_DEFINED   0
#define	EFI_MTFTP4_ERRORCODE_FILE_NOT_FOUND   1
#define	EFI_MTFTP4_ERRORCODE_ACCESS_VIOLATION   2
#define	EFI_MTFTP4_ERRORCODE_DISK_FULL   3
#define	EFI_MTFTP4_ERRORCODE_ILLEGAL_OPERATION   4
#define	EFI_MTFTP4_ERRORCODE_UNKNOWN_TRANSFER_ID   5
#define	EFI_MTFTP4_ERRORCODE_FILE_ALREADY_EXISTS   6
#define	EFI_MTFTP4_ERRORCODE_NO_SUCH_USER   7
#define	EFI_MTFTP4_ERRORCODE_REQUEST_DENIED   8

Typedefs
typedef struct _EFI_MTFTP4_PROTOCOL	EFI_MTFTP4_PROTOCOL
typedef struct _EFI_MTFTP4_TOKEN	EFI_MTFTP4_TOKEN
typedef EFI_STATUS(EFIAPI *	EFI_MTFTP4_CHECK_PACKET )(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token, IN UINT16 PacketLen, IN EFI_MTFTP4_PACKET *Paket)
typedef EFI_STATUS(EFIAPI *	EFI_MTFTP4_TIMEOUT_CALLBACK )(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token)
typedef EFI_STATUS(EFIAPI *	EFI_MTFTP4_PACKET_NEEDED )(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token, IN OUT UINT16 *Length, OUT VOID **Buffer)
typedef EFI_STATUS(EFIAPI *	EFI_MTFTP4_GET_MODE_DATA )(IN EFI_MTFTP4_PROTOCOL *This, OUT EFI_MTFTP4_MODE_DATA *ModeData)
typedef EFI_STATUS(EFIAPI *	EFI_MTFTP4_CONFIGURE )(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_CONFIG_DATA *MtftpConfigData)
typedef EFI_STATUS(EFIAPI *	EFI_MTFTP4_GET_INFO )(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_OVERRIDE_DATA *OverrideData, IN UINT8 *Filename, IN UINT8 *ModeStr, IN UINT8 OptionCount, IN EFI_MTFTP4_OPTION *OptionList, OUT UINT32 *PacketLength, OUT EFI_MTFTP4_PACKET **Packet)
typedef EFI_STATUS(EFIAPI *	EFI_MTFTP4_PARSE_OPTIONS )(IN EFI_MTFTP4_PROTOCOL *This, IN UINT32 PacketLen, IN EFI_MTFTP4_PACKET *Packet, OUT UINT32 *OptionCount, OUT EFI_MTFTP4_OPTION **OptionList)
typedef EFI_STATUS(EFIAPI *	EFI_MTFTP4_READ_FILE )(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token)
typedef EFI_STATUS(EFIAPI *	EFI_MTFTP4_WRITE_FILE )(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token)
typedef EFI_STATUS(EFIAPI *	EFI_MTFTP4_READ_DIRECTORY )(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token)
typedef EFI_STATUS(EFIAPI *	EFI_MTFTP4_POLL )(IN EFI_MTFTP4_PROTOCOL *This)

Variables
EFI_GUID	gEfiMtftp4ServiceBindingProtocolGuid
EFI_GUID	gEfiMtftp4ProtocolGuid

Detailed Description

EFI Multicast Trivial File Transfer Protocol Definition

Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Revision Reference:

This Protocol is introduced in UEFI Specification 2.0

Macro Definition Documentation

#define EFI_MTFTP4_ERRORCODE_ACCESS_VIOLATION   2

#define EFI_MTFTP4_ERRORCODE_DISK_FULL   3

#define EFI_MTFTP4_ERRORCODE_FILE_ALREADY_EXISTS   6

#define EFI_MTFTP4_ERRORCODE_FILE_NOT_FOUND   1

#define EFI_MTFTP4_ERRORCODE_ILLEGAL_OPERATION   4

#define EFI_MTFTP4_ERRORCODE_NO_SUCH_USER   7

#define EFI_MTFTP4_ERRORCODE_NOT_DEFINED   0

#define EFI_MTFTP4_ERRORCODE_REQUEST_DENIED   8

#define EFI_MTFTP4_ERRORCODE_UNKNOWN_TRANSFER_ID   5

#define EFI_MTFTP4_OPCODE_ACK   4

#define EFI_MTFTP4_OPCODE_ACK8   9

#define EFI_MTFTP4_OPCODE_DATA   3

#define EFI_MTFTP4_OPCODE_DATA8   8

#define EFI_MTFTP4_OPCODE_DIR   7

#define EFI_MTFTP4_OPCODE_ERROR   5

#define EFI_MTFTP4_OPCODE_OACK   6

#define EFI_MTFTP4_OPCODE_RRQ   1

#define EFI_MTFTP4_OPCODE_WRQ   2

#define EFI_MTFTP4_PROTOCOL_GUID

Value:

{ \
    0x78247c57, 0x63db, 0x4708, {0x99, 0xc2, 0xa8, 0xb4, 0xa9, 0xa6, 0x1f, 0x6b } \
  }

#define EFI_MTFTP4_SERVICE_BINDING_PROTOCOL_GUID

Value:

{ \
    0x2FE800BE, 0x8F01, 0x4aa6, {0x94, 0x6B, 0xD7, 0x13, 0x88, 0xE1, 0x83, 0x3F } \
  }

Typedef Documentation

typedef EFI_STATUS(EFIAPI * EFI_MTFTP4_CHECK_PACKET)(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token, IN UINT16 PacketLen, IN EFI_MTFTP4_PACKET *Paket)

A callback function that is provided by the caller to intercept the EFI_MTFTP4_OPCODE_DATA or EFI_MTFTP4_OPCODE_DATA8 packets processed in the EFI_MTFTP4_PROTOCOL.ReadFile() function, and alternatively to intercept EFI_MTFTP4_OPCODE_OACK or EFI_MTFTP4_OPCODE_ERROR packets during a call to EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory().

Parameters

This	The pointer to the EFI_MTFTP4_PROTOCOL instance.
Token	The token that the caller provided in the EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory() function.
PacketLen	Indicates the length of the packet.
Packet	The pointer to an MTFTPv4 packet.

Return values

EFI_SUCCESS	The operation was successful.
Others	Aborts the transfer process.

typedef EFI_STATUS(EFIAPI * EFI_MTFTP4_CONFIGURE)(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_CONFIG_DATA *MtftpConfigData)

Initializes, changes, or resets the default operational setting for this EFI MTFTPv4 Protocol driver instance.

Parameters

This	The pointer to the EFI_MTFTP4_PROTOCOL instance.
MtftpConfigData	The pointer to the configuration data structure.

Return values

EFI_SUCCESS	The EFI MTFTPv4 Protocol driver was configured successfully.
EFI_INVALID_PARAMETER	One or more parameters are invalid.
EFI_ACCESS_DENIED	The EFI configuration could not be changed at this time because there is one MTFTP background operation in progress.
EFI_NO_MAPPING	When using a default address, configuration (DHCP, BOOTP, RARP, etc.) has not finished yet.
EFI_UNSUPPORTED	A configuration protocol (DHCP, BOOTP, RARP, etc.) could not be located when clients choose to use the default address settings.
EFI_OUT_OF_RESOURCES	The EFI MTFTPv4 Protocol driver instance data could not be allocated.
EFI_DEVICE_ERROR	An unexpected system or network error occurred. The EFI MTFTPv4 Protocol driver instance is not configured.

typedef EFI_STATUS(EFIAPI * EFI_MTFTP4_GET_INFO)(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_OVERRIDE_DATA *OverrideData, IN UINT8 *Filename, IN UINT8 *ModeStr, IN UINT8 OptionCount, IN EFI_MTFTP4_OPTION *OptionList, OUT UINT32 *PacketLength, OUT EFI_MTFTP4_PACKET **Packet)

Gets information about a file from an MTFTPv4 server.

Parameters

This	The pointer to the EFI_MTFTP4_PROTOCOL instance.
OverrideData	Data that is used to override the existing parameters. If NULL, the default parameters that were set in the EFI_MTFTP4_PROTOCOL.Configure() function are used.
Filename	The pointer to null-terminated ASCII file name string.
ModeStr	The pointer to null-terminated ASCII mode string. If NULL, "octet" will be used.
OptionCount	Number of option/value string pairs in OptionList.
OptionList	The pointer to array of option/value string pairs. Ignored if OptionCount is zero.
PacketLength	The number of bytes in the returned packet.
Packet	The pointer to the received packet. This buffer must be freed by the caller.

Return values

EFI_SUCCESS	An MTFTPv4 OACK packet was received and is in the Packet.
EFI_INVALID_PARAMETER	One or more of the following conditions is TRUE: This is NULL. Filename is NULL. OptionCount is not zero and OptionList is NULL. One or more options in OptionList have wrong format. PacketLength is NULL. One or more IPv4 addresses in OverrideData are not valid unicast IPv4 addresses if OverrideData is not NULL.
EFI_UNSUPPORTED	One or more options in the OptionList are in the unsupported list of structure EFI_MTFTP4_MODE_DATA.
EFI_NOT_STARTED	The EFI MTFTPv4 Protocol driver has not been started.
EFI_NO_MAPPING	When using a default address, configuration (DHCP, BOOTP, RARP, etc.) has not finished yet.
EFI_ACCESS_DENIED	The previous operation has not completed yet.
EFI_OUT_OF_RESOURCES	Required system resources could not be allocated.
EFI_TFTP_ERROR	An MTFTPv4 ERROR packet was received and is in the Packet.
EFI_NETWORK_UNREACHABLE	An ICMP network unreachable error packet was received and the Packet is set to NULL.
EFI_HOST_UNREACHABLE	An ICMP host unreachable error packet was received and the Packet is set to NULL.
EFI_PROTOCOL_UNREACHABLE	An ICMP protocol unreachable error packet was received and the Packet is set to NULL.
EFI_PORT_UNREACHABLE	An ICMP port unreachable error packet was received and the Packet is set to NULL.
EFI_ICMP_ERROR	Some other ICMP ERROR packet was received and is in the Buffer.
EFI_PROTOCOL_ERROR	An unexpected MTFTPv4 packet was received and is in the Packet.
EFI_TIMEOUT	No responses were received from the MTFTPv4 server.
EFI_DEVICE_ERROR	An unexpected network error or system error occurred.
EFI_NO_MEDIA	There was a media error.

typedef EFI_STATUS(EFIAPI * EFI_MTFTP4_GET_MODE_DATA)(IN EFI_MTFTP4_PROTOCOL *This, OUT EFI_MTFTP4_MODE_DATA *ModeData)

Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.

Parameters

This	The pointer to the EFI_MTFTP4_PROTOCOL instance.
ModeData	The pointer to storage for the EFI MTFTPv4 Protocol driver mode data.

Return values

EFI_SUCCESS	The configuration data was successfully returned.
EFI_OUT_OF_RESOURCES	The required mode data could not be allocated.
EFI_INVALID_PARAMETER	This is NULL or ModeData is NULL.

typedef EFI_STATUS(EFIAPI * EFI_MTFTP4_PACKET_NEEDED)(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token, IN OUT UINT16 *Length, OUT VOID **Buffer)

A callback function that the caller provides to feed data to the EFI_MTFTP4_PROTOCOL.WriteFile() function.

Parameters

This	The pointer to the EFI_MTFTP4_PROTOCOL instance.
Token	The token provided in the EFI_MTFTP4_PROTOCOL.WriteFile() by the caller.
Length	Indicates the length of the raw data wanted on input, and the length the data available on output.
Buffer	The pointer to the buffer where the data is stored.

Return values

EFI_SUCCESS	The operation was successful.
Others	Aborts session.

typedef EFI_STATUS(EFIAPI * EFI_MTFTP4_PARSE_OPTIONS)(IN EFI_MTFTP4_PROTOCOL *This, IN UINT32 PacketLen, IN EFI_MTFTP4_PACKET *Packet, OUT UINT32 *OptionCount, OUT EFI_MTFTP4_OPTION **OptionList)

Parses the options in an MTFTPv4 OACK packet.

Parameters

This	The pointer to the EFI_MTFTP4_PROTOCOL instance.
PacketLen	Length of the OACK packet to be parsed.
Packet	The pointer to the OACK packet to be parsed.
OptionCount	The pointer to the number of options in following OptionList.
OptionList	The pointer to EFI_MTFTP4_OPTION storage. Call the EFI Boot Service FreePool() to release the OptionList if the options in this OptionList are not needed any more.

Return values

EFI_SUCCESS	The OACK packet was valid and the OptionCount and OptionList parameters have been updated.
EFI_INVALID_PARAMETER	One or more of the following conditions is TRUE: PacketLen is 0. Packet is NULL or Packet is not a valid MTFTPv4 packet. OptionCount is NULL.
EFI_NOT_FOUND	No options were found in the OACK packet.
EFI_OUT_OF_RESOURCES	Storage for the OptionList array cannot be allocated.
EFI_PROTOCOL_ERROR	One or more of the option fields is invalid.

typedef EFI_STATUS(EFIAPI * EFI_MTFTP4_POLL)(IN EFI_MTFTP4_PROTOCOL *This)

Polls for incoming data packets and processes outgoing data packets.

Parameters

This	The pointer to the EFI_MTFTP4_PROTOCOL instance.

Return values

EFI_SUCCESS	Incoming or outgoing data was processed.
EFI_NOT_STARTED	This EFI MTFTPv4 Protocol instance has not been started.
EFI_NO_MAPPING	When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet.
EFI_INVALID_PARAMETER	This is NULL.
EFI_DEVICE_ERROR	An unexpected system or network error occurred.
EFI_TIMEOUT	Data was dropped out of the transmit and/or receive queue. Consider increasing the polling rate.

typedef struct _EFI_MTFTP4_PROTOCOL EFI_MTFTP4_PROTOCOL

typedef EFI_STATUS(EFIAPI * EFI_MTFTP4_READ_DIRECTORY)(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token)

Downloads a data file "directory" from an MTFTPv4 server. May be unsupported in some EFI implementations.

Parameters

This	The pointer to the EFI_MTFTP4_PROTOCOL instance.
Token	The pointer to the token structure to provide the parameters that are used in this operation.

Return values

EFI_SUCCESS	The MTFTPv4 related file "directory" has been downloaded.
EFI_UNSUPPORTED	The operation is not supported by this implementation.
EFI_INVALID_PARAMETER	One or more parameters are invalid.
EFI_UNSUPPORTED	One or more options in the Token.OptionList are in the unsupported list of structure EFI_MTFTP4_MODE_DATA.
EFI_NOT_STARTED	The EFI MTFTPv4 Protocol driver has not been started.
EFI_NO_MAPPING	When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet.
EFI_ALREADY_STARTED	This Token is already being used in another MTFTPv4 session.
EFI_OUT_OF_RESOURCES	Required system resources could not be allocated.
EFI_ACCESS_DENIED	The previous operation has not completed yet.
EFI_DEVICE_ERROR	An unexpected network error or system error occurred.

typedef EFI_STATUS(EFIAPI * EFI_MTFTP4_READ_FILE)(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token)

Downloads a file from an MTFTPv4 server.

Parameters

This	The pointer to the EFI_MTFTP4_PROTOCOL instance.
Token	The pointer to the token structure to provide the parameters that are used in this operation.

Return values

EFI_SUCCESS	The data file has been transferred successfully.
EFI_OUT_OF_RESOURCES	Required system resources could not be allocated.
EFI_BUFFER_TOO_SMALL	BufferSize is not zero but not large enough to hold the downloaded data in downloading process.
EFI_ABORTED	Current operation is aborted by user.
EFI_NETWORK_UNREACHABLE	An ICMP network unreachable error packet was received.
EFI_HOST_UNREACHABLE	An ICMP host unreachable error packet was received.
EFI_PROTOCOL_UNREACHABLE	An ICMP protocol unreachable error packet was received.
EFI_PORT_UNREACHABLE	An ICMP port unreachable error packet was received.
EFI_ICMP_ERROR	Some other ICMP ERROR packet was received.
EFI_TIMEOUT	No responses were received from the MTFTPv4 server.
EFI_TFTP_ERROR	An MTFTPv4 ERROR packet was received.
EFI_DEVICE_ERROR	An unexpected network error or system error occurred.
EFI_NO_MEDIA	There was a media error.

typedef EFI_STATUS(EFIAPI * EFI_MTFTP4_TIMEOUT_CALLBACK)(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token)

Timeout callback function.

Parameters

This	The pointer to the EFI_MTFTP4_PROTOCOL instance.
Token	The token that is provided in the EFI_MTFTP4_PROTOCOL.ReadFile() or EFI_MTFTP4_PROTOCOL.WriteFile() or EFI_MTFTP4_PROTOCOL.ReadDirectory() functions by the caller.

Return values

EFI_SUCCESS	The operation was successful.
Others	Aborts download process.

typedef struct _EFI_MTFTP4_TOKEN EFI_MTFTP4_TOKEN

typedef EFI_STATUS(EFIAPI * EFI_MTFTP4_WRITE_FILE)(IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token)

Sends a file to an MTFTPv4 server.

Parameters

This	The pointer to the EFI_MTFTP4_PROTOCOL instance.
Token	The pointer to the token structure to provide the parameters that are used in this operation.

Return values

EFI_SUCCESS	The upload session has started.
EFI_UNSUPPORTED	The operation is not supported by this implementation.
EFI_INVALID_PARAMETER	One or more parameters are invalid.
EFI_UNSUPPORTED	One or more options in the Token.OptionList are in the unsupported list of structure EFI_MTFTP4_MODE_DATA.
EFI_NOT_STARTED	The EFI MTFTPv4 Protocol driver has not been started.
EFI_NO_MAPPING	When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet.
EFI_ALREADY_STARTED	This Token is already being used in another MTFTPv4 session.
EFI_OUT_OF_RESOURCES	Required system resources could not be allocated.
EFI_ACCESS_DENIED	The previous operation has not completed yet.
EFI_DEVICE_ERROR	An unexpected network error or system error occurred.

Variable Documentation

EFI_GUID gEfiMtftp4ProtocolGuid

EFI_GUID gEfiMtftp4ServiceBindingProtocolGuid