MdePkg/Include/Protocol/Ftp4.h File Reference


Data Structures

struct  EFI_FTP4_CONNECTION_TOKEN
struct  EFI_FTP4_CONFIG_DATA
struct  _EFI_FTP4_COMMAND_TOKEN
struct  _EFI_FTP4_PROTOCOL

Defines

#define EFI_FTP4_SERVICE_BINDING_PROTOCOL_GUID
#define EFI_FTP4_PROTOCOL_GUID

Typedefs

typedef struct _EFI_FTP4_PROTOCOL EFI_FTP4_PROTOCOL
typedef struct
_EFI_FTP4_COMMAND_TOKEN 
EFI_FTP4_COMMAND_TOKEN
typedef EFI_STATUS(EFIAPIEFI_FTP4_DATA_CALLBACK )(IN EFI_FTP4_PROTOCOL *This, IN EFI_FTP4_COMMAND_TOKEN *Token)
typedef EFI_STATUS(EFIAPIEFI_FTP4_GET_MODE_DATA )(IN EFI_FTP4_PROTOCOL *This, OUT EFI_FTP4_CONFIG_DATA *ModeData)
typedef EFI_STATUS(EFIAPIEFI_FTP4_CONNECT )(IN EFI_FTP4_PROTOCOL *This, IN EFI_FTP4_CONNECTION_TOKEN *Token)
typedef EFI_STATUS(EFIAPIEFI_FTP4_CLOSE )(IN EFI_FTP4_PROTOCOL *This, IN EFI_FTP4_CONNECTION_TOKEN *Token)
typedef EFI_STATUS(EFIAPIEFI_FTP4_CONFIGURE )(IN EFI_FTP4_PROTOCOL *This, IN EFI_FTP4_CONFIG_DATA *FtpConfigData)
typedef EFI_STATUS(EFIAPIEFI_FTP4_READ_FILE )(IN EFI_FTP4_PROTOCOL *This, IN EFI_FTP4_COMMAND_TOKEN *Token)
typedef EFI_STATUS(EFIAPIEFI_FTP4_WRITE_FILE )(IN EFI_FTP4_PROTOCOL *This, IN EFI_FTP4_COMMAND_TOKEN *Token)
typedef EFI_STATUS(EFIAPIEFI_FTP4_READ_DIRECTORY )(IN EFI_FTP4_PROTOCOL *This, IN EFI_FTP4_COMMAND_TOKEN *Token)
typedef EFI_STATUS(EFIAPIEFI_FTP4_POLL )(IN EFI_FTP4_PROTOCOL *This)

Variables

EFI_GUID gEfiFtp4ServiceBindingProtocolGuid
EFI_GUID gEfiFtp4ProtocolGuid

Detailed Description

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.
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.

Revision Reference:
This Protocol is introduced in UEFI Specification 2.2

Define Documentation

#define EFI_FTP4_PROTOCOL_GUID

Value:

{ \
    0xeb338826, 0x681b, 0x4295, {0xb3, 0x56, 0x2b, 0x36, 0x4c, 0x75, 0x7b, 0x9 } \
  }

#define EFI_FTP4_SERVICE_BINDING_PROTOCOL_GUID

Value:

{ \
    0xfaaecb1, 0x226e, 0x4782, {0xaa, 0xce, 0x7d, 0xb9, 0xbc, 0xbf, 0x4d, 0xaf } \
  }


Typedef Documentation

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.

Parameters:
[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
[in] Token Pointer to the token used to close control connection.
Return values:
EFI_SUCCESS The close request is successfully initiated.
EFI_INVALID_PARAMETER One or more of the following are TRUE:
  • This is NULL.
  • Token is NULL.
  • Token->Event is NULL.
EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started.
EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet.
EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation.
EFI_DEVICE_ERROR An unexpected system or network error occurred.

typedef EFI_STATUS(EFIAPI * EFI_FTP4_CONFIGURE)(IN EFI_FTP4_PROTOCOL *This, IN EFI_FTP4_CONFIG_DATA *FtpConfigData)

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.

Parameters:
[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
[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.
Return values:
EFI_SUCCESS The FTPv4 driver was configured successfully.
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.
EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet.
EFI_UNSUPPORTED One or more of the configuration parameters are not supported by this implementation.
EFI_OUT_OF_RESOURCES The EFI FTPv4 Protocol driver instance data could not be allocated.
EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI FTPv4 Protocol driver instance is not configured.

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.

Parameters:
[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
[in] Token Pointer to the token used to establish control connection.
Return values:
EFI_SUCCESS The connection sequence is successfully initiated.
EFI_INVALID_PARAMETER One or more of the following are TRUE:
  • This is NULL.
  • Token is NULL.
  • Token->Event is NULL.
EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started.
EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet.
EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation.
EFI_DEVICE_ERROR An unexpected system or network error occurred.

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.

Parameters:
[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
[in] Token Pointer to the token structure to provide the parameters that are used in this operation.
Returns:
User defined Status.

typedef EFI_STATUS(EFIAPI * EFI_FTP4_GET_MODE_DATA)(IN EFI_FTP4_PROTOCOL *This, OUT EFI_FTP4_CONFIG_DATA *ModeData)

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.

Parameters:
[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
[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.
Return values:
EFI_SUCCESS This function is called successfully.
EFI_INVALID_PARAMETER One or more of the following are TRUE:
  • This is NULL.
  • ModeData is NULL.
EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started
EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation.
EFI_DEVICE_ERROR An unexpected system or network error occurred.

typedef EFI_STATUS(EFIAPI * EFI_FTP4_POLL)(IN EFI_FTP4_PROTOCOL *This)

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.

Parameters:
[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
Return values:
EFI_SUCCESS Incoming or outgoing data was processed.
EFI_NOT_STARTED This EFI FTPv4 Protocol instance has not been started.
EFI_INVALID_PARAMETER This is NULL.
EFI_DEVICE_ERROR EapAuthType 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.

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.

Parameters:
[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
[in] Token Pointer to the token structure to provide the parameters that are used in this operation.
Return values:
EFI_SUCCESS The file list information is being downloaded successfully.
EFI_UNSUPPORTED The operation is not supported by this implementation.
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.
EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started.
EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet.
EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
EFI_DEVICE_ERROR An unexpected network error or system error occurred.

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.

Parameters:
[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
[in] Token Pointer to the token structure to provide the parameters that are used in this operation.
Return values:
EFI_SUCCESS The data file is being downloaded successfully.
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.
EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started.
EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet.
EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
EFI_DEVICE_ERROR An unexpected network error or system error occurred.

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.

Parameters:
[in] This Pointer to the EFI_FTP4_PROTOCOL instance.
[in] Token Pointer to the token structure to provide the parameters that are used in this operation.
Return values:
EFI_SUCCESS TThe data file is being uploaded successfully.
EFI_UNSUPPORTED The operation is not supported by this implementation.
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.
EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started.
EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet.
EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
EFI_DEVICE_ERROR An unexpected network error or system error occurred.


Variable Documentation


Generated on Thu Sep 24 23:14:20 2015 for MdePkg[ALL] by  doxygen 1.5.7.1