diff options
Diffstat (limited to 'src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/Ftp4.h')
| -rw-r--r-- | src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/Ftp4.h | 524 |
1 files changed, 524 insertions, 0 deletions
diff --git a/src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/Ftp4.h b/src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/Ftp4.h new file mode 100644 index 0000000000..113e84a22d --- /dev/null +++ b/src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/Ftp4.h @@ -0,0 +1,524 @@ +/** @file + EFI FTPv4 (File Transfer Protocol version 4) Protocol Definition + The EFI FTPv4 Protocol is used to locate communication devices that are + supported by an EFI FTPv4 Protocol driver and to create and destroy instances + of the EFI FTPv4 Protocol child protocol driver that can use the underlying + communication device. + The definitions in this file are defined in UEFI Specification 2.3, which have + not been verified by one implementation yet. + + Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR> + 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 + + 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.2 + +**/ + +#ifndef __EFI_FTP4_PROTOCOL_H__ +#define __EFI_FTP4_PROTOCOL_H__ + + +#define EFI_FTP4_SERVICE_BINDING_PROTOCOL_GUID \ + { \ + 0xfaaecb1, 0x226e, 0x4782, {0xaa, 0xce, 0x7d, 0xb9, 0xbc, 0xbf, 0x4d, 0xaf } \ + } + +#define EFI_FTP4_PROTOCOL_GUID \ + { \ + 0xeb338826, 0x681b, 0x4295, {0xb3, 0x56, 0x2b, 0x36, 0x4c, 0x75, 0x7b, 0x9 } \ + } + +typedef struct _EFI_FTP4_PROTOCOL EFI_FTP4_PROTOCOL; + +/// +/// EFI_FTP4_CONNECTION_TOKEN +/// +typedef struct { + /// + /// The Event to signal after the connection is established and Status field is updated + /// by the EFI FTP v4 Protocol driver. The type of Event must be + /// EVENT_NOTIFY_SIGNAL, and its Task Priority Level (TPL) must be lower than or + /// equal to TPL_CALLBACK. If it is set to NULL, this function will not return until the + /// function completes. + /// + EFI_EVENT Event; + /// + /// The variable to receive the result of the completed operation. + /// EFI_SUCCESS: The FTP connection is established successfully + /// EFI_ACCESS_DENIED: The FTP server denied the access the user's request to access it. + /// EFI_CONNECTION_RESET: The connect fails because the connection is reset either by instance + /// itself or communication peer. + /// EFI_TIMEOUT: The connection establishment timer expired and no more specific + /// information is available. + /// EFI_NETWORK_UNREACHABLE: The active open fails because an ICMP network unreachable error is + /// received. + /// EFI_HOST_UNREACHABLE: The active open fails because an ICMP host unreachable error is + /// received. + /// EFI_PROTOCOL_UNREACHABLE: The active open fails because an ICMP protocol unreachable error is + /// received. + /// EFI_PORT_UNREACHABLE: The connection establishment timer times out and an ICMP port + /// unreachable error is received. + /// EFI_ICMP_ERROR: The connection establishment timer timeout and some other ICMP + /// error is received. + /// EFI_DEVICE_ERROR: An unexpected system or network error occurred. + /// + EFI_STATUS Status; +} EFI_FTP4_CONNECTION_TOKEN; + +/// +/// EFI_FTP4_CONFIG_DATA +/// +typedef struct { + /// + /// Pointer to a ASCII string that contains user name. The caller is + /// responsible for freeing Username after GetModeData() is called. + /// + UINT8 *Username; + /// + /// Pointer to a ASCII string that contains password. The caller is + /// responsible for freeing Password after GetModeData() is called. + /// + UINT8 *Password; + /// + /// Set it to TRUE to initiate an active data connection. Set it to + /// FALSE to initiate a passive data connection. + /// + BOOLEAN Active; + /// + /// Boolean value indicating if default network settting used. + /// + BOOLEAN UseDefaultSetting; + /// + /// IP address of station if UseDefaultSetting is FALSE. + /// + EFI_IPv4_ADDRESS StationIp; + /// + /// Subnet mask of station if UseDefaultSetting is FALSE. + /// + EFI_IPv4_ADDRESS SubnetMask; + /// + /// IP address of gateway if UseDefaultSetting is FALSE. + /// + EFI_IPv4_ADDRESS GatewayIp; + /// + /// IP address of FTPv4 server. + /// + EFI_IPv4_ADDRESS ServerIp; + /// + /// FTPv4 server port number of control connection, and the default + /// value is 21 as convention. + /// + UINT16 ServerPort; + /// + /// FTPv4 server port number of data connection. If it is zero, use + /// (ServerPort - 1) by convention. + /// + UINT16 AltDataPort; + /// + /// A byte indicate the representation type. The right 4 bit is used for + /// first parameter, the left 4 bit is use for second parameter + /// - For the first parameter, 0x0 = image, 0x1 = EBCDIC, 0x2 = ASCII, 0x3 = local + /// - For the second parameter, 0x0 = Non-print, 0x1 = Telnet format effectors, 0x2 = + /// Carriage Control. + /// - If it is a local type, the second parameter is the local byte byte size. + /// - If it is a image type, the second parameter is undefined. + /// + UINT8 RepType; + /// + /// Defines the file structure in FTP used. 0x00 = file, 0x01 = record, 0x02 = page. + /// + UINT8 FileStruct; + /// + /// Defines the transifer mode used in FTP. 0x00 = stream, 0x01 = Block, 0x02 = Compressed. + /// + UINT8 TransMode; +} EFI_FTP4_CONFIG_DATA; + +typedef struct _EFI_FTP4_COMMAND_TOKEN EFI_FTP4_COMMAND_TOKEN; + +/** + Callback function when process inbound or outbound data. + + If it is receiving function that leads to inbound data, the callback function + is called when data buffer is full. Then, old data in the data buffer should be + flushed and new data is stored from the beginning of data buffer. + If it is a transmit function that lead to outbound data and the size of + Data in daata buffer has been transmitted, this callback function is called to + supply additional data to be transmitted. + + @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. + @param[in] Token Pointer to the token structure to provide the parameters that + are used in this operation. + @return User defined Status. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_FTP4_DATA_CALLBACK)( + IN EFI_FTP4_PROTOCOL *This, + IN EFI_FTP4_COMMAND_TOKEN *Token + ); + +/// +/// EFI_FTP4_COMMAND_TOKEN +/// +struct _EFI_FTP4_COMMAND_TOKEN { + /// + /// The Event to signal after request is finished and Status field + /// is updated by the EFI FTP v4 Protocol driver. The type of Event + /// must be EVT_NOTIFY_SIGNAL, and its Task Priority Level + /// (TPL) must be lower than or equal to TPL_CALLBACK. If it is + /// set to NULL, related function must wait until the function + /// completes. + /// + EFI_EVENT Event; + /// + /// Pointer to a null-terminated ASCII name string. + /// + UINT8 *Pathname; + /// + /// The size of data buffer in bytes. + /// + UINT64 DataBufferSize; + /// + /// Pointer to the data buffer. Data downloaded from FTP server + /// through connection is downloaded here. + /// + VOID *DataBuffer; + /// + /// Pointer to a callback function. If it is receiving function that leads + /// to inbound data, the callback function is called when databuffer is + /// full. Then, old data in the data buffer should be flushed and new + /// data is stored from the beginning of data buffer. If it is a transmit + /// function that lead to outbound data and DataBufferSize of + /// Data in DataBuffer has been transmitted, this callback + /// function is called to supply additional data to be transmitted. The + /// size of additional data to be transmitted is indicated in + /// DataBufferSize, again. If there is no data remained, + /// DataBufferSize should be set to 0. + /// + EFI_FTP4_DATA_CALLBACK DataCallback; + /// + /// Pointer to the parameter for DataCallback. + /// + VOID *Context; + /// + /// The variable to receive the result of the completed operation. + /// EFI_SUCCESS: The FTP command is completed successfully. + /// EFI_ACCESS_DENIED: The FTP server denied the access to the requested file. + /// EFI_CONNECTION_RESET: The connect fails because the connection is reset either + /// by instance itself or communication peer. + /// EFI_TIMEOUT: The connection establishment timer expired and no more + /// specific information is available. + /// EFI_NETWORK_UNREACHABLE: The active open fails because an ICMP network unreachable + /// error is received. + /// EFI_HOST_UNREACHABLE: The active open fails because an ICMP host unreachable + /// error is received. + /// EFI_PROTOCOL_UNREACHABLE: The active open fails because an ICMP protocol unreachable + /// error is received. + /// EFI_PORT_UNREACHABLE: The connection establishment timer times out and an ICMP port + /// unreachable error is received. + /// EFI_ICMP_ERROR: The connection establishment timer timeout and some other ICMP + /// error is received. + /// EFI_DEVICE_ERROR: An unexpected system or network error occurred. + /// + EFI_STATUS Status; +}; + +/** + Gets the current operational settings. + + The GetModeData() function reads the current operational settings of this + EFI FTPv4 Protocol driver instance. EFI_FTP4_CONFIG_DATA is defined in the + EFI_FTP4_PROTOCOL.Configure. + + @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. + @param[out] ModeData Pointer to storage for the EFI FTPv4 Protocol driver + mode data. The string buffers for Username and Password + in EFI_FTP4_CONFIG_DATA are allocated by the function, + and the caller should take the responsibility to free the + buffer later. + + @retval EFI_SUCCESS This function is called successfully. + @retval EFI_INVALID_PARAMETER One or more of the following are TRUE: + - This is NULL. + - ModeData is NULL. + @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started + @retval EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation. + @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_FTP4_GET_MODE_DATA)( + IN EFI_FTP4_PROTOCOL *This, + OUT EFI_FTP4_CONFIG_DATA *ModeData + ); + +/** + Disconnecting a FTP connection gracefully. + + The Connect() function will initiate a connection request to the remote FTP server + with the corresponding connection token. If this function returns EFI_SUCCESS, the + connection sequence is initiated successfully. If the connection succeeds or faild + due to any error, the Token->Event will be signaled and Token->Status will be updated + accordingly. + + @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. + @param[in] Token Pointer to the token used to establish control connection. + + @retval EFI_SUCCESS The connection sequence is successfully initiated. + @retval EFI_INVALID_PARAMETER One or more of the following are TRUE: + - This is NULL. + - Token is NULL. + - Token->Event is NULL. + @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started. + @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, + RARP, etc.) is not finished yet. + @retval EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation. + @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_FTP4_CONNECT)( + IN EFI_FTP4_PROTOCOL *This, + IN EFI_FTP4_CONNECTION_TOKEN *Token + ); + +/** + Disconnecting a FTP connection gracefully. + + The Close() function will initiate a close request to the remote FTP server with the + corresponding connection token. If this function returns EFI_SUCCESS, the control + connection with the remote FTP server is closed. + + @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. + @param[in] Token Pointer to the token used to close control connection. + + @retval EFI_SUCCESS The close request is successfully initiated. + @retval EFI_INVALID_PARAMETER One or more of the following are TRUE: + - This is NULL. + - Token is NULL. + - Token->Event is NULL. + @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started. + @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, + RARP, etc.) is not finished yet. + @retval EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation. + @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_FTP4_CLOSE)( + IN EFI_FTP4_PROTOCOL *This, + IN EFI_FTP4_CONNECTION_TOKEN *Token + ); + +/** + Sets or clears the operational parameters for the FTP child driver. + + The Configure() function will configure the connected FTP session with the + configuration setting specified in FtpConfigData. The configuration data can + be reset by calling Configure() with FtpConfigData set to NULL. + + @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. + @param[in] FtpConfigData Pointer to configuration data that will be assigned to + the FTP child driver instance. If NULL, the FTP child + driver instance is reset to startup defaults and all + pending transmit and receive requests are flushed. + + @retval EFI_SUCCESS The FTPv4 driver was configured successfully. + @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE: + - This is NULL. + - FtpConfigData.RepType is invalid. + - FtpConfigData.FileStruct is invalid. + - FtpConfigData.TransMode is invalid. + - IP address in FtpConfigData is invalid. + @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, + RARP, etc.) is not finished yet. + @retval EFI_UNSUPPORTED One or more of the configuration parameters are not supported + by this implementation. + @retval EFI_OUT_OF_RESOURCES The EFI FTPv4 Protocol driver instance data could not be + allocated. + @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI FTPv4 + Protocol driver instance is not configured. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_FTP4_CONFIGURE)( + IN EFI_FTP4_PROTOCOL *This, + IN EFI_FTP4_CONFIG_DATA *FtpConfigData OPTIONAL + ); + + +/** + Downloads a file from an FTPv4 server. + + The ReadFile() function is used to initialize and start an FTPv4 download process + and optionally wait for completion. When the download operation completes, whether + successfully or not, the Token.Status field is updated by the EFI FTPv4 Protocol + driver and then Token.Event is signaled (if it is not NULL). + + Data will be downloaded from the FTPv4 server into Token.DataBuffer. If the file size + is larger than Token.DataBufferSize, Token.DataCallback will be called to allow for + processing data and then new data will be placed at the beginning of Token.DataBuffer. + + @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. + @param[in] Token Pointer to the token structure to provide the parameters that + are used in this operation. + + @retval EFI_SUCCESS The data file is being downloaded successfully. + @retval EFI_INVALID_PARAMETER One or more of the parameters is not valid. + - This is NULL. + - Token is NULL. + - Token.Pathname is NULL. + - Token. DataBuffer is NULL. + - Token. DataBufferSize is 0. + @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started. + @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, + RARP, etc.) is not finished yet. + @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. + @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_FTP4_READ_FILE)( + IN EFI_FTP4_PROTOCOL *This, + IN EFI_FTP4_COMMAND_TOKEN *Token + ); + +/** + Uploads a file from an FTPv4 server. + + The WriteFile() function is used to initialize and start an FTPv4 upload process and + optionally wait for completion. When the upload operation completes, whether successfully + or not, the Token.Status field is updated by the EFI FTPv4 Protocol driver and then + Token.Event is signaled (if it is not NULL). Data to be uploaded to server is stored + into Token.DataBuffer. Token.DataBufferSize is the number bytes to be transferred. + If the file size is larger than Token.DataBufferSize, Token.DataCallback will be called + to allow for processing data and then new data will be placed at the beginning of + Token.DataBuffer. Token.DataBufferSize is updated to reflect the actual number of bytes + to be transferred. Token.DataBufferSize is set to 0 by the call back to indicate the + completion of data transfer. + + @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. + @param[in] Token Pointer to the token structure to provide the parameters that + are used in this operation. + + @retval EFI_SUCCESS TThe data file is being uploaded successfully. + @retval EFI_UNSUPPORTED The operation is not supported by this implementation. + @retval EFI_INVALID_PARAMETER One or more of the parameters is not valid. + - This is NULL. + - Token is NULL. + - Token.Pathname is NULL. + - Token. DataBuffer is NULL. + - Token. DataBufferSize is 0. + @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started. + @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, + RARP, etc.) is not finished yet. + @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. + @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_FTP4_WRITE_FILE)( + IN EFI_FTP4_PROTOCOL *This, + IN EFI_FTP4_COMMAND_TOKEN *Token + ); + +/** + Download a data file "directory" from a FTPv4 server. May be unsupported in some EFI + implementations. + + The ReadDirectory() function is used to return a list of files on the FTPv4 server that + logically (or operationally) related to Token.Pathname, and optionally wait for completion. + When the download operation completes, whether successfully or not, the Token.Status field + is updated by the EFI FTPv4 Protocol driver and then Token.Event is signaled (if it is not + NULL). Data will be downloaded from the FTPv4 server into Token.DataBuffer. If the file size + is larger than Token.DataBufferSize, Token.DataCallback will be called to allow for processing + data and then new data will be placed at the beginning of Token.DataBuffer. + + @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. + @param[in] Token Pointer to the token structure to provide the parameters that + are used in this operation. + + @retval EFI_SUCCESS The file list information is being downloaded successfully. + @retval EFI_UNSUPPORTED The operation is not supported by this implementation. + @retval EFI_INVALID_PARAMETER One or more of the parameters is not valid. + - This is NULL. + - Token is NULL. + - Token. DataBuffer is NULL. + - Token. DataBufferSize is 0. + @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started. + @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, + RARP, etc.) is not finished yet. + @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. + @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_FTP4_READ_DIRECTORY)( + IN EFI_FTP4_PROTOCOL *This, + IN EFI_FTP4_COMMAND_TOKEN *Token + ); + +/** + Polls for incoming data packets and processes outgoing data packets. + + The Poll() function can be used by network drivers and applications to increase the + rate that data packets are moved between the communications device and the transmit + and receive queues. In some systems, the periodic timer event in the managed network + driver may not poll the underlying communications device fast enough to transmit + and/or receive all data packets without missing incoming packets or dropping outgoing + packets. Drivers and applications that are experiencing packet loss should try calling + the Poll() function more often. + + @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. + + @retval EFI_SUCCESS Incoming or outgoing data was processed. + @retval EFI_NOT_STARTED This EFI FTPv4 Protocol instance has not been started. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_DEVICE_ERROR EapAuthType An unexpected system or network error occurred. + @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue. + Consider increasing the polling rate. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_FTP4_POLL)( + IN EFI_FTP4_PROTOCOL *This + ); + +/// +/// EFI_FTP4_PROTOCOL +/// provides basic services for client-side FTP (File Transfer Protocol) +/// operations. +/// +struct _EFI_FTP4_PROTOCOL { + EFI_FTP4_GET_MODE_DATA GetModeData; + EFI_FTP4_CONNECT Connect; + EFI_FTP4_CLOSE Close; + EFI_FTP4_CONFIGURE Configure; + EFI_FTP4_READ_FILE ReadFile; + EFI_FTP4_WRITE_FILE WriteFile; + EFI_FTP4_READ_DIRECTORY ReadDirectory; + EFI_FTP4_POLL Poll; +}; + +extern EFI_GUID gEfiFtp4ServiceBindingProtocolGuid; +extern EFI_GUID gEfiFtp4ProtocolGuid; + +#endif + |