2 EFI Multicast Trivial File Tranfer Protocol Definition
4 Copyright (c) 2006 - 2008, 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
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.
15 #ifndef __EFI_MTFTP4_PROTOCOL_H__
16 #define __EFI_MTFTP4_PROTOCOL_H__
18 #define EFI_MTFTP4_SERVICE_BINDING_PROTOCOL_GUID \
20 0x2FE800BE, 0x8F01, 0x4aa6, {0x94, 0x6B, 0xD7, 0x13, 0x88, 0xE1, 0x83, 0x3F } \
23 #define EFI_MTFTP4_PROTOCOL_GUID \
25 0x78247c57, 0x63db, 0x4708, {0x99, 0xc2, 0xa8, 0xb4, 0xa9, 0xa6, 0x1f, 0x6b } \
28 typedef struct _EFI_MTFTP4_PROTOCOL EFI_MTFTP4_PROTOCOL
;
29 typedef struct _EFI_MTFTP4_TOKEN EFI_MTFTP4_TOKEN
;
32 //MTFTP4 packet opcode definition
34 #define EFI_MTFTP4_OPCODE_RRQ 1
35 #define EFI_MTFTP4_OPCODE_WRQ 2
36 #define EFI_MTFTP4_OPCODE_DATA 3
37 #define EFI_MTFTP4_OPCODE_ACK 4
38 #define EFI_MTFTP4_OPCODE_ERROR 5
39 #define EFI_MTFTP4_OPCODE_OACK 6
40 #define EFI_MTFTP4_OPCODE_DIR 7
41 #define EFI_MTFTP4_OPCODE_DATA8 8
42 #define EFI_MTFTP4_OPCODE_ACK8 9
45 // MTFTP4 error code definition
47 #define EFI_MTFTP4_ERRORCODE_NOT_DEFINED 0
48 #define EFI_MTFTP4_ERRORCODE_FILE_NOT_FOUND 1
49 #define EFI_MTFTP4_ERRORCODE_ACCESS_VIOLATION 2
50 #define EFI_MTFTP4_ERRORCODE_DISK_FULL 3
51 #define EFI_MTFTP4_ERRORCODE_ILLEGAL_OPERATION 4
52 #define EFI_MTFTP4_ERRORCODE_UNKNOWN_TRANSFER_ID 5
53 #define EFI_MTFTP4_ERRORCODE_FILE_ALREADY_EXISTS 6
54 #define EFI_MTFTP4_ERRORCODE_NO_SUCH_USER 7
55 #define EFI_MTFTP4_ERRORCODE_REQUEST_DENIED 8
58 // MTFTP4 pacekt definitions
65 } EFI_MTFTP4_REQ_HEADER
;
70 } EFI_MTFTP4_OACK_HEADER
;
76 } EFI_MTFTP4_DATA_HEADER
;
81 } EFI_MTFTP4_ACK_HEADER
;
87 } EFI_MTFTP4_DATA8_HEADER
;
92 } EFI_MTFTP4_ACK8_HEADER
;
97 UINT8 ErrorMessage
[1];
98 } EFI_MTFTP4_ERROR_HEADER
;
102 /// Type of packets as defined by the MTFTPv4 packet opcodes.
106 /// Read request packet header.
108 EFI_MTFTP4_REQ_HEADER Rrq
;
110 /// Write request packet header.
112 EFI_MTFTP4_REQ_HEADER Wrq
;
114 /// Option acknowledge packet header.
116 EFI_MTFTP4_OACK_HEADER Oack
;
118 /// Data packet header.
120 EFI_MTFTP4_DATA_HEADER Data
;
122 /// Acknowledgement packet header.
124 EFI_MTFTP4_ACK_HEADER Ack
;
126 /// Data packet header with big block number.
128 EFI_MTFTP4_DATA8_HEADER Data8
;
130 /// Acknowledgement header with big block num.
132 EFI_MTFTP4_ACK8_HEADER Ack8
;
134 /// Error packet header.
136 EFI_MTFTP4_ERROR_HEADER Error
;
142 /// MTFTP4 option definition
151 BOOLEAN UseDefaultSetting
;
152 EFI_IPv4_ADDRESS StationIp
;
153 EFI_IPv4_ADDRESS SubnetMask
;
155 EFI_IPv4_ADDRESS GatewayIp
;
156 EFI_IPv4_ADDRESS ServerIp
;
157 UINT16 InitialServerPort
;
160 } EFI_MTFTP4_CONFIG_DATA
;
164 EFI_MTFTP4_CONFIG_DATA ConfigData
;
165 UINT8 SupportedOptionCount
;
166 UINT8
**SupportedOptoins
;
167 UINT8 UnsupportedOptionCount
;
168 UINT8
**UnsupportedOptoins
;
169 } EFI_MTFTP4_MODE_DATA
;
173 EFI_IPv4_ADDRESS GatewayIp
;
174 EFI_IPv4_ADDRESS ServerIp
;
178 } EFI_MTFTP4_OVERRIDE_DATA
;
181 // Protocol interfaces definition
185 a callback function that is provided by the caller to intercept
186 the EFI_MTFTP4_OPCODE_DATA or EFI_MTFTP4_OPCODE_DATA8 packets processed in the
187 EFI_MTFTP4_PROTOCOL.ReadFile() function, and alternatively to intercept
188 EFI_MTFTP4_OPCODE_OACK or EFI_MTFTP4_OPCODE_ERROR packets during a call to
189 EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory().
191 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
192 @param Token The token that the caller provided in the
193 EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile()
194 or ReadDirectory() function.
195 @param PacketLen Indicates the length of the packet.
196 @param Packet Pointer to an MTFTPv4 packet.
198 @retval EFI_SUCCESS Operation sucess
199 @retval Others Abort transfer process
204 (EFIAPI
*EFI_MTFTP4_CHECK_PACKET
)(
205 IN EFI_MTFTP4_PROTOCOL
*This
,
206 IN EFI_MTFTP4_TOKEN
*Token
,
208 IN EFI_MTFTP4_PACKET
*Paket
212 Timeout callback funtion.
214 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
215 @param Token The token that is provided in the
216 EFI_MTFTP4_PROTOCOL.ReadFile() or
217 EFI_MTFTP4_PROTOCOL.WriteFile() or
218 EFI_MTFTP4_PROTOCOL.ReadDirectory() functions
221 @retval EFI_SUCCESS Operation sucess
222 @retval Others Aborts download process.
227 (EFIAPI
*EFI_MTFTP4_TIMEOUT_CALLBACK
)(
228 IN EFI_MTFTP4_PROTOCOL
*This
,
229 IN EFI_MTFTP4_TOKEN
*Token
233 a callback function that the caller provides to feed data to the
234 EFI_MTFTP4_PROTOCOL.WriteFile() function.
236 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
237 @param Token The token provided in the
238 EFI_MTFTP4_PROTOCOL.WriteFile() by the caller.
239 @param Length Indicates the length of the raw data wanted on input, and the
240 length the data available on output.
241 @param Buffer Pointer to the buffer where the data is stored.
243 @retval EFI_SUCCESS Operation sucess
244 @retval Others Aborts session.
249 (EFIAPI
*EFI_MTFTP4_PACKET_NEEDED
)(
250 IN EFI_MTFTP4_PROTOCOL
*This
,
251 IN EFI_MTFTP4_TOKEN
*Token
,
252 IN OUT UINT16
*Length
,
258 Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
260 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
261 @param ModeData Pointer to storage for the EFI MTFTPv4 Protocol driver mode data.
263 @retval EFI_SUCCESS The configuration data was successfully returned.
264 @retval EFI_OUT_OF_RESOURCES The required mode data could not be allocated.
265 @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
270 (EFIAPI
*EFI_MTFTP4_GET_MODE_DATA
)(
271 IN EFI_MTFTP4_PROTOCOL
*This
,
272 OUT EFI_MTFTP4_MODE_DATA
*ModeData
277 Initializes, changes, or resets the default operational setting for this
278 EFI MTFTPv4 Protocol driver instance.
280 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
281 @param MtftpConfigData Pointer to the configuration data structure.
283 @retval EFI_SUCCESS The EFI MTFTPv4 Protocol driver was configured successfully.
284 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
285 @retval EFI_ACCESS_DENIED The EFI configuration could not be changed at this time because
286 there is one MTFTP background operation in progress.
287 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
288 RARP, etc.) has not finished yet.
289 @retval EFI_UNSUPPORTED A configuration protocol (DHCP, BOOTP, RARP, etc.) could not
290 be located when clients choose to use the default address
292 @retval EFI_OUT_OF_RESOURCES The EFI MTFTPv4 Protocol driver instance data could not be
294 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI
295 MTFTPv4 Protocol driver instance is not configured.
300 (EFIAPI
*EFI_MTFTP4_CONFIGURE
)(
301 IN EFI_MTFTP4_PROTOCOL
*This
,
302 IN EFI_MTFTP4_CONFIG_DATA
*MtftpConfigData OPTIONAL
307 Gets information about a file from an MTFTPv4 server.
309 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
310 @param OverrideData Data that is used to override the existing parameters. If NULL,
311 the default parameters that were set in the
312 EFI_MTFTP4_PROTOCOL.Configure() function are used.
313 @param Filename Pointer to ASCIIZ file name string.
314 @param ModeStr Pointer to ASCIIZ mode string. If NULL, "octet" will be used.
315 @param OptionCount Number of option/value string pairs in OptionList.
316 @param OptionList Pointer to array of option/value string pairs. Ignored if
318 @param PacketLength The number of bytes in the returned packet.
319 @param Packet The pointer to the received packet. This buffer must be freed by
322 @retval EFI_SUCCESS An MTFTPv4 OACK packet was received and is in the Buffer.
323 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
324 @retval EFI_UNSUPPORTED One or more options in the OptionList are in the
325 unsupported list of structure EFI_MTFTP4_MODE_DATA.
326 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
327 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
328 RARP, etc.) has not finished yet.
329 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
330 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
331 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received and is in the buffer.
332 @retval EFI_ICMP_ERROR An ICMP ERROR packet was received and is in the Buffer.
333 @retval EFI_PROTOCOL_ERROR An unexpected MTFTPv4 packet was received and is in the buffer.
334 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
335 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
340 (EFIAPI
*EFI_MTFTP4_GET_INFO
)(
341 IN EFI_MTFTP4_PROTOCOL
*This
,
342 IN EFI_MTFTP4_OVERRIDE_DATA
*OverrideData OPTIONAL
,
344 IN UINT8
*ModeStr OPTIONAL
,
345 IN UINT8 OptionCount
,
346 IN EFI_MTFTP4_OPTION
*OptionList
,
347 OUT UINT32
*PacketLength
,
348 OUT EFI_MTFTP4_PACKET
**Packet OPTIONAL
352 Parses the options in an MTFTPv4 OACK packet.
354 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
355 @param PacketLen Length of the OACK packet to be parsed.
356 @param Packet Pointer to the OACK packet to be parsed.
357 @param OptionCount Pointer to the number of options in following OptionList.
358 @param OptionList Pointer to EFI_MTFTP4_OPTION storage. Call the EFI Boot
359 Service FreePool() to release each option if they are not
362 @retval EFI_SUCCESS The OACK packet was valid and the OptionCount and
363 OptionList parameters have been updated.
364 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
366 - Packet is NULL or Packet is not a valid MTFTPv4 packet.
367 - OptionCount is NULL.
368 @retval EFI_NOT_FOUND No options were found in the OACK packet.
369 @retval EFI_OUT_OF_RESOURCES Storage for the OptionList array cannot be allocated.
370 @retval EFI_PROTOCOL_ERROR One or more of the option fields is invalid.
375 (EFIAPI
*EFI_MTFTP4_PARSE_OPTIONS
)(
376 IN EFI_MTFTP4_PROTOCOL
*This
,
378 IN EFI_MTFTP4_PACKET
*Packet
,
379 OUT UINT32
*OptionCount
,
380 OUT EFI_MTFTP4_OPTION
**OptionList OPTIONAL
385 Downloads a file from an MTFTPv4 server.
387 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
388 @param Token Pointer to the token structure to provide the parameters that are
389 used in this operation.
391 @retval EFI_SUCCESS The data file has been transferred successfully.
392 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
393 @retval EFI_BUFFER_TOO_SMALL BufferSize is not large enough to hold the downloaded data
394 in downloading process.
395 @retval EFI_ABORTED Current operation is aborted by user.
396 @retval EFI_ICMP_ERROR An ICMP ERROR packet was received.
397 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
398 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received.
399 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
404 (EFIAPI
*EFI_MTFTP4_READ_FILE
)(
405 IN EFI_MTFTP4_PROTOCOL
*This
,
406 IN EFI_MTFTP4_TOKEN
*Token
412 Sends a file to an MTFTPv4 server.
414 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
415 @param Token Pointer to the token structure to provide the parameters that are
416 used in this operation.
418 @retval EFI_SUCCESS The upload session has started.
419 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
420 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
421 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in
422 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
423 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
424 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
425 RARP, etc.) is not finished yet.
426 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4 session.
427 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
428 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
429 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
434 (EFIAPI
*EFI_MTFTP4_WRITE_FILE
)(
435 IN EFI_MTFTP4_PROTOCOL
*This
,
436 IN EFI_MTFTP4_TOKEN
*Token
441 Downloads a data file "directory" from an MTFTPv4 server. May be unsupported in some EFI
444 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
445 @param Token Pointer to the token structure to provide the parameters that are
446 used in this operation.
448 @retval EFI_SUCCESS The MTFTPv4 related file "directory" has been downloaded.
449 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
450 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
451 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in
452 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
453 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
454 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
455 RARP, etc.) is not finished yet.
456 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4 session.
457 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
458 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
459 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
464 (EFIAPI
*EFI_MTFTP4_READ_DIRECTORY
)(
465 IN EFI_MTFTP4_PROTOCOL
*This
,
466 IN EFI_MTFTP4_TOKEN
*Token
470 Polls for incoming data packets and processes outgoing data packets.
472 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
474 @retval EFI_SUCCESS Incoming or outgoing data was processed.
475 @retval EFI_NOT_STARTED This EFI MTFTPv4 Protocol instance 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_INVALID_PARAMETER This is NULL.
479 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
480 @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue.
481 Consider increasing the polling rate.
486 (EFIAPI
*EFI_MTFTP4_POLL
)(
487 IN EFI_MTFTP4_PROTOCOL
*This
491 /// The EFI_MTFTP4_PROTOCOL is designed to be used by UEFI drivers and applications
492 /// to transmit and receive data files. The EFI MTFTPv4 Protocol driver uses
493 /// the underlying EFI UDPv4 Protocol driver and EFI IPv4 Protocol driver.
495 struct _EFI_MTFTP4_PROTOCOL
{
496 EFI_MTFTP4_GET_MODE_DATA GetModeData
;
497 EFI_MTFTP4_CONFIGURE Configure
;
498 EFI_MTFTP4_GET_INFO GetInfo
;
499 EFI_MTFTP4_PARSE_OPTIONS ParseOptions
;
500 EFI_MTFTP4_READ_FILE ReadFile
;
501 EFI_MTFTP4_WRITE_FILE WriteFile
;
502 EFI_MTFTP4_READ_DIRECTORY ReadDirectory
;
503 EFI_MTFTP4_POLL Poll
;
506 struct _EFI_MTFTP4_TOKEN
{
508 /// The status that is returned to the caller at the end of the operation
509 /// to indicate whether this operation completed successfully.
513 /// The event that will be signaled when the operation completes. If
514 /// set to NULL, the corresponding function will wait until the read or
515 /// write operation finishes. The type of Event must be
516 /// EVT_NOTIFY_SIGNAL. The Task Priority Level (TPL) of
517 /// Event must be lower than or equal to TPL_CALLBACK.
521 /// If not NULL, the data that will be used to override the existing configure data.
523 EFI_MTFTP4_OVERRIDE_DATA
*OverrideData
;
525 /// Pointer to the ASCIIZ file name string.
529 /// Pointer to the ASCIIZ mode string. If NULL, "octet" is used.
533 /// Number of option/value string pairs.
537 /// Pointer to an array of option/value string pairs. Ignored if OptionCount is zero.
539 EFI_MTFTP4_OPTION
*OptionList
;
541 /// Size of the data buffer.
543 OUT UINT64 BufferSize
;
545 /// Pointer to the data buffer. Data that is downloaded from the
546 /// MTFTPv4 server is stored here. Data that is uploaded to the
547 /// MTFTPv4 server is read from here. Ignored if BufferSize is zero.
551 /// Pointer to the callback function to check the contents of the received packet.
553 EFI_MTFTP4_CHECK_PACKET CheckPacket
;
555 /// Pointer to the function to be called when a timeout occurs.
557 EFI_MTFTP4_TIMEOUT_CALLBACK TimeoutCallback
;
559 /// Pointer to the function to provide the needed packet contents.
561 EFI_MTFTP4_PACKET_NEEDED PacketNeeded
;
564 extern EFI_GUID gEfiMtftp4ServiceBindingProtocolGuid
;
565 extern EFI_GUID gEfiMtftp4ProtocolGuid
;