X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=MdePkg%2FInclude%2FProtocol%2FMtftp4.h;h=1afac6cff5286024fb8f2922eb3f2740f0c1eb17;hb=419d98994418f2c8454cedf6269b35cfaa787f59;hp=15cfd98831e852c93b649043ba41a0ad6fa31fa1;hpb=992f22b99a90d1b217b1e6f702b238f1ff319753;p=mirror_edk2.git diff --git a/MdePkg/Include/Protocol/Mtftp4.h b/MdePkg/Include/Protocol/Mtftp4.h index 15cfd98831..1afac6cff5 100644 --- a/MdePkg/Include/Protocol/Mtftp4.h +++ b/MdePkg/Include/Protocol/Mtftp4.h @@ -1,14 +1,17 @@ /** @file EFI Multicast Trivial File Tranfer Protocol Definition - Copyright (c) 2006 - 2008, Intel Corporation - All rights reserved. This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php +Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.
+This program and the accompanying materials are licensed and made available under +the terms and conditions of the BSD License that accompanies this distribution. +The full text of the license may be found at +http://opensource.org/licenses/bsd-license.php. + +THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, +WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + @par Revision Reference: + This Protocol is introduced in UEFI Specification 2.0 **/ @@ -139,7 +142,7 @@ typedef union { #pragma pack() /// -/// MTFTP4 option definition +/// MTFTP4 option definition. /// typedef struct { UINT8 *OptionStr; @@ -162,9 +165,9 @@ typedef struct { typedef struct { EFI_MTFTP4_CONFIG_DATA ConfigData; - UINT8 SupportedOptionCount; + UINT8 SupportedOptionCount; UINT8 **SupportedOptoins; - UINT8 UnsupportedOptionCount; + UINT8 UnsupportedOptionCount; UINT8 **UnsupportedOptoins; } EFI_MTFTP4_MODE_DATA; @@ -182,26 +185,26 @@ typedef struct { // /** - a callback function that is provided by the caller to intercept + 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(). + 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(). - @param This Pointer to the EFI_MTFTP4_PROTOCOL instance. + @param This The pointer to the EFI_MTFTP4_PROTOCOL instance. @param Token The token that the caller provided in the EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory() function. @param PacketLen Indicates the length of the packet. - @param Packet Pointer to an MTFTPv4 packet. + @param Packet The pointer to an MTFTPv4 packet. - @retval EFI_SUCCESS Operation sucess - @retval Others Abort transfer process + @retval EFI_SUCCESS The operation was successful. + @retval Others Aborts the transfer process. **/ -typedef -EFI_STATUS -(EFIAPI *EFI_MTFTP4_CHECK_PACKET)( +typedef +EFI_STATUS +(EFIAPI *EFI_MTFTP4_CHECK_PACKET)( IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token, IN UINT16 PacketLen, @@ -209,44 +212,44 @@ EFI_STATUS ); /** - Timeout callback funtion. + Timeout callback funtion. - @param This Pointer to the EFI_MTFTP4_PROTOCOL instance. + @param This The pointer to the EFI_MTFTP4_PROTOCOL instance. @param 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. - - @retval EFI_SUCCESS Operation sucess + + @retval EFI_SUCCESS The operation was successful. @retval Others Aborts download process. **/ -typedef -EFI_STATUS -(EFIAPI *EFI_MTFTP4_TIMEOUT_CALLBACK)( +typedef +EFI_STATUS +(EFIAPI *EFI_MTFTP4_TIMEOUT_CALLBACK)( IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token ); /** - a callback function that the caller provides to feed data to the + A callback function that the caller provides to feed data to the EFI_MTFTP4_PROTOCOL.WriteFile() function. - @param This Pointer to the EFI_MTFTP4_PROTOCOL instance. + @param This The pointer to the EFI_MTFTP4_PROTOCOL instance. @param Token The token provided in the EFI_MTFTP4_PROTOCOL.WriteFile() by the caller. @param Length Indicates the length of the raw data wanted on input, and the length the data available on output. - @param Buffer Pointer to the buffer where the data is stored. + @param Buffer The pointer to the buffer where the data is stored. - @retval EFI_SUCCESS Operation sucess + @retval EFI_SUCCESS The operation was successful. @retval Others Aborts session. **/ -typedef -EFI_STATUS -(EFIAPI *EFI_MTFTP4_PACKET_NEEDED)( +typedef +EFI_STATUS +(EFIAPI *EFI_MTFTP4_PACKET_NEEDED)( IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token, IN OUT UINT16 *Length, @@ -257,16 +260,16 @@ EFI_STATUS /** Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device. - @param This Pointer to the EFI_MTFTP4_PROTOCOL instance. - @param ModeData Pointer to storage for the EFI MTFTPv4 Protocol driver mode data. + @param This The pointer to the EFI_MTFTP4_PROTOCOL instance. + @param ModeData The pointer to storage for the EFI MTFTPv4 Protocol driver mode data. @retval EFI_SUCCESS The configuration data was successfully returned. @retval EFI_OUT_OF_RESOURCES The required mode data could not be allocated. @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL. **/ -typedef -EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_MTFTP4_GET_MODE_DATA)( IN EFI_MTFTP4_PROTOCOL *This, OUT EFI_MTFTP4_MODE_DATA *ModeData @@ -274,11 +277,11 @@ EFI_STATUS /** - Initializes, changes, or resets the default operational setting for this + Initializes, changes, or resets the default operational setting for this EFI MTFTPv4 Protocol driver instance. - @param This Pointer to the EFI_MTFTP4_PROTOCOL instance. - @param MtftpConfigData Pointer to the configuration data structure. + @param This The pointer to the EFI_MTFTP4_PROTOCOL instance. + @param MtftpConfigData The pointer to the configuration data structure. @retval EFI_SUCCESS The EFI MTFTPv4 Protocol driver was configured successfully. @retval EFI_INVALID_PARAMETER One or more parameters are invalid. @@ -295,48 +298,60 @@ EFI_STATUS MTFTPv4 Protocol driver instance is not configured. **/ -typedef -EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_MTFTP4_CONFIGURE)( IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_CONFIG_DATA *MtftpConfigData OPTIONAL - ); - - + ); + + /** Gets information about a file from an MTFTPv4 server. - @param This Pointer to the EFI_MTFTP4_PROTOCOL instance. + @param This The pointer to the EFI_MTFTP4_PROTOCOL instance. @param 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. - @param Filename Pointer to ASCIIZ file name string. - @param ModeStr Pointer to ASCIIZ mode string. If NULL, "octet" will be used. + @param Filename The pointer to null-terminated ASCII file name string. + @param ModeStr The pointer to null-terminated ASCII mode string. If NULL, "octet" will be used. @param OptionCount Number of option/value string pairs in OptionList. - @param OptionList Pointer to array of option/value string pairs. Ignored if + @param OptionList The pointer to array of option/value string pairs. Ignored if OptionCount is zero. @param PacketLength The number of bytes in the returned packet. @param Packet The pointer to the received packet. This buffer must be freed by the caller. - @retval EFI_SUCCESS An MTFTPv4 OACK packet was received and is in the Buffer. - @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - @retval EFI_UNSUPPORTED One or more options in the OptionList are in the - unsupported list of structure EFI_MTFTP4_MODE_DATA. - @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started. - @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, - RARP, etc.) has not finished yet. - @retval EFI_ACCESS_DENIED The previous operation has not completed yet. - @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. - @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received and is in the buffer. - @retval EFI_ICMP_ERROR An ICMP ERROR packet was received and is in the Buffer. - @retval EFI_PROTOCOL_ERROR An unexpected MTFTPv4 packet was received and is in the buffer. - @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server. - @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred. + @retval EFI_SUCCESS An MTFTPv4 OACK packet was received and is in the Packet. + @retval 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. + @retval EFI_UNSUPPORTED One or more options in the OptionList are in the + unsupported list of structure EFI_MTFTP4_MODE_DATA. + @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started. + @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, + RARP, etc.) has not finished yet. + @retval EFI_ACCESS_DENIED The previous operation has not completed yet. + @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. + @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received and is in the Packet. + @retval EFI_NETWORK_UNREACHABLE An ICMP network unreachable error packet was received and the Packet is set to NULL. + @retval EFI_HOST_UNREACHABLE An ICMP host unreachable error packet was received and the Packet is set to NULL. + @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received and the Packet is set to NULL. + @retval EFI_PORT_UNREACHABLE An ICMP port unreachable error packet was received and the Packet is set to NULL. + @retval EFI_ICMP_ERROR Some other ICMP ERROR packet was received and is in the Buffer. + @retval EFI_PROTOCOL_ERROR An unexpected MTFTPv4 packet was received and is in the Packet. + @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server. + @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred. + @retval EFI_NO_MEDIA There was a media error. **/ -typedef -EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_MTFTP4_GET_INFO)( IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_OVERRIDE_DATA *OverrideData OPTIONAL, @@ -351,13 +366,13 @@ EFI_STATUS /** Parses the options in an MTFTPv4 OACK packet. - @param This Pointer to the EFI_MTFTP4_PROTOCOL instance. + @param This The pointer to the EFI_MTFTP4_PROTOCOL instance. @param PacketLen Length of the OACK packet to be parsed. - @param Packet Pointer to the OACK packet to be parsed. - @param OptionCount Pointer to the number of options in following OptionList. - @param OptionList Pointer to EFI_MTFTP4_OPTION storage. Call the EFI Boot - Service FreePool() to release each option if they are not - needed any more. + @param Packet The pointer to the OACK packet to be parsed. + @param OptionCount The pointer to the number of options in following OptionList. + @param 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. @retval EFI_SUCCESS The OACK packet was valid and the OptionCount and OptionList parameters have been updated. @@ -370,49 +385,54 @@ EFI_STATUS @retval EFI_PROTOCOL_ERROR One or more of the option fields is invalid. **/ -typedef -EFI_STATUS +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 OPTIONAL - ); + ); /** Downloads a file from an MTFTPv4 server. - @param This Pointer to the EFI_MTFTP4_PROTOCOL instance. - @param Token Pointer to the token structure to provide the parameters that are + @param This The pointer to the EFI_MTFTP4_PROTOCOL instance. + @param Token The pointer to the token structure to provide the parameters that are used in this operation. - @retval EFI_SUCCESS The data file has been transferred successfully. - @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. - @retval EFI_BUFFER_TOO_SMALL BufferSize is not large enough to hold the downloaded data - in downloading process. - @retval EFI_ABORTED Current operation is aborted by user. - @retval EFI_ICMP_ERROR An ICMP ERROR packet was received. - @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server. - @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received. - @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred. + @retval EFI_SUCCESS The data file has been transferred successfully. + @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. + @retval EFI_BUFFER_TOO_SMALL BufferSize is not zero but not large enough to hold the + downloaded data in downloading process. + @retval EFI_ABORTED Current operation is aborted by user. + @retval EFI_NETWORK_UNREACHABLE An ICMP network unreachable error packet was received. + @retval EFI_HOST_UNREACHABLE An ICMP host unreachable error packet was received. + @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received. + @retval EFI_PORT_UNREACHABLE An ICMP port unreachable error packet was received. + @retval EFI_ICMP_ERROR Some other ICMP ERROR packet was received. + @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server. + @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received. + @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred. + @retval EFI_NO_MEDIA There was a media error. **/ -typedef -EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_MTFTP4_READ_FILE)( IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token - ); - + ); + /** Sends a file to an MTFTPv4 server. - @param This Pointer to the EFI_MTFTP4_PROTOCOL instance. - @param Token Pointer to the token structure to provide the parameters that are + @param This The pointer to the EFI_MTFTP4_PROTOCOL instance. + @param Token The pointer to the token structure to provide the parameters that are used in this operation. @retval EFI_SUCCESS The upload session has started. @@ -429,20 +449,20 @@ EFI_STATUS @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred. **/ -typedef -EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_MTFTP4_WRITE_FILE)( 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. + implementations. - @param This Pointer to the EFI_MTFTP4_PROTOCOL instance. - @param Token Pointer to the token structure to provide the parameters that are + @param This The pointer to the EFI_MTFTP4_PROTOCOL instance. + @param Token The pointer to the token structure to provide the parameters that are used in this operation. @retval EFI_SUCCESS The MTFTPv4 related file "directory" has been downloaded. @@ -459,17 +479,17 @@ EFI_STATUS @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred. **/ -typedef -EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_MTFTP4_READ_DIRECTORY)( IN EFI_MTFTP4_PROTOCOL *This, IN EFI_MTFTP4_TOKEN *Token - ); + ); /** Polls for incoming data packets and processes outgoing data packets. - @param This Pointer to the EFI_MTFTP4_PROTOCOL instance. + @param This The pointer to the EFI_MTFTP4_PROTOCOL instance. @retval EFI_SUCCESS Incoming or outgoing data was processed. @retval EFI_NOT_STARTED This EFI MTFTPv4 Protocol instance has not been started. @@ -485,13 +505,13 @@ typedef EFI_STATUS (EFIAPI *EFI_MTFTP4_POLL)( IN EFI_MTFTP4_PROTOCOL *This - ); - + ); + /// -/// The EFI_MTFTP4_PROTOCOL is designed to be used by UEFI drivers and applications -/// to transmit and receive data files. The EFI MTFTPv4 Protocol driver uses +/// The EFI_MTFTP4_PROTOCOL is designed to be used by UEFI drivers and applications +/// to transmit and receive data files. The EFI MTFTPv4 Protocol driver uses /// the underlying EFI UDPv4 Protocol driver and EFI IPv4 Protocol driver. -/// +/// struct _EFI_MTFTP4_PROTOCOL { EFI_MTFTP4_GET_MODE_DATA GetModeData; EFI_MTFTP4_CONFIGURE Configure; @@ -522,11 +542,11 @@ struct _EFI_MTFTP4_TOKEN { /// EFI_MTFTP4_OVERRIDE_DATA *OverrideData; /// - /// Pointer to the ASCIIZ file name string. + /// The pointer to the null-terminated ASCII file name string. /// UINT8 *Filename; /// - /// Pointer to the ASCIIZ mode string. If NULL, ¡°octet¡± is used. + /// The pointer to the null-terminated ASCII mode string. If NULL, "octet" is used. /// UINT8 *ModeStr; /// @@ -534,35 +554,40 @@ struct _EFI_MTFTP4_TOKEN { /// UINT32 OptionCount; /// - /// Pointer to an array of option/value string pairs. Ignored if OptionCount is zero. + /// The pointer to an array of option/value string pairs. Ignored if OptionCount is zero. /// EFI_MTFTP4_OPTION *OptionList; /// - /// Size of the data buffer. + /// The size of the data buffer. /// - OUT UINT64 BufferSize; + UINT64 BufferSize; /// - /// Pointer to the data buffer. Data that is downloaded from the + /// The pointer to the data buffer. Data that is downloaded from the /// MTFTPv4 server is stored here. Data that is uploaded to the /// MTFTPv4 server is read from here. Ignored if BufferSize is zero. /// - OUT VOID *Buffer; + VOID *Buffer; + /// + /// The pointer to the context that will be used by CheckPacket, + /// TimeoutCallback and PacketNeeded. + /// + VOID *Context; /// - /// Pointer to the callback function to check the contents of the received packet. + /// The pointer to the callback function to check the contents of the received packet. /// EFI_MTFTP4_CHECK_PACKET CheckPacket; /// - /// Pointer to the function to be called when a timeout occurs. + /// The pointer to the function to be called when a timeout occurs. /// EFI_MTFTP4_TIMEOUT_CALLBACK TimeoutCallback; /// - /// Pointer to the function to provide the needed packet contents. + /// The pointer to the function to provide the needed packet contents. /// EFI_MTFTP4_PACKET_NEEDED PacketNeeded; }; extern EFI_GUID gEfiMtftp4ServiceBindingProtocolGuid; -extern EFI_GUID gEfiMtftp4ProtocolGuid; +extern EFI_GUID gEfiMtftp4ProtocolGuid; #endif