MdePkg/Include/Protocol/Mtftp4.h

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