qemu/roms/ipxe/src/include/ipxe/efi/Protocol/Mtftp4.h

   1 /** @file
   2   EFI Multicast Trivial File Tranfer Protocol Definition
   3
   4 Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials are licensed and made available under
   6 the terms and conditions of the BSD License that accompanies this distribution.
   7 The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php.
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13   @par Revision Reference:
  14   This Protocol is introduced in UEFI Specification 2.0
  15
  16 **/
  17
  18 #ifndef __EFI_MTFTP4_PROTOCOL_H__
  19 #define __EFI_MTFTP4_PROTOCOL_H__
  20
  21 FILE_LICENCE ( BSD3 );
  22
  23 #define EFI_MTFTP4_SERVICE_BINDING_PROTOCOL_GUID \
  24   { \
  25     0x2FE800BE, 0x8F01, 0x4aa6, {0x94, 0x6B, 0xD7, 0x13, 0x88, 0xE1, 0x83, 0x3F } \
  26   }
  27
  28 #define EFI_MTFTP4_PROTOCOL_GUID \
  29   { \
  30     0x78247c57, 0x63db, 0x4708, {0x99, 0xc2, 0xa8, 0xb4, 0xa9, 0xa6, 0x1f, 0x6b } \
  31   }
  32
  33 typedef struct _EFI_MTFTP4_PROTOCOL EFI_MTFTP4_PROTOCOL;
  34 typedef struct _EFI_MTFTP4_TOKEN EFI_MTFTP4_TOKEN;
  35
  36 //
  37 //MTFTP4 packet opcode definition
  38 //
  39 #define EFI_MTFTP4_OPCODE_RRQ                     1
  40 #define EFI_MTFTP4_OPCODE_WRQ                     2
  41 #define EFI_MTFTP4_OPCODE_DATA                    3
  42 #define EFI_MTFTP4_OPCODE_ACK                     4
  43 #define EFI_MTFTP4_OPCODE_ERROR                   5
  44 #define EFI_MTFTP4_OPCODE_OACK                    6
  45 #define EFI_MTFTP4_OPCODE_DIR                     7
  46 #define EFI_MTFTP4_OPCODE_DATA8                   8
  47 #define EFI_MTFTP4_OPCODE_ACK8                    9
  48
  49 //
  50 // MTFTP4 error code definition
  51 //
  52 #define EFI_MTFTP4_ERRORCODE_NOT_DEFINED          0
  53 #define EFI_MTFTP4_ERRORCODE_FILE_NOT_FOUND       1
  54 #define EFI_MTFTP4_ERRORCODE_ACCESS_VIOLATION     2
  55 #define EFI_MTFTP4_ERRORCODE_DISK_FULL            3
  56 #define EFI_MTFTP4_ERRORCODE_ILLEGAL_OPERATION    4
  57 #define EFI_MTFTP4_ERRORCODE_UNKNOWN_TRANSFER_ID  5
  58 #define EFI_MTFTP4_ERRORCODE_FILE_ALREADY_EXISTS  6
  59 #define EFI_MTFTP4_ERRORCODE_NO_SUCH_USER         7
  60 #define EFI_MTFTP4_ERRORCODE_REQUEST_DENIED       8
  61
  62 //
  63 // MTFTP4 pacekt definitions
  64 //
  65 #pragma pack(1)
  66
  67 typedef struct {
  68   UINT16                  OpCode;
  69   UINT8                   Filename[1];
  70 } EFI_MTFTP4_REQ_HEADER;
  71
  72 typedef struct {
  73   UINT16                  OpCode;
  74   UINT8                   Data[1];
  75 } EFI_MTFTP4_OACK_HEADER;
  76
  77 typedef struct {
  78   UINT16                  OpCode;
  79   UINT16                  Block;
  80   UINT8                   Data[1];
  81 } EFI_MTFTP4_DATA_HEADER;
  82
  83 typedef struct {
  84   UINT16                  OpCode;
  85   UINT16                  Block[1];
  86 } EFI_MTFTP4_ACK_HEADER;
  87
  88 typedef struct {
  89   UINT16                  OpCode;
  90   UINT64                  Block;
  91   UINT8                   Data[1];
  92 } EFI_MTFTP4_DATA8_HEADER;
  93
  94 typedef struct {
  95   UINT16                  OpCode;
  96   UINT64                  Block[1];
  97 } EFI_MTFTP4_ACK8_HEADER;
  98
  99 typedef struct {
 100   UINT16                  OpCode;
 101   UINT16                  ErrorCode;
 102   UINT8                   ErrorMessage[1];
 103 } EFI_MTFTP4_ERROR_HEADER;
 104
 105 typedef union {
 106   ///
 107   /// Type of packets as defined by the MTFTPv4 packet opcodes.
 108   ///
 109   UINT16                  OpCode;
 110   ///
 111   /// Read request packet header.
 112   ///
 113   EFI_MTFTP4_REQ_HEADER   Rrq;
 114   ///
 115   /// Write request packet header.
 116   ///
 117   EFI_MTFTP4_REQ_HEADER   Wrq;
 118   ///
 119   /// Option acknowledge packet header.
 120   ///
 121   EFI_MTFTP4_OACK_HEADER  Oack;
 122   ///
 123   /// Data packet header.
 124   ///
 125   EFI_MTFTP4_DATA_HEADER  Data;
 126   ///
 127   /// Acknowledgement packet header.
 128   ///
 129   EFI_MTFTP4_ACK_HEADER   Ack;
 130   ///
 131   /// Data packet header with big block number.
 132   ///
 133   EFI_MTFTP4_DATA8_HEADER Data8;
 134   ///
 135   /// Acknowledgement header with big block num.
 136   ///
 137   EFI_MTFTP4_ACK8_HEADER  Ack8;
 138   ///
 139   /// Error packet header.
 140   ///
 141   EFI_MTFTP4_ERROR_HEADER Error;
 142 } EFI_MTFTP4_PACKET;
 143
 144 #pragma pack()
 145
 146 ///
 147 /// MTFTP4 option definition.
 148 ///
 149 typedef struct {
 150   UINT8                   *OptionStr;
 151   UINT8                   *ValueStr;
 152 } EFI_MTFTP4_OPTION;
 153
 154
 155 typedef struct {
 156   BOOLEAN                 UseDefaultSetting;
 157   EFI_IPv4_ADDRESS        StationIp;
 158   EFI_IPv4_ADDRESS        SubnetMask;
 159   UINT16                  LocalPort;
 160   EFI_IPv4_ADDRESS        GatewayIp;
 161   EFI_IPv4_ADDRESS        ServerIp;
 162   UINT16                  InitialServerPort;
 163   UINT16                  TryCount;
 164   UINT16                  TimeoutValue;
 165 } EFI_MTFTP4_CONFIG_DATA;
 166
 167
 168 typedef struct {
 169   EFI_MTFTP4_CONFIG_DATA  ConfigData;
 170   UINT8                   SupportedOptionCount;
 171   UINT8                   **SupportedOptoins;
 172   UINT8                   UnsupportedOptionCount;
 173   UINT8                   **UnsupportedOptoins;
 174 } EFI_MTFTP4_MODE_DATA;
 175
 176
 177 typedef struct {
 178   EFI_IPv4_ADDRESS        GatewayIp;
 179   EFI_IPv4_ADDRESS        ServerIp;
 180   UINT16                  ServerPort;
 181   UINT16                  TryCount;
 182   UINT16                  TimeoutValue;
 183 } EFI_MTFTP4_OVERRIDE_DATA;
 184
 185 //
 186 // Protocol interfaces definition
 187 //
 188
 189 /**
 190   A callback function that is provided by the caller to intercept
 191   the EFI_MTFTP4_OPCODE_DATA or EFI_MTFTP4_OPCODE_DATA8 packets processed in the
 192   EFI_MTFTP4_PROTOCOL.ReadFile() function, and alternatively to intercept
 193   EFI_MTFTP4_OPCODE_OACK or EFI_MTFTP4_OPCODE_ERROR packets during a call to
 194   EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory().
 195
 196   @param  This        The pointer to the EFI_MTFTP4_PROTOCOL instance.
 197   @param  Token       The token that the caller provided in the
 198                       EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile()
 199                       or ReadDirectory() function.
 200   @param  PacketLen   Indicates the length of the packet.
 201   @param  Packet      The pointer to an MTFTPv4 packet.
 202
 203   @retval EFI_SUCCESS The operation was successful.
 204   @retval Others      Aborts the transfer process.
 205
 206 **/
 207 typedef
 208 EFI_STATUS
 209 (EFIAPI *EFI_MTFTP4_CHECK_PACKET)(
 210   IN EFI_MTFTP4_PROTOCOL  *This,
 211   IN EFI_MTFTP4_TOKEN     *Token,
 212   IN UINT16               PacketLen,
 213   IN EFI_MTFTP4_PACKET    *Paket
 214   );
 215
 216 /**
 217   Timeout callback funtion.
 218
 219   @param  This           The pointer to the EFI_MTFTP4_PROTOCOL instance.
 220   @param  Token          The token that is provided in the
 221                          EFI_MTFTP4_PROTOCOL.ReadFile() or
 222                          EFI_MTFTP4_PROTOCOL.WriteFile() or
 223                          EFI_MTFTP4_PROTOCOL.ReadDirectory() functions
 224                          by the caller.
 225
 226   @retval EFI_SUCCESS   The operation was successful.
 227   @retval Others        Aborts download process.
 228
 229 **/
 230 typedef
 231 EFI_STATUS
 232 (EFIAPI *EFI_MTFTP4_TIMEOUT_CALLBACK)(
 233   IN EFI_MTFTP4_PROTOCOL  *This,
 234   IN EFI_MTFTP4_TOKEN     *Token
 235   );
 236
 237 /**
 238   A callback function that the caller provides to feed data to the
 239   EFI_MTFTP4_PROTOCOL.WriteFile() function.
 240
 241   @param  This   The pointer to the EFI_MTFTP4_PROTOCOL instance.
 242   @param  Token  The token provided in the
 243                  EFI_MTFTP4_PROTOCOL.WriteFile() by the caller.
 244   @param  Length Indicates the length of the raw data wanted on input, and the
 245                  length the data available on output.
 246   @param  Buffer The pointer to the buffer where the data is stored.
 247
 248   @retval EFI_SUCCESS The operation was successful.
 249   @retval Others      Aborts session.
 250
 251 **/
 252 typedef
 253 EFI_STATUS
 254 (EFIAPI *EFI_MTFTP4_PACKET_NEEDED)(
 255   IN  EFI_MTFTP4_PROTOCOL *This,
 256   IN  EFI_MTFTP4_TOKEN    *Token,
 257   IN  OUT UINT16          *Length,
 258   OUT VOID                **Buffer
 259   );
 260
 261
 262 /**
 263   Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
 264
 265   @param  This     The pointer to the EFI_MTFTP4_PROTOCOL instance.
 266   @param  ModeData The pointer to storage for the EFI MTFTPv4 Protocol driver mode data.
 267
 268   @retval EFI_SUCCESS           The configuration data was successfully returned.
 269   @retval EFI_OUT_OF_RESOURCES  The required mode data could not be allocated.
 270   @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
 271
 272 **/
 273 typedef
 274 EFI_STATUS
 275 (EFIAPI *EFI_MTFTP4_GET_MODE_DATA)(
 276   IN  EFI_MTFTP4_PROTOCOL     *This,
 277   OUT EFI_MTFTP4_MODE_DATA    *ModeData
 278   );
 279
 280
 281 /**
 282   Initializes, changes, or resets the default operational setting for this
 283   EFI MTFTPv4 Protocol driver instance.
 284
 285   @param  This            The pointer to the EFI_MTFTP4_PROTOCOL instance.
 286   @param  MtftpConfigData The pointer to the configuration data structure.
 287
 288   @retval EFI_SUCCESS           The EFI MTFTPv4 Protocol driver was configured successfully.
 289   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 290   @retval EFI_ACCESS_DENIED     The EFI configuration could not be changed at this time because
 291                                 there is one MTFTP background operation in progress.
 292   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
 293                                 RARP, etc.) has not finished yet.
 294   @retval EFI_UNSUPPORTED       A configuration protocol (DHCP, BOOTP, RARP, etc.) could not
 295                                 be located when clients choose to use the default address
 296                                 settings.
 297   @retval EFI_OUT_OF_RESOURCES  The EFI MTFTPv4 Protocol driver instance data could not be
 298                                 allocated.
 299   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred. The EFI
 300                                  MTFTPv4 Protocol driver instance is not configured.
 301
 302 **/
 303 typedef
 304 EFI_STATUS
 305 (EFIAPI *EFI_MTFTP4_CONFIGURE)(
 306   IN EFI_MTFTP4_PROTOCOL       *This,
 307   IN EFI_MTFTP4_CONFIG_DATA    *MtftpConfigData OPTIONAL
 308   );
 309
 310
 311 /**
 312   Gets information about a file from an MTFTPv4 server.
 313
 314   @param  This         The pointer to the EFI_MTFTP4_PROTOCOL instance.
 315   @param  OverrideData Data that is used to override the existing parameters. If NULL,
 316                        the default parameters that were set in the
 317                        EFI_MTFTP4_PROTOCOL.Configure() function are used.
 318   @param  Filename     The pointer to null-terminated ASCII file name string.
 319   @param  ModeStr      The pointer to null-terminated ASCII mode string. If NULL, "octet" will be used.
 320   @param  OptionCount  Number of option/value string pairs in OptionList.
 321   @param  OptionList   The pointer to array of option/value string pairs. Ignored if
 322                        OptionCount is zero.
 323   @param  PacketLength The number of bytes in the returned packet.
 324   @param  Packet       The pointer to the received packet. This buffer must be freed by
 325                        the caller.
 326
 327   @retval EFI_SUCCESS              An MTFTPv4 OACK packet was received and is in the Packet.
 328   @retval EFI_INVALID_PARAMETER    One or more of the following conditions is TRUE:
 329                                    - This is NULL.
 330                                    - Filename is NULL.
 331                                    - OptionCount is not zero and OptionList is NULL.
 332                                    - One or more options in OptionList have wrong format.
 333                                    - PacketLength is NULL.
 334                                    - One or more IPv4 addresses in OverrideData are not valid
 335                                      unicast IPv4 addresses if OverrideData is not NULL.
 336   @retval EFI_UNSUPPORTED          One or more options in the OptionList are in the
 337                                    unsupported list of structure EFI_MTFTP4_MODE_DATA.
 338   @retval EFI_NOT_STARTED          The EFI MTFTPv4 Protocol driver has not been started.
 339   @retval EFI_NO_MAPPING           When using a default address, configuration (DHCP, BOOTP,
 340                                    RARP, etc.) has not finished yet.
 341   @retval EFI_ACCESS_DENIED        The previous operation has not completed yet.
 342   @retval EFI_OUT_OF_RESOURCES     Required system resources could not be allocated.
 343   @retval EFI_TFTP_ERROR           An MTFTPv4 ERROR packet was received and is in the Packet.
 344   @retval EFI_NETWORK_UNREACHABLE  An ICMP network unreachable error packet was received and the Packet is set to NULL.
 345   @retval EFI_HOST_UNREACHABLE     An ICMP host unreachable error packet was received and the Packet is set to NULL.
 346   @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received and the Packet is set to NULL.
 347   @retval EFI_PORT_UNREACHABLE     An ICMP port unreachable error packet was received and the Packet is set to NULL.
 348   @retval EFI_ICMP_ERROR           Some other ICMP ERROR packet was received and is in the Buffer.
 349   @retval EFI_PROTOCOL_ERROR       An unexpected MTFTPv4 packet was received and is in the Packet.
 350   @retval EFI_TIMEOUT              No responses were received from the MTFTPv4 server.
 351   @retval EFI_DEVICE_ERROR         An unexpected network error or system error occurred.
 352   @retval EFI_NO_MEDIA             There was a media error.
 353
 354 **/
 355 typedef
 356 EFI_STATUS
 357 (EFIAPI *EFI_MTFTP4_GET_INFO)(
 358   IN  EFI_MTFTP4_PROTOCOL      *This,
 359   IN  EFI_MTFTP4_OVERRIDE_DATA *OverrideData   OPTIONAL,
 360   IN  UINT8                    *Filename,
 361   IN  UINT8                    *ModeStr        OPTIONAL,
 362   IN  UINT8                    OptionCount,
 363   IN  EFI_MTFTP4_OPTION        *OptionList,
 364   OUT UINT32                   *PacketLength,
 365   OUT EFI_MTFTP4_PACKET        **Packet        OPTIONAL
 366   );
 367
 368 /**
 369   Parses the options in an MTFTPv4 OACK packet.
 370
 371   @param  This         The pointer to the EFI_MTFTP4_PROTOCOL instance.
 372   @param  PacketLen    Length of the OACK packet to be parsed.
 373   @param  Packet       The pointer to the OACK packet to be parsed.
 374   @param  OptionCount  The pointer to the number of options in following OptionList.
 375   @param  OptionList   The pointer to EFI_MTFTP4_OPTION storage. Call the EFI Boot
 376                        Service FreePool() to release the OptionList if the options
 377                        in this OptionList are not needed any more.
 378
 379   @retval EFI_SUCCESS           The OACK packet was valid and the OptionCount and
 380                                 OptionList parameters have been updated.
 381   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 382                                 - PacketLen is 0.
 383                                 - Packet is NULL or Packet is not a valid MTFTPv4 packet.
 384                                 - OptionCount is NULL.
 385   @retval EFI_NOT_FOUND         No options were found in the OACK packet.
 386   @retval EFI_OUT_OF_RESOURCES  Storage for the OptionList array cannot be allocated.
 387   @retval EFI_PROTOCOL_ERROR    One or more of the option fields is invalid.
 388
 389 **/
 390 typedef
 391 EFI_STATUS
 392 (EFIAPI *EFI_MTFTP4_PARSE_OPTIONS)(
 393   IN  EFI_MTFTP4_PROTOCOL      *This,
 394   IN  UINT32                   PacketLen,
 395   IN  EFI_MTFTP4_PACKET        *Packet,
 396   OUT UINT32                   *OptionCount,
 397   OUT EFI_MTFTP4_OPTION        **OptionList OPTIONAL
 398   );
 399
 400
 401 /**
 402   Downloads a file from an MTFTPv4 server.
 403
 404   @param  This  The pointer to the EFI_MTFTP4_PROTOCOL instance.
 405   @param  Token The pointer to the token structure to provide the parameters that are
 406                 used in this operation.
 407
 408   @retval EFI_SUCCESS              The data file has been transferred successfully.
 409   @retval EFI_OUT_OF_RESOURCES     Required system resources could not be allocated.
 410   @retval EFI_BUFFER_TOO_SMALL     BufferSize is not zero but not large enough to hold the
 411                                    downloaded data in downloading process.
 412   @retval EFI_ABORTED              Current operation is aborted by user.
 413   @retval EFI_NETWORK_UNREACHABLE  An ICMP network unreachable error packet was received.
 414   @retval EFI_HOST_UNREACHABLE     An ICMP host unreachable error packet was received.
 415   @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received.
 416   @retval EFI_PORT_UNREACHABLE     An ICMP port unreachable error packet was received.
 417   @retval EFI_ICMP_ERROR           Some other  ICMP ERROR packet was received.
 418   @retval EFI_TIMEOUT              No responses were received from the MTFTPv4 server.
 419   @retval EFI_TFTP_ERROR           An MTFTPv4 ERROR packet was received.
 420   @retval EFI_DEVICE_ERROR         An unexpected network error or system error occurred.
 421   @retval EFI_NO_MEDIA             There was a media error.
 422
 423 **/
 424 typedef
 425 EFI_STATUS
 426 (EFIAPI *EFI_MTFTP4_READ_FILE)(
 427   IN EFI_MTFTP4_PROTOCOL       *This,
 428   IN EFI_MTFTP4_TOKEN          *Token
 429   );
 430
 431
 432
 433 /**
 434   Sends a file to an MTFTPv4 server.
 435
 436   @param  This  The pointer to the EFI_MTFTP4_PROTOCOL instance.
 437   @param  Token The pointer to the token structure to provide the parameters that are
 438                 used in this operation.
 439
 440   @retval EFI_SUCCESS           The upload session has started.
 441   @retval EFI_UNSUPPORTED       The operation is not supported by this implementation.
 442   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 443   @retval EFI_UNSUPPORTED       One or more options in the Token.OptionList are in
 444                                 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
 445   @retval EFI_NOT_STARTED       The EFI MTFTPv4 Protocol driver has not been started.
 446   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
 447                                 RARP, etc.) is not finished yet.
 448   @retval EFI_ALREADY_STARTED   This Token is already being used in another MTFTPv4 session.
 449   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 450   @retval EFI_ACCESS_DENIED     The previous operation has not completed yet.
 451   @retval EFI_DEVICE_ERROR      An unexpected network error or system error occurred.
 452
 453 **/
 454 typedef
 455 EFI_STATUS
 456 (EFIAPI *EFI_MTFTP4_WRITE_FILE)(
 457   IN EFI_MTFTP4_PROTOCOL       *This,
 458   IN EFI_MTFTP4_TOKEN          *Token
 459   );
 460
 461
 462 /**
 463   Downloads a data file "directory" from an MTFTPv4 server. May be unsupported in some EFI
 464   implementations.
 465
 466   @param  This  The pointer to the EFI_MTFTP4_PROTOCOL instance.
 467   @param  Token The pointer to the token structure to provide the parameters that are
 468                 used in this operation.
 469
 470   @retval EFI_SUCCESS           The MTFTPv4 related file "directory" has been downloaded.
 471   @retval EFI_UNSUPPORTED       The operation is not supported by this implementation.
 472   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 473   @retval EFI_UNSUPPORTED       One or more options in the Token.OptionList are in
 474                                 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
 475   @retval EFI_NOT_STARTED       The EFI MTFTPv4 Protocol driver has not been started.
 476   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
 477                                 RARP, etc.) is not finished yet.
 478   @retval EFI_ALREADY_STARTED   This Token is already being used in another MTFTPv4 session.
 479   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 480   @retval EFI_ACCESS_DENIED     The previous operation has not completed yet.
 481   @retval EFI_DEVICE_ERROR      An unexpected network error or system error occurred.
 482
 483 **/
 484 typedef
 485 EFI_STATUS
 486 (EFIAPI *EFI_MTFTP4_READ_DIRECTORY)(
 487   IN EFI_MTFTP4_PROTOCOL       *This,
 488   IN EFI_MTFTP4_TOKEN          *Token
 489   );
 490
 491 /**
 492   Polls for incoming data packets and processes outgoing data packets.
 493
 494   @param  This The pointer to the EFI_MTFTP4_PROTOCOL instance.
 495
 496   @retval  EFI_SUCCESS           Incoming or outgoing data was processed.
 497   @retval  EFI_NOT_STARTED       This EFI MTFTPv4 Protocol instance has not been started.
 498   @retval  EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
 499                                  RARP, etc.) is not finished yet.
 500   @retval  EFI_INVALID_PARAMETER This is NULL.
 501   @retval  EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 502   @retval  EFI_TIMEOUT           Data was dropped out of the transmit and/or receive queue.
 503                                  Consider increasing the polling rate.
 504
 505 **/
 506 typedef
 507 EFI_STATUS
 508 (EFIAPI *EFI_MTFTP4_POLL)(
 509   IN EFI_MTFTP4_PROTOCOL       *This
 510   );
 511
 512 ///
 513 /// The EFI_MTFTP4_PROTOCOL is designed to be used by UEFI drivers and applications
 514 /// to transmit and receive data files. The EFI MTFTPv4 Protocol driver uses
 515 /// the underlying EFI UDPv4 Protocol driver and EFI IPv4 Protocol driver.
 516 ///
 517 struct _EFI_MTFTP4_PROTOCOL {
 518   EFI_MTFTP4_GET_MODE_DATA     GetModeData;
 519   EFI_MTFTP4_CONFIGURE         Configure;
 520   EFI_MTFTP4_GET_INFO          GetInfo;
 521   EFI_MTFTP4_PARSE_OPTIONS     ParseOptions;
 522   EFI_MTFTP4_READ_FILE         ReadFile;
 523   EFI_MTFTP4_WRITE_FILE        WriteFile;
 524   EFI_MTFTP4_READ_DIRECTORY    ReadDirectory;
 525   EFI_MTFTP4_POLL              Poll;
 526 };
 527
 528 struct _EFI_MTFTP4_TOKEN {
 529   ///
 530   /// The status that is returned to the caller at the end of the operation
 531   /// to indicate whether this operation completed successfully.
 532   ///
 533   EFI_STATUS                  Status;
 534   ///
 535   /// The event that will be signaled when the operation completes. If
 536   /// set to NULL, the corresponding function will wait until the read or
 537   /// write operation finishes. The type of Event must be
 538   /// EVT_NOTIFY_SIGNAL. The Task Priority Level (TPL) of
 539   /// Event must be lower than or equal to TPL_CALLBACK.
 540   ///
 541   EFI_EVENT                   Event;
 542   ///
 543   /// If not NULL, the data that will be used to override the existing configure data.
 544   ///
 545   EFI_MTFTP4_OVERRIDE_DATA    *OverrideData;
 546   ///
 547   /// The pointer to the null-terminated ASCII file name string.
 548   ///
 549   UINT8                       *Filename;
 550   ///
 551   /// The pointer to the null-terminated ASCII mode string. If NULL, "octet" is used.
 552   ///
 553   UINT8                       *ModeStr;
 554   ///
 555   /// Number of option/value string pairs.
 556   ///
 557   UINT32                      OptionCount;
 558   ///
 559   /// The pointer to an array of option/value string pairs. Ignored if OptionCount is zero.
 560   ///
 561   EFI_MTFTP4_OPTION           *OptionList;
 562   ///
 563   /// The size of the data buffer.
 564   ///
 565   UINT64                      BufferSize;
 566   ///
 567   /// The pointer to the data buffer. Data that is downloaded from the
 568   /// MTFTPv4 server is stored here. Data that is uploaded to the
 569   /// MTFTPv4 server is read from here. Ignored if BufferSize is zero.
 570   ///
 571   VOID                        *Buffer;
 572   ///
 573   /// The pointer to the context that will be used by CheckPacket,
 574   /// TimeoutCallback and PacketNeeded.
 575   ///
 576   VOID                        *Context;
 577   ///
 578   /// The pointer to the callback function to check the contents of the received packet.
 579   ///
 580   EFI_MTFTP4_CHECK_PACKET     CheckPacket;
 581   ///
 582   /// The pointer to the function to be called when a timeout occurs.
 583   ///
 584   EFI_MTFTP4_TIMEOUT_CALLBACK TimeoutCallback;
 585   ///
 586   /// The pointer to the function to provide the needed packet contents.
 587   ///
 588   EFI_MTFTP4_PACKET_NEEDED    PacketNeeded;
 589 };
 590
 591 extern EFI_GUID gEfiMtftp4ServiceBindingProtocolGuid;
 592 extern EFI_GUID gEfiMtftp4ProtocolGuid;
 593
 594 #endif
 595