MdePkg/Include/Protocol/Mtftp4.h

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