/** @file\r
EFI Multicast Trivial File Tranfer Protocol Definition\r
\r
- Copyright (c) 2006, Intel Corporation \r
+ Copyright (c) 2006 - 2009, Intel Corporation \r
All rights reserved. This program and the accompanying materials \r
are licensed and made available under the terms and conditions of the BSD License \r
which accompanies this distribution. The full text of the license may be found at \r
http://opensource.org/licenses/bsd-license.php \r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
+\r
+ @par Revision Reference: \r
+ This Protocol is introduced in UEFI Specification 2.0\r
\r
**/\r
\r
} EFI_MTFTP4_ERROR_HEADER;\r
\r
typedef union {\r
+ ///\r
+ /// Type of packets as defined by the MTFTPv4 packet opcodes.\r
+ ///\r
UINT16 OpCode;\r
+ ///\r
+ /// Read request packet header.\r
+ ///\r
EFI_MTFTP4_REQ_HEADER Rrq;\r
+ ///\r
+ /// Write request packet header.\r
+ ///\r
EFI_MTFTP4_REQ_HEADER Wrq;\r
+ ///\r
+ /// Option acknowledge packet header.\r
+ ///\r
EFI_MTFTP4_OACK_HEADER Oack;\r
+ ///\r
+ /// Data packet header.\r
+ ///\r
EFI_MTFTP4_DATA_HEADER Data;\r
+ ///\r
+ /// Acknowledgement packet header.\r
+ ///\r
EFI_MTFTP4_ACK_HEADER Ack;\r
+ ///\r
+ /// Data packet header with big block number.\r
+ ///\r
EFI_MTFTP4_DATA8_HEADER Data8;\r
+ ///\r
+ /// Acknowledgement header with big block num.\r
+ ///\r
EFI_MTFTP4_ACK8_HEADER Ack8;\r
+ ///\r
+ /// Error packet header.\r
+ ///\r
EFI_MTFTP4_ERROR_HEADER Error;\r
} EFI_MTFTP4_PACKET;\r
\r
#pragma pack()\r
\r
-//\r
-// MTFTP4 option definition\r
-//\r
+///\r
+/// MTFTP4 option definition\r
+///\r
typedef struct {\r
UINT8 *OptionStr;\r
UINT8 *ValueStr;\r
//\r
\r
/**\r
- a callback function that is provided by the caller to intercept \r
+ A callback function that is provided by the caller to intercept \r
the EFI_MTFTP4_OPCODE_DATA or EFI_MTFTP4_OPCODE_DATA8 packets processed in the\r
EFI_MTFTP4_PROTOCOL.ReadFile() function, and alternatively to intercept \r
EFI_MTFTP4_OPCODE_OACK or EFI_MTFTP4_OPCODE_ERROR packets during a call to \r
IN EFI_MTFTP4_TOKEN *Token,\r
IN UINT16 PacketLen,\r
IN EFI_MTFTP4_PACKET *Paket\r
- )\r
-;\r
+ );\r
\r
/**\r
Timeout callback funtion. \r
(EFIAPI *EFI_MTFTP4_TIMEOUT_CALLBACK)( \r
IN EFI_MTFTP4_PROTOCOL *This,\r
IN EFI_MTFTP4_TOKEN *Token\r
- )\r
-;\r
+ );\r
\r
/**\r
- a callback function that the caller provides to feed data to the\r
+ A callback function that the caller provides to feed data to the\r
EFI_MTFTP4_PROTOCOL.WriteFile() function.\r
\r
@param This Pointer to the EFI_MTFTP4_PROTOCOL instance.\r
IN EFI_MTFTP4_TOKEN *Token,\r
IN OUT UINT16 *Length,\r
OUT VOID **Buffer\r
- )\r
-;\r
+ );\r
\r
\r
/**\r
(EFIAPI *EFI_MTFTP4_GET_MODE_DATA)(\r
IN EFI_MTFTP4_PROTOCOL *This,\r
OUT EFI_MTFTP4_MODE_DATA *ModeData\r
- )\r
-;\r
+ );\r
\r
\r
/**\r
(EFIAPI *EFI_MTFTP4_CONFIGURE)(\r
IN EFI_MTFTP4_PROTOCOL *This,\r
IN EFI_MTFTP4_CONFIG_DATA *MtftpConfigData OPTIONAL\r
- )\r
-; \r
+ ); \r
\r
\r
/**\r
@param Packet The pointer to the received packet. This buffer must be freed by\r
the caller.\r
\r
- @retval EFI_SUCCESS An MTFTPv4 OACK packet was received and is in the Buffer.\r
- @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
- @retval EFI_UNSUPPORTED One or more options in the OptionList are in the\r
- unsupported list of structure EFI_MTFTP4_MODE_DATA.\r
- @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.\r
- @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,\r
- RARP, etc.) has not finished yet.\r
- @retval EFI_ACCESS_DENIED The previous operation has not completed yet.\r
- @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.\r
- @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received and is in the buffer.\r
- @retval EFI_ICMP_ERROR An ICMP ERROR packet was received and is in the Buffer.\r
- @retval EFI_PROTOCOL_ERROR An unexpected MTFTPv4 packet was received and is in the buffer.\r
- @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.\r
- @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.\r
+ @retval EFI_SUCCESS An MTFTPv4 OACK packet was received and is in the Packet.\r
+ Note: It does not match UEFI 2.3 Specification.\r
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
+ - This is NULL.\r
+ - Filename is NULL.\r
+ - OptionCount is not zero and OptionList is NULL.\r
+ - One or more options in OptionList have wrong format.\r
+ - PacketLength is NULL.\r
+ - One or more IPv4 addresses in OverrideData are not valid\r
+ unicast IPv4 addresses if OverrideData is not NULL.\r
+ @retval EFI_UNSUPPORTED One or more options in the OptionList are in the\r
+ unsupported list of structure EFI_MTFTP4_MODE_DATA.\r
+ @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.\r
+ @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,\r
+ RARP, etc.) has not finished yet.\r
+ @retval EFI_ACCESS_DENIED The previous operation has not completed yet.\r
+ @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.\r
+ @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received and is in the Packet.\r
+ @retval EFI_NETWORK_UNREACHABLE An ICMP network unreachable error packet was received and the Packet is set to NULL.\r
+ Note: It is not defined in UEFI 2.3 Specification.\r
+ @retval EFI_HOST_UNREACHABLE An ICMP host unreachable error packet was received and the Packet is set to NULL.\r
+ Note: It is not defined in UEFI 2.3 Specification.\r
+ @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received and the Packet is set to NULL.\r
+ Note: It is not defined in UEFI 2.3 Specification.\r
+ @retval EFI_PORT_UNREACHABLE An ICMP port unreachable error packet was received and the Packet is set to NULL.\r
+ Note: It is not defined in UEFI 2.3 Specification.\r
+ @retval EFI_ICMP_ERROR Some other ICMP ERROR packet was received and is in the Buffer.\r
+ Note: It does not match UEFI 2.3 Specification.\r
+ @retval EFI_PROTOCOL_ERROR An unexpected MTFTPv4 packet was received and is in the Packet.\r
+ Note: It does not match UEFI 2.3 Specification.\r
+ @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.\r
+ @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.\r
\r
**/\r
typedef \r
IN EFI_MTFTP4_OPTION *OptionList,\r
OUT UINT32 *PacketLength,\r
OUT EFI_MTFTP4_PACKET **Packet OPTIONAL\r
- )\r
-;\r
+ );\r
\r
/**\r
Parses the options in an MTFTPv4 OACK packet.\r
@param Packet Pointer to the OACK packet to be parsed.\r
@param OptionCount Pointer to the number of options in following OptionList.\r
@param OptionList Pointer to EFI_MTFTP4_OPTION storage. Call the EFI Boot\r
- Service FreePool() to release each option if they are not\r
- needed any more.\r
+ Service FreePool() to release the OptionList if the options\r
+ in this OptionList are not needed any more.\r
\r
@retval EFI_SUCCESS The OACK packet was valid and the OptionCount and\r
OptionList parameters have been updated.\r
IN EFI_MTFTP4_PACKET *Packet,\r
OUT UINT32 *OptionCount,\r
OUT EFI_MTFTP4_OPTION **OptionList OPTIONAL\r
- )\r
-; \r
+ ); \r
\r
\r
/**\r
@param Token Pointer to the token structure to provide the parameters that are\r
used in this operation.\r
\r
- @retval EFI_SUCCESS The data file has been transferred successfully.\r
- @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.\r
- @retval EFI_BUFFER_TOO_SMALL BufferSize is not large enough to hold the downloaded data\r
- in downloading process.\r
- @retval EFI_ABORTED Current operation is aborted by user.\r
- @retval EFI_ICMP_ERROR An ICMP ERROR packet was received.\r
- @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.\r
- @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received.\r
- @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.\r
+ @retval EFI_SUCCESS The data file has been transferred successfully.\r
+ @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.\r
+ @retval EFI_BUFFER_TOO_SMALL BufferSize is not zero but not large enough to hold the\r
+ downloaded data in downloading process.\r
+ Note: It does not match UEFI 2.3 Specification.\r
+ @retval EFI_ABORTED Current operation is aborted by user.\r
+ @retval EFI_NETWORK_UNREACHABLE An ICMP network unreachable error packet was received.\r
+ Note: It is not defined in UEFI 2.3 Specification.\r
+ @retval EFI_HOST_UNREACHABLE An ICMP host unreachable error packet was received.\r
+ Note: It is not defined in UEFI 2.3 Specification.\r
+ @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received.\r
+ Note: It is not defined in UEFI 2.3 Specification.\r
+ @retval EFI_PORT_UNREACHABLE An ICMP port unreachable error packet was received.\r
+ Note: It is not defined in UEFI 2.3 Specification.\r
+ @retval EFI_ICMP_ERROR Some other ICMP ERROR packet was received.\r
+ Note: It does not match UEFI 2.3 Specification.\r
+ @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.\r
+ @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received.\r
+ @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.\r
\r
**/\r
typedef \r
(EFIAPI *EFI_MTFTP4_READ_FILE)(\r
IN EFI_MTFTP4_PROTOCOL *This,\r
IN EFI_MTFTP4_TOKEN *Token\r
- )\r
-; \r
+ ); \r
\r
\r
\r
(EFIAPI *EFI_MTFTP4_WRITE_FILE)(\r
IN EFI_MTFTP4_PROTOCOL *This,\r
IN EFI_MTFTP4_TOKEN *Token\r
- )\r
-; \r
+ ); \r
\r
\r
/**\r
(EFIAPI *EFI_MTFTP4_READ_DIRECTORY)(\r
IN EFI_MTFTP4_PROTOCOL *This,\r
IN EFI_MTFTP4_TOKEN *Token\r
- )\r
-; \r
+ ); \r
\r
/**\r
Polls for incoming data packets and processes outgoing data packets.\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_MTFTP4_POLL) (\r
+(EFIAPI *EFI_MTFTP4_POLL)(\r
IN EFI_MTFTP4_PROTOCOL *This\r
- )\r
-; \r
+ ); \r
\r
- \r
+///\r
+/// The EFI_MTFTP4_PROTOCOL is designed to be used by UEFI drivers and applications \r
+/// to transmit and receive data files. The EFI MTFTPv4 Protocol driver uses \r
+/// the underlying EFI UDPv4 Protocol driver and EFI IPv4 Protocol driver.\r
+/// \r
struct _EFI_MTFTP4_PROTOCOL {\r
EFI_MTFTP4_GET_MODE_DATA GetModeData;\r
EFI_MTFTP4_CONFIGURE Configure;\r
};\r
\r
struct _EFI_MTFTP4_TOKEN {\r
- OUT EFI_STATUS Status;\r
- IN EFI_EVENT Event;\r
- IN EFI_MTFTP4_OVERRIDE_DATA *OverrideData;\r
- IN UINT8 *Filename;\r
- IN UINT8 *ModeStr;\r
- IN UINT32 OptionCount;\r
- IN EFI_MTFTP4_OPTION *OptionList;\r
- IN OUT UINT64 BufferSize;\r
- IN OUT VOID *Buffer;\r
- IN EFI_MTFTP4_CHECK_PACKET CheckPacket;\r
- IN EFI_MTFTP4_TIMEOUT_CALLBACK TimeoutCallback;\r
- IN EFI_MTFTP4_PACKET_NEEDED PacketNeeded;\r
+ ///\r
+ /// The status that is returned to the caller at the end of the operation\r
+ /// to indicate whether this operation completed successfully.\r
+ ///\r
+ EFI_STATUS Status;\r
+ ///\r
+ /// The event that will be signaled when the operation completes. If\r
+ /// set to NULL, the corresponding function will wait until the read or\r
+ /// write operation finishes. The type of Event must be\r
+ /// EVT_NOTIFY_SIGNAL. The Task Priority Level (TPL) of\r
+ /// Event must be lower than or equal to TPL_CALLBACK.\r
+ ///\r
+ EFI_EVENT Event;\r
+ ///\r
+ /// If not NULL, the data that will be used to override the existing configure data.\r
+ ///\r
+ EFI_MTFTP4_OVERRIDE_DATA *OverrideData;\r
+ ///\r
+ /// Pointer to the ASCIIZ file name string.\r
+ ///\r
+ UINT8 *Filename;\r
+ ///\r
+ /// Pointer to the ASCIIZ mode string. If NULL, "octet" is used.\r
+ ///\r
+ UINT8 *ModeStr;\r
+ ///\r
+ /// Number of option/value string pairs.\r
+ ///\r
+ UINT32 OptionCount;\r
+ ///\r
+ /// Pointer to an array of option/value string pairs. Ignored if OptionCount is zero.\r
+ ///\r
+ EFI_MTFTP4_OPTION *OptionList;\r
+ ///\r
+ /// Size of the data buffer.\r
+ ///\r
+ UINT64 BufferSize;\r
+ ///\r
+ /// Pointer to the data buffer. Data that is downloaded from the\r
+ /// MTFTPv4 server is stored here. Data that is uploaded to the\r
+ /// MTFTPv4 server is read from here. Ignored if BufferSize is zero.\r
+ ///\r
+ VOID *Buffer;\r
+ ///\r
+ /// Pointer to the context that will be used by CheckPacket, \r
+ /// TimeoutCallback and PacketNeeded.\r
+ ///\r
+ VOID *Context;\r
+ ///\r
+ /// Pointer to the callback function to check the contents of the received packet.\r
+ ///\r
+ EFI_MTFTP4_CHECK_PACKET CheckPacket;\r
+ ///\r
+ /// Pointer to the function to be called when a timeout occurs.\r
+ ///\r
+ EFI_MTFTP4_TIMEOUT_CALLBACK TimeoutCallback;\r
+ ///\r
+ /// Pointer to the function to provide the needed packet contents.\r
+ ///\r
+ EFI_MTFTP4_PACKET_NEEDED PacketNeeded;\r
};\r
\r
extern EFI_GUID gEfiMtftp4ServiceBindingProtocolGuid;\r
projects / mirror_edk2.git / blobdiff