| /** @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 - 2018, Intel Corporation. All rights reserved.<BR> |
| SPDX-License-Identifier: BSD-2-Clause-Patent |
| |
| @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 |
| |