← Back to branch summary

~pmdj/ubuntu/trusty/qemu/2.9+applesmc+fadtv3

« back to all changes in this revision

Viewing changes to roms/ipxe/src/include/ipxe/efi/Protocol/Mtftp4.h

  • Committer: Phil Dennis-Jordan
  • Date: 2017-07-21 08:03:43 UTC
  • mfrom: (1.1.1)
  • Revision ID: phil@philjordan.eu-20170721080343-2yr2vdj7713czahv
New upstream release 2.9.0.

Show diffs side-by-side

added added

removed removed

Lines of Context:
roms/ipxe/src/include/ipxe/efi/Protocol/Mtftp4.h
 
1
/** @file
 
2
  EFI Multicast Trivial File Transfer 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 function.
 
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