iPXE
Mtftp4.h
Go to the documentation of this file.
00001 /** @file
00002   EFI Multicast Trivial File Transfer Protocol Definition
00003 
00004 Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
00005 This program and the accompanying materials are licensed and made available under
00006 the terms and conditions of the BSD License that accompanies this distribution.
00007 The full text of the license may be found at
00008 http://opensource.org/licenses/bsd-license.php.
00009 
00010 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00011 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00012 
00013   @par Revision Reference:
00014   This Protocol is introduced in UEFI Specification 2.0
00015 
00016 **/
00017 
00018 #ifndef __EFI_MTFTP4_PROTOCOL_H__
00019 #define __EFI_MTFTP4_PROTOCOL_H__
00020 
00021 FILE_LICENCE ( BSD3 );
00022 
00023 #define EFI_MTFTP4_SERVICE_BINDING_PROTOCOL_GUID \
00024   { \
00025     0x2FE800BE, 0x8F01, 0x4aa6, {0x94, 0x6B, 0xD7, 0x13, 0x88, 0xE1, 0x83, 0x3F } \
00026   }
00027 
00028 #define EFI_MTFTP4_PROTOCOL_GUID \
00029   { \
00030     0x78247c57, 0x63db, 0x4708, {0x99, 0xc2, 0xa8, 0xb4, 0xa9, 0xa6, 0x1f, 0x6b } \
00031   }
00032 
00033 typedef struct _EFI_MTFTP4_PROTOCOL EFI_MTFTP4_PROTOCOL;
00034 typedef struct _EFI_MTFTP4_TOKEN EFI_MTFTP4_TOKEN;
00035 
00036 //
00037 //MTFTP4 packet opcode definition
00038 //
00039 #define EFI_MTFTP4_OPCODE_RRQ                     1
00040 #define EFI_MTFTP4_OPCODE_WRQ                     2
00041 #define EFI_MTFTP4_OPCODE_DATA                    3
00042 #define EFI_MTFTP4_OPCODE_ACK                     4
00043 #define EFI_MTFTP4_OPCODE_ERROR                   5
00044 #define EFI_MTFTP4_OPCODE_OACK                    6
00045 #define EFI_MTFTP4_OPCODE_DIR                     7
00046 #define EFI_MTFTP4_OPCODE_DATA8                   8
00047 #define EFI_MTFTP4_OPCODE_ACK8                    9
00048 
00049 //
00050 // MTFTP4 error code definition
00051 //
00052 #define EFI_MTFTP4_ERRORCODE_NOT_DEFINED          0
00053 #define EFI_MTFTP4_ERRORCODE_FILE_NOT_FOUND       1
00054 #define EFI_MTFTP4_ERRORCODE_ACCESS_VIOLATION     2
00055 #define EFI_MTFTP4_ERRORCODE_DISK_FULL            3
00056 #define EFI_MTFTP4_ERRORCODE_ILLEGAL_OPERATION    4
00057 #define EFI_MTFTP4_ERRORCODE_UNKNOWN_TRANSFER_ID  5
00058 #define EFI_MTFTP4_ERRORCODE_FILE_ALREADY_EXISTS  6
00059 #define EFI_MTFTP4_ERRORCODE_NO_SUCH_USER         7
00060 #define EFI_MTFTP4_ERRORCODE_REQUEST_DENIED       8
00061 
00062 //
00063 // MTFTP4 pacekt definitions
00064 //
00065 #pragma pack(1)
00066 
00067 typedef struct {
00068   UINT16                  OpCode;
00069   UINT8                   Filename[1];
00070 } EFI_MTFTP4_REQ_HEADER;
00071 
00072 typedef struct {
00073   UINT16                  OpCode;
00074   UINT8                   Data[1];
00075 } EFI_MTFTP4_OACK_HEADER;
00076 
00077 typedef struct {
00078   UINT16                  OpCode;
00079   UINT16                  Block;
00080   UINT8                   Data[1];
00081 } EFI_MTFTP4_DATA_HEADER;
00082 
00083 typedef struct {
00084   UINT16                  OpCode;
00085   UINT16                  Block[1];
00086 } EFI_MTFTP4_ACK_HEADER;
00087 
00088 typedef struct {
00089   UINT16                  OpCode;
00090   UINT64                  Block;
00091   UINT8                   Data[1];
00092 } EFI_MTFTP4_DATA8_HEADER;
00093 
00094 typedef struct {
00095   UINT16                  OpCode;
00096   UINT64                  Block[1];
00097 } EFI_MTFTP4_ACK8_HEADER;
00098 
00099 typedef struct {
00100   UINT16                  OpCode;
00101   UINT16                  ErrorCode;
00102   UINT8                   ErrorMessage[1];
00103 } EFI_MTFTP4_ERROR_HEADER;
00104 
00105 typedef union {
00106   ///
00107   /// Type of packets as defined by the MTFTPv4 packet opcodes.
00108   ///
00109   UINT16                  OpCode;
00110   ///
00111   /// Read request packet header.
00112   ///
00113   EFI_MTFTP4_REQ_HEADER   Rrq;
00114   ///
00115   /// Write request packet header.
00116   ///
00117   EFI_MTFTP4_REQ_HEADER   Wrq;
00118   ///
00119   /// Option acknowledge packet header.
00120   ///
00121   EFI_MTFTP4_OACK_HEADER  Oack;
00122   ///
00123   /// Data packet header.
00124   ///
00125   EFI_MTFTP4_DATA_HEADER  Data;
00126   ///
00127   /// Acknowledgement packet header.
00128   ///
00129   EFI_MTFTP4_ACK_HEADER   Ack;
00130   ///
00131   /// Data packet header with big block number.
00132   ///
00133   EFI_MTFTP4_DATA8_HEADER Data8;
00134   ///
00135   /// Acknowledgement header with big block num.
00136   ///
00137   EFI_MTFTP4_ACK8_HEADER  Ack8;
00138   ///
00139   /// Error packet header.
00140   ///
00141   EFI_MTFTP4_ERROR_HEADER Error;
00142 } EFI_MTFTP4_PACKET;
00143 
00144 #pragma pack()
00145 
00146 ///
00147 /// MTFTP4 option definition.
00148 ///
00149 typedef struct {
00150   UINT8                   *OptionStr;
00151   UINT8                   *ValueStr;
00152 } EFI_MTFTP4_OPTION;
00153 
00154 
00155 typedef struct {
00156   BOOLEAN                 UseDefaultSetting;
00157   EFI_IPv4_ADDRESS        StationIp;
00158   EFI_IPv4_ADDRESS        SubnetMask;
00159   UINT16                  LocalPort;
00160   EFI_IPv4_ADDRESS        GatewayIp;
00161   EFI_IPv4_ADDRESS        ServerIp;
00162   UINT16                  InitialServerPort;
00163   UINT16                  TryCount;
00164   UINT16                  TimeoutValue;
00165 } EFI_MTFTP4_CONFIG_DATA;
00166 
00167 
00168 typedef struct {
00169   EFI_MTFTP4_CONFIG_DATA  ConfigData;
00170   UINT8                   SupportedOptionCount;
00171   UINT8                   **SupportedOptoins;
00172   UINT8                   UnsupportedOptionCount;
00173   UINT8                   **UnsupportedOptoins;
00174 } EFI_MTFTP4_MODE_DATA;
00175 
00176 
00177 typedef struct {
00178   EFI_IPv4_ADDRESS        GatewayIp;
00179   EFI_IPv4_ADDRESS        ServerIp;
00180   UINT16                  ServerPort;
00181   UINT16                  TryCount;
00182   UINT16                  TimeoutValue;
00183 } EFI_MTFTP4_OVERRIDE_DATA;
00184 
00185 //
00186 // Protocol interfaces definition
00187 //
00188 
00189 /**
00190   A callback function that is provided by the caller to intercept
00191   the EFI_MTFTP4_OPCODE_DATA or EFI_MTFTP4_OPCODE_DATA8 packets processed in the
00192   EFI_MTFTP4_PROTOCOL.ReadFile() function, and alternatively to intercept
00193   EFI_MTFTP4_OPCODE_OACK or EFI_MTFTP4_OPCODE_ERROR packets during a call to
00194   EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory().
00195 
00196   @param  This        The pointer to the EFI_MTFTP4_PROTOCOL instance.
00197   @param  Token       The token that the caller provided in the
00198                       EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile()
00199                       or ReadDirectory() function.
00200   @param  PacketLen   Indicates the length of the packet.
00201   @param  Packet      The pointer to an MTFTPv4 packet.
00202 
00203   @retval EFI_SUCCESS The operation was successful.
00204   @retval Others      Aborts the transfer process.
00205 
00206 **/
00207 typedef
00208 EFI_STATUS
00209 (EFIAPI *EFI_MTFTP4_CHECK_PACKET)(
00210   IN EFI_MTFTP4_PROTOCOL  *This,
00211   IN EFI_MTFTP4_TOKEN     *Token,
00212   IN UINT16               PacketLen,
00213   IN EFI_MTFTP4_PACKET    *Paket
00214   );
00215 
00216 /**
00217   Timeout callback function.
00218 
00219   @param  This           The pointer to the EFI_MTFTP4_PROTOCOL instance.
00220   @param  Token          The token that is provided in the
00221                          EFI_MTFTP4_PROTOCOL.ReadFile() or
00222                          EFI_MTFTP4_PROTOCOL.WriteFile() or
00223                          EFI_MTFTP4_PROTOCOL.ReadDirectory() functions
00224                          by the caller.
00225 
00226   @retval EFI_SUCCESS   The operation was successful.
00227   @retval Others        Aborts download process.
00228 
00229 **/
00230 typedef
00231 EFI_STATUS
00232 (EFIAPI *EFI_MTFTP4_TIMEOUT_CALLBACK)(
00233   IN EFI_MTFTP4_PROTOCOL  *This,
00234   IN EFI_MTFTP4_TOKEN     *Token
00235   );
00236 
00237 /**
00238   A callback function that the caller provides to feed data to the
00239   EFI_MTFTP4_PROTOCOL.WriteFile() function.
00240 
00241   @param  This   The pointer to the EFI_MTFTP4_PROTOCOL instance.
00242   @param  Token  The token provided in the
00243                  EFI_MTFTP4_PROTOCOL.WriteFile() by the caller.
00244   @param  Length Indicates the length of the raw data wanted on input, and the
00245                  length the data available on output.
00246   @param  Buffer The pointer to the buffer where the data is stored.
00247 
00248   @retval EFI_SUCCESS The operation was successful.
00249   @retval Others      Aborts session.
00250 
00251 **/
00252 typedef
00253 EFI_STATUS
00254 (EFIAPI *EFI_MTFTP4_PACKET_NEEDED)(
00255   IN  EFI_MTFTP4_PROTOCOL *This,
00256   IN  EFI_MTFTP4_TOKEN    *Token,
00257   IN  OUT UINT16          *Length,
00258   OUT VOID                **Buffer
00259   );
00260 
00261 
00262 /**
00263   Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
00264 
00265   @param  This     The pointer to the EFI_MTFTP4_PROTOCOL instance.
00266   @param  ModeData The pointer to storage for the EFI MTFTPv4 Protocol driver mode data.
00267 
00268   @retval EFI_SUCCESS           The configuration data was successfully returned.
00269   @retval EFI_OUT_OF_RESOURCES  The required mode data could not be allocated.
00270   @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
00271 
00272 **/
00273 typedef
00274 EFI_STATUS
00275 (EFIAPI *EFI_MTFTP4_GET_MODE_DATA)(
00276   IN  EFI_MTFTP4_PROTOCOL     *This,
00277   OUT EFI_MTFTP4_MODE_DATA    *ModeData
00278   );
00279 
00280 
00281 /**
00282   Initializes, changes, or resets the default operational setting for this
00283   EFI MTFTPv4 Protocol driver instance.
00284 
00285   @param  This            The pointer to the EFI_MTFTP4_PROTOCOL instance.
00286   @param  MtftpConfigData The pointer to the configuration data structure.
00287 
00288   @retval EFI_SUCCESS           The EFI MTFTPv4 Protocol driver was configured successfully.
00289   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
00290   @retval EFI_ACCESS_DENIED     The EFI configuration could not be changed at this time because
00291                                 there is one MTFTP background operation in progress.
00292   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
00293                                 RARP, etc.) has not finished yet.
00294   @retval EFI_UNSUPPORTED       A configuration protocol (DHCP, BOOTP, RARP, etc.) could not
00295                                 be located when clients choose to use the default address
00296                                 settings.
00297   @retval EFI_OUT_OF_RESOURCES  The EFI MTFTPv4 Protocol driver instance data could not be
00298                                 allocated.
00299   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred. The EFI
00300                                  MTFTPv4 Protocol driver instance is not configured.
00301 
00302 **/
00303 typedef
00304 EFI_STATUS
00305 (EFIAPI *EFI_MTFTP4_CONFIGURE)(
00306   IN EFI_MTFTP4_PROTOCOL       *This,
00307   IN EFI_MTFTP4_CONFIG_DATA    *MtftpConfigData OPTIONAL
00308   );
00309 
00310 
00311 /**
00312   Gets information about a file from an MTFTPv4 server.
00313 
00314   @param  This         The pointer to the EFI_MTFTP4_PROTOCOL instance.
00315   @param  OverrideData Data that is used to override the existing parameters. If NULL,
00316                        the default parameters that were set in the
00317                        EFI_MTFTP4_PROTOCOL.Configure() function are used.
00318   @param  Filename     The pointer to null-terminated ASCII file name string.
00319   @param  ModeStr      The pointer to null-terminated ASCII mode string. If NULL, "octet" will be used.
00320   @param  OptionCount  Number of option/value string pairs in OptionList.
00321   @param  OptionList   The pointer to array of option/value string pairs. Ignored if
00322                        OptionCount is zero.
00323   @param  PacketLength The number of bytes in the returned packet.
00324   @param  Packet       The pointer to the received packet. This buffer must be freed by
00325                        the caller.
00326 
00327   @retval EFI_SUCCESS              An MTFTPv4 OACK packet was received and is in the Packet.
00328   @retval EFI_INVALID_PARAMETER    One or more of the following conditions is TRUE:
00329                                    - This is NULL.
00330                                    - Filename is NULL.
00331                                    - OptionCount is not zero and OptionList is NULL.
00332                                    - One or more options in OptionList have wrong format.
00333                                    - PacketLength is NULL.
00334                                    - One or more IPv4 addresses in OverrideData are not valid
00335                                      unicast IPv4 addresses if OverrideData is not NULL.
00336   @retval EFI_UNSUPPORTED          One or more options in the OptionList are in the
00337                                    unsupported list of structure EFI_MTFTP4_MODE_DATA.
00338   @retval EFI_NOT_STARTED          The EFI MTFTPv4 Protocol driver has not been started.
00339   @retval EFI_NO_MAPPING           When using a default address, configuration (DHCP, BOOTP,
00340                                    RARP, etc.) has not finished yet.
00341   @retval EFI_ACCESS_DENIED        The previous operation has not completed yet.
00342   @retval EFI_OUT_OF_RESOURCES     Required system resources could not be allocated.
00343   @retval EFI_TFTP_ERROR           An MTFTPv4 ERROR packet was received and is in the Packet.
00344   @retval EFI_NETWORK_UNREACHABLE  An ICMP network unreachable error packet was received and the Packet is set to NULL.
00345   @retval EFI_HOST_UNREACHABLE     An ICMP host unreachable error packet was received and the Packet is set to NULL.
00346   @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received and the Packet is set to NULL.
00347   @retval EFI_PORT_UNREACHABLE     An ICMP port unreachable error packet was received and the Packet is set to NULL.
00348   @retval EFI_ICMP_ERROR           Some other ICMP ERROR packet was received and is in the Buffer.
00349   @retval EFI_PROTOCOL_ERROR       An unexpected MTFTPv4 packet was received and is in the Packet.
00350   @retval EFI_TIMEOUT              No responses were received from the MTFTPv4 server.
00351   @retval EFI_DEVICE_ERROR         An unexpected network error or system error occurred.
00352   @retval EFI_NO_MEDIA             There was a media error.
00353 
00354 **/
00355 typedef
00356 EFI_STATUS
00357 (EFIAPI *EFI_MTFTP4_GET_INFO)(
00358   IN  EFI_MTFTP4_PROTOCOL      *This,
00359   IN  EFI_MTFTP4_OVERRIDE_DATA *OverrideData   OPTIONAL,
00360   IN  UINT8                    *Filename,
00361   IN  UINT8                    *ModeStr        OPTIONAL,
00362   IN  UINT8                    OptionCount,
00363   IN  EFI_MTFTP4_OPTION        *OptionList,
00364   OUT UINT32                   *PacketLength,
00365   OUT EFI_MTFTP4_PACKET        **Packet        OPTIONAL
00366   );
00367 
00368 /**
00369   Parses the options in an MTFTPv4 OACK packet.
00370 
00371   @param  This         The pointer to the EFI_MTFTP4_PROTOCOL instance.
00372   @param  PacketLen    Length of the OACK packet to be parsed.
00373   @param  Packet       The pointer to the OACK packet to be parsed.
00374   @param  OptionCount  The pointer to the number of options in following OptionList.
00375   @param  OptionList   The pointer to EFI_MTFTP4_OPTION storage. Call the EFI Boot
00376                        Service FreePool() to release the OptionList if the options
00377                        in this OptionList are not needed any more.
00378 
00379   @retval EFI_SUCCESS           The OACK packet was valid and the OptionCount and
00380                                 OptionList parameters have been updated.
00381   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
00382                                 - PacketLen is 0.
00383                                 - Packet is NULL or Packet is not a valid MTFTPv4 packet.
00384                                 - OptionCount is NULL.
00385   @retval EFI_NOT_FOUND         No options were found in the OACK packet.
00386   @retval EFI_OUT_OF_RESOURCES  Storage for the OptionList array cannot be allocated.
00387   @retval EFI_PROTOCOL_ERROR    One or more of the option fields is invalid.
00388 
00389 **/
00390 typedef
00391 EFI_STATUS
00392 (EFIAPI *EFI_MTFTP4_PARSE_OPTIONS)(
00393   IN  EFI_MTFTP4_PROTOCOL      *This,
00394   IN  UINT32                   PacketLen,
00395   IN  EFI_MTFTP4_PACKET        *Packet,
00396   OUT UINT32                   *OptionCount,
00397   OUT EFI_MTFTP4_OPTION        **OptionList OPTIONAL
00398   );
00399 
00400 
00401 /**
00402   Downloads a file from an MTFTPv4 server.
00403 
00404   @param  This  The pointer to the EFI_MTFTP4_PROTOCOL instance.
00405   @param  Token The pointer to the token structure to provide the parameters that are
00406                 used in this operation.
00407 
00408   @retval EFI_SUCCESS              The data file has been transferred successfully.
00409   @retval EFI_OUT_OF_RESOURCES     Required system resources could not be allocated.
00410   @retval EFI_BUFFER_TOO_SMALL     BufferSize is not zero but not large enough to hold the
00411                                    downloaded data in downloading process.
00412   @retval EFI_ABORTED              Current operation is aborted by user.
00413   @retval EFI_NETWORK_UNREACHABLE  An ICMP network unreachable error packet was received.
00414   @retval EFI_HOST_UNREACHABLE     An ICMP host unreachable error packet was received.
00415   @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received.
00416   @retval EFI_PORT_UNREACHABLE     An ICMP port unreachable error packet was received.
00417   @retval EFI_ICMP_ERROR           Some other  ICMP ERROR packet was received.
00418   @retval EFI_TIMEOUT              No responses were received from the MTFTPv4 server.
00419   @retval EFI_TFTP_ERROR           An MTFTPv4 ERROR packet was received.
00420   @retval EFI_DEVICE_ERROR         An unexpected network error or system error occurred.
00421   @retval EFI_NO_MEDIA             There was a media error.
00422 
00423 **/
00424 typedef
00425 EFI_STATUS
00426 (EFIAPI *EFI_MTFTP4_READ_FILE)(
00427   IN EFI_MTFTP4_PROTOCOL       *This,
00428   IN EFI_MTFTP4_TOKEN          *Token
00429   );
00430 
00431 
00432 
00433 /**
00434   Sends a file to an MTFTPv4 server.
00435 
00436   @param  This  The pointer to the EFI_MTFTP4_PROTOCOL instance.
00437   @param  Token The pointer to the token structure to provide the parameters that are
00438                 used in this operation.
00439 
00440   @retval EFI_SUCCESS           The upload session has started.
00441   @retval EFI_UNSUPPORTED       The operation is not supported by this implementation.
00442   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
00443   @retval EFI_UNSUPPORTED       One or more options in the Token.OptionList are in
00444                                 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
00445   @retval EFI_NOT_STARTED       The EFI MTFTPv4 Protocol driver has not been started.
00446   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
00447                                 RARP, etc.) is not finished yet.
00448   @retval EFI_ALREADY_STARTED   This Token is already being used in another MTFTPv4 session.
00449   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
00450   @retval EFI_ACCESS_DENIED     The previous operation has not completed yet.
00451   @retval EFI_DEVICE_ERROR      An unexpected network error or system error occurred.
00452 
00453 **/
00454 typedef
00455 EFI_STATUS
00456 (EFIAPI *EFI_MTFTP4_WRITE_FILE)(
00457   IN EFI_MTFTP4_PROTOCOL       *This,
00458   IN EFI_MTFTP4_TOKEN          *Token
00459   );
00460 
00461 
00462 /**
00463   Downloads a data file "directory" from an MTFTPv4 server. May be unsupported in some EFI
00464   implementations.
00465 
00466   @param  This  The pointer to the EFI_MTFTP4_PROTOCOL instance.
00467   @param  Token The pointer to the token structure to provide the parameters that are
00468                 used in this operation.
00469 
00470   @retval EFI_SUCCESS           The MTFTPv4 related file "directory" has been downloaded.
00471   @retval EFI_UNSUPPORTED       The operation is not supported by this implementation.
00472   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
00473   @retval EFI_UNSUPPORTED       One or more options in the Token.OptionList are in
00474                                 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
00475   @retval EFI_NOT_STARTED       The EFI MTFTPv4 Protocol driver has not been started.
00476   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
00477                                 RARP, etc.) is not finished yet.
00478   @retval EFI_ALREADY_STARTED   This Token is already being used in another MTFTPv4 session.
00479   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
00480   @retval EFI_ACCESS_DENIED     The previous operation has not completed yet.
00481   @retval EFI_DEVICE_ERROR      An unexpected network error or system error occurred.
00482 
00483 **/
00484 typedef
00485 EFI_STATUS
00486 (EFIAPI *EFI_MTFTP4_READ_DIRECTORY)(
00487   IN EFI_MTFTP4_PROTOCOL       *This,
00488   IN EFI_MTFTP4_TOKEN          *Token
00489   );
00490 
00491 /**
00492   Polls for incoming data packets and processes outgoing data packets.
00493 
00494   @param  This The pointer to the EFI_MTFTP4_PROTOCOL instance.
00495 
00496   @retval  EFI_SUCCESS           Incoming or outgoing data was processed.
00497   @retval  EFI_NOT_STARTED       This EFI MTFTPv4 Protocol instance has not been started.
00498   @retval  EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
00499                                  RARP, etc.) is not finished yet.
00500   @retval  EFI_INVALID_PARAMETER This is NULL.
00501   @retval  EFI_DEVICE_ERROR      An unexpected system or network error occurred.
00502   @retval  EFI_TIMEOUT           Data was dropped out of the transmit and/or receive queue.
00503                                  Consider increasing the polling rate.
00504 
00505 **/
00506 typedef
00507 EFI_STATUS
00508 (EFIAPI *EFI_MTFTP4_POLL)(
00509   IN EFI_MTFTP4_PROTOCOL       *This
00510   );
00511 
00512 ///
00513 /// The EFI_MTFTP4_PROTOCOL is designed to be used by UEFI drivers and applications
00514 /// to transmit and receive data files. The EFI MTFTPv4 Protocol driver uses
00515 /// the underlying EFI UDPv4 Protocol driver and EFI IPv4 Protocol driver.
00516 ///
00517 struct _EFI_MTFTP4_PROTOCOL {
00518   EFI_MTFTP4_GET_MODE_DATA     GetModeData;
00519   EFI_MTFTP4_CONFIGURE         Configure;
00520   EFI_MTFTP4_GET_INFO          GetInfo;
00521   EFI_MTFTP4_PARSE_OPTIONS     ParseOptions;
00522   EFI_MTFTP4_READ_FILE         ReadFile;
00523   EFI_MTFTP4_WRITE_FILE        WriteFile;
00524   EFI_MTFTP4_READ_DIRECTORY    ReadDirectory;
00525   EFI_MTFTP4_POLL              Poll;
00526 };
00527 
00528 struct _EFI_MTFTP4_TOKEN {
00529   ///
00530   /// The status that is returned to the caller at the end of the operation
00531   /// to indicate whether this operation completed successfully.
00532   ///
00533   EFI_STATUS                  Status;
00534   ///
00535   /// The event that will be signaled when the operation completes. If
00536   /// set to NULL, the corresponding function will wait until the read or
00537   /// write operation finishes. The type of Event must be
00538   /// EVT_NOTIFY_SIGNAL. The Task Priority Level (TPL) of
00539   /// Event must be lower than or equal to TPL_CALLBACK.
00540   ///
00541   EFI_EVENT                   Event;
00542   ///
00543   /// If not NULL, the data that will be used to override the existing configure data.
00544   ///
00545   EFI_MTFTP4_OVERRIDE_DATA    *OverrideData;
00546   ///
00547   /// The pointer to the null-terminated ASCII file name string.
00548   ///
00549   UINT8                       *Filename;
00550   ///
00551   /// The pointer to the null-terminated ASCII mode string. If NULL, "octet" is used.
00552   ///
00553   UINT8                       *ModeStr;
00554   ///
00555   /// Number of option/value string pairs.
00556   ///
00557   UINT32                      OptionCount;
00558   ///
00559   /// The pointer to an array of option/value string pairs. Ignored if OptionCount is zero.
00560   ///
00561   EFI_MTFTP4_OPTION           *OptionList;
00562   ///
00563   /// The size of the data buffer.
00564   ///
00565   UINT64                      BufferSize;
00566   ///
00567   /// The pointer to the data buffer. Data that is downloaded from the
00568   /// MTFTPv4 server is stored here. Data that is uploaded to the
00569   /// MTFTPv4 server is read from here. Ignored if BufferSize is zero.
00570   ///
00571   VOID                        *Buffer;
00572   ///
00573   /// The pointer to the context that will be used by CheckPacket,
00574   /// TimeoutCallback and PacketNeeded.
00575   ///
00576   VOID                        *Context;
00577   ///
00578   /// The pointer to the callback function to check the contents of the received packet.
00579   ///
00580   EFI_MTFTP4_CHECK_PACKET     CheckPacket;
00581   ///
00582   /// The pointer to the function to be called when a timeout occurs.
00583   ///
00584   EFI_MTFTP4_TIMEOUT_CALLBACK TimeoutCallback;
00585   ///
00586   /// The pointer to the function to provide the needed packet contents.
00587   ///
00588   EFI_MTFTP4_PACKET_NEEDED    PacketNeeded;
00589 };
00590 
00591 extern EFI_GUID gEfiMtftp4ServiceBindingProtocolGuid;
00592 extern EFI_GUID gEfiMtftp4ProtocolGuid;
00593 
00594 #endif
00595