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
 147 typedef struct {
 148   BOOLEAN                 UseDefaultSetting;
 149   EFI_IPv4_ADDRESS        StationIp;
 150   EFI_IPv4_ADDRESS        SubnetMask;
 151   UINT16                  LocalPort;
 152   EFI_IPv4_ADDRESS        GatewayIp;
 153   EFI_IPv4_ADDRESS        ServerIp;
 154   UINT16                  InitialServerPort;
 155   UINT16                  TryCount;
 156   UINT16                  TimeoutValue;
 157 } EFI_MTFTP4_CONFIG_DATA;
 158
 159
 160 typedef struct {
 161   EFI_MTFTP4_CONFIG_DATA  ConfigData;
 162   UINT8                   SupportedOptionCount;
 163   UINT8                   **SupportedOptoins;
 164   UINT8                   UnsupportedOptionCount;
 165   UINT8                   **UnsupportedOptoins;
 166 } EFI_MTFTP4_MODE_DATA;
 167
 168
 169 typedef struct {
 170   EFI_IPv4_ADDRESS        GatewayIp;
 171   EFI_IPv4_ADDRESS        ServerIp;
 172   UINT16                  ServerPort;
 173   UINT16                  TryCount;
 174   UINT16                  TimeoutValue;
 175 } EFI_MTFTP4_OVERRIDE_DATA;
 176
 177 //
 178 // Protocol interfaces definition
 179 //
 180
 181 /**
 182   A callback function that is provided by the caller to intercept
 183   the EFI_MTFTP4_OPCODE_DATA or EFI_MTFTP4_OPCODE_DATA8 packets processed in the
 184   EFI_MTFTP4_PROTOCOL.ReadFile() function, and alternatively to intercept
 185   EFI_MTFTP4_OPCODE_OACK or EFI_MTFTP4_OPCODE_ERROR packets during a call to
 186   EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory().
 187
 188   @param  This        The pointer to the EFI_MTFTP4_PROTOCOL instance.
 189   @param  Token       The token that the caller provided in the
 190                       EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile()
 191                       or ReadDirectory() function.
 192   @param  PacketLen   Indicates the length of the packet.
 193   @param  Packet      The pointer to an MTFTPv4 packet.
 194
 195   @retval EFI_SUCCESS The operation was successful.
 196   @retval Others      Aborts the transfer process.
 197
 198 **/
 199 typedef
 200 EFI_STATUS
 201 (EFIAPI *EFI_MTFTP4_CHECK_PACKET)(
 202   IN EFI_MTFTP4_PROTOCOL  *This,
 203   IN EFI_MTFTP4_TOKEN     *Token,
 204   IN UINT16               PacketLen,
 205   IN EFI_MTFTP4_PACKET    *Paket
 206   );
 207
 208 /**
 209   Timeout callback function.
 210
 211   @param  This           The pointer to the EFI_MTFTP4_PROTOCOL instance.
 212   @param  Token          The token that is provided in the
 213                          EFI_MTFTP4_PROTOCOL.ReadFile() or
 214                          EFI_MTFTP4_PROTOCOL.WriteFile() or
 215                          EFI_MTFTP4_PROTOCOL.ReadDirectory() functions
 216                          by the caller.
 217
 218   @retval EFI_SUCCESS   The operation was successful.
 219   @retval Others        Aborts download process.
 220
 221 **/
 222 typedef
 223 EFI_STATUS
 224 (EFIAPI *EFI_MTFTP4_TIMEOUT_CALLBACK)(
 225   IN EFI_MTFTP4_PROTOCOL  *This,
 226   IN EFI_MTFTP4_TOKEN     *Token
 227   );
 228
 229 /**
 230   A callback function that the caller provides to feed data to the
 231   EFI_MTFTP4_PROTOCOL.WriteFile() function.
 232
 233   @param  This   The pointer to the EFI_MTFTP4_PROTOCOL instance.
 234   @param  Token  The token provided in the
 235                  EFI_MTFTP4_PROTOCOL.WriteFile() by the caller.
 236   @param  Length Indicates the length of the raw data wanted on input, and the
 237                  length the data available on output.
 238   @param  Buffer The pointer to the buffer where the data is stored.
 239
 240   @retval EFI_SUCCESS The operation was successful.
 241   @retval Others      Aborts session.
 242
 243 **/
 244 typedef
 245 EFI_STATUS
 246 (EFIAPI *EFI_MTFTP4_PACKET_NEEDED)(
 247   IN  EFI_MTFTP4_PROTOCOL *This,
 248   IN  EFI_MTFTP4_TOKEN    *Token,
 249   IN  OUT UINT16          *Length,
 250   OUT VOID                **Buffer
 251   );
 252
 253
 254 /**
 255   Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
 256
 257   @param  This     The pointer to the EFI_MTFTP4_PROTOCOL instance.
 258   @param  ModeData The pointer to storage for the EFI MTFTPv4 Protocol driver mode data.
 259
 260   @retval EFI_SUCCESS           The configuration data was successfully returned.
 261   @retval EFI_OUT_OF_RESOURCES  The required mode data could not be allocated.
 262   @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
 263
 264 **/
 265 typedef
 266 EFI_STATUS
 267 (EFIAPI *EFI_MTFTP4_GET_MODE_DATA)(
 268   IN  EFI_MTFTP4_PROTOCOL     *This,
 269   OUT EFI_MTFTP4_MODE_DATA    *ModeData
 270   );
 271
 272
 273 /**
 274   Initializes, changes, or resets the default operational setting for this
 275   EFI MTFTPv4 Protocol driver instance.
 276
 277   @param  This            The pointer to the EFI_MTFTP4_PROTOCOL instance.
 278   @param  MtftpConfigData The pointer to the configuration data structure.
 279
 280   @retval EFI_SUCCESS           The EFI MTFTPv4 Protocol driver was configured successfully.
 281   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 282   @retval EFI_ACCESS_DENIED     The EFI configuration could not be changed at this time because
 283                                 there is one MTFTP background operation in progress.
 284   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
 285                                 RARP, etc.) has not finished yet.
 286   @retval EFI_UNSUPPORTED       A configuration protocol (DHCP, BOOTP, RARP, etc.) could not
 287                                 be located when clients choose to use the default address
 288                                 settings.
 289   @retval EFI_OUT_OF_RESOURCES  The EFI MTFTPv4 Protocol driver instance data could not be
 290                                 allocated.
 291   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred. The EFI
 292                                  MTFTPv4 Protocol driver instance is not configured.
 293
 294 **/
 295 typedef
 296 EFI_STATUS
 297 (EFIAPI *EFI_MTFTP4_CONFIGURE)(
 298   IN EFI_MTFTP4_PROTOCOL       *This,
 299   IN EFI_MTFTP4_CONFIG_DATA    *MtftpConfigData OPTIONAL
 300   );
 301
 302
 303 /**
 304   Gets information about a file from an MTFTPv4 server.
 305
 306   @param  This         The pointer to the EFI_MTFTP4_PROTOCOL instance.
 307   @param  OverrideData Data that is used to override the existing parameters. If NULL,
 308                        the default parameters that were set in the
 309                        EFI_MTFTP4_PROTOCOL.Configure() function are used.
 310   @param  Filename     The pointer to null-terminated ASCII file name string.
 311   @param  ModeStr      The pointer to null-terminated ASCII mode string. If NULL, "octet" will be used.
 312   @param  OptionCount  Number of option/value string pairs in OptionList.
 313   @param  OptionList   The pointer to array of option/value string pairs. Ignored if
 314                        OptionCount is zero.
 315   @param  PacketLength The number of bytes in the returned packet.
 316   @param  Packet       The pointer to the received packet. This buffer must be freed by
 317                        the caller.
 318
 319   @retval EFI_SUCCESS              An MTFTPv4 OACK packet was received and is in the Packet.
 320   @retval EFI_INVALID_PARAMETER    One or more of the following conditions is TRUE:
 321                                    - This is NULL.
 322                                    - Filename is NULL.
 323                                    - OptionCount is not zero and OptionList is NULL.
 324                                    - One or more options in OptionList have wrong format.
 325                                    - PacketLength is NULL.
 326                                    - One or more IPv4 addresses in OverrideData are not valid
 327                                      unicast IPv4 addresses if OverrideData is not NULL.
 328   @retval EFI_UNSUPPORTED          One or more options in the OptionList are in the
 329                                    unsupported list of structure EFI_MTFTP4_MODE_DATA.
 330   @retval EFI_NOT_STARTED          The EFI MTFTPv4 Protocol driver has not been started.
 331   @retval EFI_NO_MAPPING           When using a default address, configuration (DHCP, BOOTP,
 332                                    RARP, etc.) has not finished yet.
 333   @retval EFI_ACCESS_DENIED        The previous operation has not completed yet.
 334   @retval EFI_OUT_OF_RESOURCES     Required system resources could not be allocated.
 335   @retval EFI_TFTP_ERROR           An MTFTPv4 ERROR packet was received and is in the Packet.
 336   @retval EFI_NETWORK_UNREACHABLE  An ICMP network unreachable error packet was received and the Packet is set to NULL.
 337   @retval EFI_HOST_UNREACHABLE     An ICMP host unreachable error packet was received and the Packet is set to NULL.
 338   @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received and the Packet is set to NULL.
 339   @retval EFI_PORT_UNREACHABLE     An ICMP port unreachable error packet was received and the Packet is set to NULL.
 340   @retval EFI_ICMP_ERROR           Some other ICMP ERROR packet was received and is in the Buffer.
 341   @retval EFI_PROTOCOL_ERROR       An unexpected MTFTPv4 packet was received and is in the Packet.
 342   @retval EFI_TIMEOUT              No responses were received from the MTFTPv4 server.
 343   @retval EFI_DEVICE_ERROR         An unexpected network error or system error occurred.
 344   @retval EFI_NO_MEDIA             There was a media error.
 345
 346 **/
 347 typedef
 348 EFI_STATUS
 349 (EFIAPI *EFI_MTFTP4_GET_INFO)(
 350   IN  EFI_MTFTP4_PROTOCOL      *This,
 351   IN  EFI_MTFTP4_OVERRIDE_DATA *OverrideData   OPTIONAL,
 352   IN  UINT8                    *Filename,
 353   IN  UINT8                    *ModeStr        OPTIONAL,
 354   IN  UINT8                    OptionCount,
 355   IN  EFI_MTFTP4_OPTION        *OptionList,
 356   OUT UINT32                   *PacketLength,
 357   OUT EFI_MTFTP4_PACKET        **Packet        OPTIONAL
 358   );
 359
 360 /**
 361   Parses the options in an MTFTPv4 OACK packet.
 362
 363   @param  This         The pointer to the EFI_MTFTP4_PROTOCOL instance.
 364   @param  PacketLen    Length of the OACK packet to be parsed.
 365   @param  Packet       The pointer to the OACK packet to be parsed.
 366   @param  OptionCount  The pointer to the number of options in following OptionList.
 367   @param  OptionList   The pointer to EFI_MTFTP4_OPTION storage. Call the EFI Boot
 368                        Service FreePool() to release the OptionList if the options
 369                        in this OptionList are not needed any more.
 370
 371   @retval EFI_SUCCESS           The OACK packet was valid and the OptionCount and
 372                                 OptionList parameters have been updated.
 373   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 374                                 - PacketLen is 0.
 375                                 - Packet is NULL or Packet is not a valid MTFTPv4 packet.
 376                                 - OptionCount is NULL.
 377   @retval EFI_NOT_FOUND         No options were found in the OACK packet.
 378   @retval EFI_OUT_OF_RESOURCES  Storage for the OptionList array cannot be allocated.
 379   @retval EFI_PROTOCOL_ERROR    One or more of the option fields is invalid.
 380
 381 **/
 382 typedef
 383 EFI_STATUS
 384 (EFIAPI *EFI_MTFTP4_PARSE_OPTIONS)(
 385   IN  EFI_MTFTP4_PROTOCOL      *This,
 386   IN  UINT32                   PacketLen,
 387   IN  EFI_MTFTP4_PACKET        *Packet,
 388   OUT UINT32                   *OptionCount,
 389   OUT EFI_MTFTP4_OPTION        **OptionList OPTIONAL
 390   );
 391
 392
 393 /**
 394   Downloads a file from an MTFTPv4 server.
 395
 396   @param  This  The pointer to the EFI_MTFTP4_PROTOCOL instance.
 397   @param  Token The pointer to the token structure to provide the parameters that are
 398                 used in this operation.
 399
 400   @retval EFI_SUCCESS              The data file has been transferred successfully.
 401   @retval EFI_OUT_OF_RESOURCES     Required system resources could not be allocated.
 402   @retval EFI_BUFFER_TOO_SMALL     BufferSize is not zero but not large enough to hold the
 403                                    downloaded data in downloading process.
 404   @retval EFI_ABORTED              Current operation is aborted by user.
 405   @retval EFI_NETWORK_UNREACHABLE  An ICMP network unreachable error packet was received.
 406   @retval EFI_HOST_UNREACHABLE     An ICMP host unreachable error packet was received.
 407   @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received.
 408   @retval EFI_PORT_UNREACHABLE     An ICMP port unreachable error packet was received.
 409   @retval EFI_ICMP_ERROR           Some other  ICMP ERROR packet was received.
 410   @retval EFI_TIMEOUT              No responses were received from the MTFTPv4 server.
 411   @retval EFI_TFTP_ERROR           An MTFTPv4 ERROR packet was received.
 412   @retval EFI_DEVICE_ERROR         An unexpected network error or system error occurred.
 413   @retval EFI_NO_MEDIA             There was a media error.
 414
 415 **/
 416 typedef
 417 EFI_STATUS
 418 (EFIAPI *EFI_MTFTP4_READ_FILE)(
 419   IN EFI_MTFTP4_PROTOCOL       *This,
 420   IN EFI_MTFTP4_TOKEN          *Token
 421   );
 422
 423
 424
 425 /**
 426   Sends a file to an MTFTPv4 server.
 427
 428   @param  This  The pointer to the EFI_MTFTP4_PROTOCOL instance.
 429   @param  Token The pointer to the token structure to provide the parameters that are
 430                 used in this operation.
 431
 432   @retval EFI_SUCCESS           The upload session has started.
 433   @retval EFI_UNSUPPORTED       The operation is not supported by this implementation.
 434   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 435   @retval EFI_UNSUPPORTED       One or more options in the Token.OptionList are in
 436                                 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
 437   @retval EFI_NOT_STARTED       The EFI MTFTPv4 Protocol driver has not been started.
 438   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
 439                                 RARP, etc.) is not finished yet.
 440   @retval EFI_ALREADY_STARTED   This Token is already being used in another MTFTPv4 session.
 441   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 442   @retval EFI_ACCESS_DENIED     The previous operation has not completed yet.
 443   @retval EFI_DEVICE_ERROR      An unexpected network error or system error occurred.
 444
 445 **/
 446 typedef
 447 EFI_STATUS
 448 (EFIAPI *EFI_MTFTP4_WRITE_FILE)(
 449   IN EFI_MTFTP4_PROTOCOL       *This,
 450   IN EFI_MTFTP4_TOKEN          *Token
 451   );
 452
 453
 454 /**
 455   Downloads a data file "directory" from an MTFTPv4 server. May be unsupported in some EFI
 456   implementations.
 457
 458   @param  This  The pointer to the EFI_MTFTP4_PROTOCOL instance.
 459   @param  Token The pointer to the token structure to provide the parameters that are
 460                 used in this operation.
 461
 462   @retval EFI_SUCCESS           The MTFTPv4 related file "directory" has been downloaded.
 463   @retval EFI_UNSUPPORTED       The operation is not supported by this implementation.
 464   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 465   @retval EFI_UNSUPPORTED       One or more options in the Token.OptionList are in
 466                                 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
 467   @retval EFI_NOT_STARTED       The EFI MTFTPv4 Protocol driver has not been started.
 468   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
 469                                 RARP, etc.) is not finished yet.
 470   @retval EFI_ALREADY_STARTED   This Token is already being used in another MTFTPv4 session.
 471   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 472   @retval EFI_ACCESS_DENIED     The previous operation has not completed yet.
 473   @retval EFI_DEVICE_ERROR      An unexpected network error or system error occurred.
 474
 475 **/
 476 typedef
 477 EFI_STATUS
 478 (EFIAPI *EFI_MTFTP4_READ_DIRECTORY)(
 479   IN EFI_MTFTP4_PROTOCOL       *This,
 480   IN EFI_MTFTP4_TOKEN          *Token
 481   );
 482
 483 /**
 484   Polls for incoming data packets and processes outgoing data packets.
 485
 486   @param  This The pointer to the EFI_MTFTP4_PROTOCOL instance.
 487
 488   @retval  EFI_SUCCESS           Incoming or outgoing data was processed.
 489   @retval  EFI_NOT_STARTED       This EFI MTFTPv4 Protocol instance has not been started.
 490   @retval  EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
 491                                  RARP, etc.) is not finished yet.
 492   @retval  EFI_INVALID_PARAMETER This is NULL.
 493   @retval  EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 494   @retval  EFI_TIMEOUT           Data was dropped out of the transmit and/or receive queue.
 495                                  Consider increasing the polling rate.
 496
 497 **/
 498 typedef
 499 EFI_STATUS
 500 (EFIAPI *EFI_MTFTP4_POLL)(
 501   IN EFI_MTFTP4_PROTOCOL       *This
 502   );
 503
 504 ///
 505 /// The EFI_MTFTP4_PROTOCOL is designed to be used by UEFI drivers and applications
 506 /// to transmit and receive data files. The EFI MTFTPv4 Protocol driver uses
 507 /// the underlying EFI UDPv4 Protocol driver and EFI IPv4 Protocol driver.
 508 ///
 509 struct _EFI_MTFTP4_PROTOCOL {
 510   EFI_MTFTP4_GET_MODE_DATA     GetModeData;
 511   EFI_MTFTP4_CONFIGURE         Configure;
 512   EFI_MTFTP4_GET_INFO          GetInfo;
 513   EFI_MTFTP4_PARSE_OPTIONS     ParseOptions;
 514   EFI_MTFTP4_READ_FILE         ReadFile;
 515   EFI_MTFTP4_WRITE_FILE        WriteFile;
 516   EFI_MTFTP4_READ_DIRECTORY    ReadDirectory;
 517   EFI_MTFTP4_POLL              Poll;
 518 };
 519
 520 struct _EFI_MTFTP4_TOKEN {
 521   ///
 522   /// The status that is returned to the caller at the end of the operation
 523   /// to indicate whether this operation completed successfully.
 524   ///
 525   EFI_STATUS                  Status;
 526   ///
 527   /// The event that will be signaled when the operation completes. If
 528   /// set to NULL, the corresponding function will wait until the read or
 529   /// write operation finishes. The type of Event must be
 530   /// EVT_NOTIFY_SIGNAL. The Task Priority Level (TPL) of
 531   /// Event must be lower than or equal to TPL_CALLBACK.
 532   ///
 533   EFI_EVENT                   Event;
 534   ///
 535   /// If not NULL, the data that will be used to override the existing configure data.
 536   ///
 537   EFI_MTFTP4_OVERRIDE_DATA    *OverrideData;
 538   ///
 539   /// The pointer to the null-terminated ASCII file name string.
 540   ///
 541   UINT8                       *Filename;
 542   ///
 543   /// The pointer to the null-terminated ASCII mode string. If NULL, "octet" is used.
 544   ///
 545   UINT8                       *ModeStr;
 546   ///
 547   /// Number of option/value string pairs.
 548   ///
 549   UINT32                      OptionCount;
 550   ///
 551   /// The pointer to an array of option/value string pairs. Ignored if OptionCount is zero.
 552   ///
 553   EFI_MTFTP4_OPTION           *OptionList;
 554   ///
 555   /// The size of the data buffer.
 556   ///
 557   UINT64                      BufferSize;
 558   ///
 559   /// The pointer to the data buffer. Data that is downloaded from the
 560   /// MTFTPv4 server is stored here. Data that is uploaded to the
 561   /// MTFTPv4 server is read from here. Ignored if BufferSize is zero.
 562   ///
 563   VOID                        *Buffer;
 564   ///
 565   /// The pointer to the context that will be used by CheckPacket,
 566   /// TimeoutCallback and PacketNeeded.
 567   ///
 568   VOID                        *Context;
 569   ///
 570   /// The pointer to the callback function to check the contents of the received packet.
 571   ///
 572   EFI_MTFTP4_CHECK_PACKET     CheckPacket;
 573   ///
 574   /// The pointer to the function to be called when a timeout occurs.
 575   ///
 576   EFI_MTFTP4_TIMEOUT_CALLBACK TimeoutCallback;
 577   ///
 578   /// The pointer to the function to provide the needed packet contents.
 579   ///
 580   EFI_MTFTP4_PACKET_NEEDED    PacketNeeded;
 581 };
 582
 583 extern EFI_GUID gEfiMtftp4ServiceBindingProtocolGuid;
 584 extern EFI_GUID gEfiMtftp4ProtocolGuid;
 585
 586 #endif
 587