2 Interface routine for Mtftp4.
4 Copyright (c) 2006 - 2007, Intel Corporation<BR>
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<BR>
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.
16 #include "Mtftp4Impl.h"
20 Clean up the MTFTP session to get ready for new operation.
22 @param Instance The MTFTP session to clean up
23 @param Result The result to return to the caller who initiated
27 Mtftp4CleanOperation (
28 IN OUT MTFTP4_PROTOCOL
*Instance
,
34 MTFTP4_BLOCK_RANGE
*Block
;
35 EFI_MTFTP4_TOKEN
*Token
;
38 // Free various resources.
40 Token
= Instance
->Token
;
43 Token
->Status
= Result
;
45 if (Token
->Event
!= NULL
) {
46 gBS
->SignalEvent (Token
->Event
);
49 Instance
->Token
= NULL
;
52 ASSERT (Instance
->UnicastPort
!= NULL
);
53 UdpIoCleanPort (Instance
->UnicastPort
);
55 if (Instance
->LastPacket
!= NULL
) {
56 NetbufFree (Instance
->LastPacket
);
57 Instance
->LastPacket
= NULL
;
60 if (Instance
->McastUdpPort
!= NULL
) {
61 UdpIoFreePort (Instance
->McastUdpPort
);
62 Instance
->McastUdpPort
= NULL
;
65 NET_LIST_FOR_EACH_SAFE (Entry
, Next
, &Instance
->Blocks
) {
66 Block
= NET_LIST_USER_STRUCT (Entry
, MTFTP4_BLOCK_RANGE
, Link
);
67 RemoveEntryList (Entry
);
68 gBS
->FreePool (Block
);
71 ZeroMem (&Instance
->RequestOption
, sizeof (MTFTP4_OPTION
));
73 Instance
->Operation
= 0;
75 Instance
->BlkSize
= MTFTP4_DEFAULT_BLKSIZE
;
76 Instance
->LastBlock
= 0;
77 Instance
->ServerIp
= 0;
78 Instance
->ListeningPort
= 0;
79 Instance
->ConnectedPort
= 0;
80 Instance
->Gateway
= 0;
81 Instance
->PacketToLive
= 0;
82 Instance
->MaxRetry
= 0;
83 Instance
->CurRetry
= 0;
84 Instance
->Timeout
= 0;
85 Instance
->McastIp
= 0;
86 Instance
->McastPort
= 0;
87 Instance
->Master
= TRUE
;
92 Check packet for GetInfo.
94 GetInfo is implemented with EfiMtftp4ReadFile. It use Mtftp4GetInfoCheckPacket
95 to inspect the first packet from server, then abort the session.
97 @param This The MTFTP4 protocol instance
98 @param Token The user's token
99 @param PacketLen The length of the packet
100 @param Packet The received packet.
102 @retval EFI_ABORTED Abort the ReadFile operation and return.
106 Mtftp4GetInfoCheckPacket (
107 IN EFI_MTFTP4_PROTOCOL
*This
,
108 IN EFI_MTFTP4_TOKEN
*Token
,
110 IN EFI_MTFTP4_PACKET
*Packet
113 MTFTP4_PROTOCOL
*Instance
;
114 MTFTP4_GETINFO_STATE
*State
;
118 Instance
= MTFTP4_PROTOCOL_FROM_THIS (This
);
119 State
= &Instance
->GetInfoState
;
120 OpCode
= NTOHS (Packet
->OpCode
);
123 // Set the GetInfo's return status according to the OpCode.
126 case EFI_MTFTP4_OPCODE_ERROR
:
127 State
->Status
= EFI_TFTP_ERROR
;
130 case EFI_MTFTP4_OPCODE_OACK
:
131 State
->Status
= EFI_SUCCESS
;
135 State
->Status
= EFI_PROTOCOL_ERROR
;
139 // Allocate buffer then copy the packet over. Use gBS->AllocatePool
140 // in case AllocatePool will implements something tricky.
142 Status
= gBS
->AllocatePool (EfiBootServicesData
, PacketLen
, (VOID
**) State
->Packet
);
144 if (EFI_ERROR (Status
)) {
145 State
->Status
= EFI_OUT_OF_RESOURCES
;
149 *(State
->PacketLen
) = PacketLen
;
150 CopyMem (*(State
->Packet
), Packet
, PacketLen
);
157 Check whether the override data is valid.
159 It will first validate whether the server is a valid unicast. If a gateway
160 is provided in the Override, it also check that it is a unicast on the
163 @param Instance The MTFTP instance
164 @param Override The override data to validate.
166 @retval TRUE The override data is valid
167 @retval FALSE The override data is invalid
171 Mtftp4OverrideValid (
172 IN MTFTP4_PROTOCOL
*Instance
,
173 IN EFI_MTFTP4_OVERRIDE_DATA
*Override
176 EFI_MTFTP4_CONFIG_DATA
*Config
;
181 CopyMem (&Ip
, &Override
->ServerIp
, sizeof (IP4_ADDR
));
182 if (!Ip4IsUnicast (NTOHL (Ip
), 0)) {
186 Config
= &Instance
->Config
;
188 CopyMem (&Gateway
, &Override
->GatewayIp
, sizeof (IP4_ADDR
));
189 Gateway
= NTOHL (Gateway
);
191 if (!Config
->UseDefaultSetting
&& (Gateway
!= 0)) {
192 CopyMem (&Netmask
, &Config
->SubnetMask
, sizeof (IP4_ADDR
));
193 CopyMem (&Ip
, &Config
->StationIp
, sizeof (IP4_ADDR
));
195 Netmask
= NTOHL (Netmask
);
198 if (!Ip4IsUnicast (Gateway
, Netmask
) || !IP4_NET_EQUAL (Gateway
, Ip
, Netmask
)) {
208 Poll the UDP to get the IP4 default address, which may be retrieved
211 The default time out value is 5 seconds. If IP has retrieved the default address,
212 the UDP is reconfigured.
214 @param Instance The Mtftp instance
215 @param UdpPort The UDP port to poll
216 @param UdpCfgData The UDP configure data to reconfigure the UDP
219 @retval TRUE The default address is retrieved and UDP is reconfigured.
220 @retval FALSE Some error occured.
225 IN MTFTP4_PROTOCOL
*Instance
,
226 IN UDP_IO_PORT
*UdpPort
,
227 IN EFI_UDP4_CONFIG_DATA
*UdpCfgData
230 MTFTP4_SERVICE
*Service
;
231 EFI_IP4_MODE_DATA Ip4Mode
;
232 EFI_UDP4_PROTOCOL
*Udp
;
235 ASSERT (Instance
->Config
.UseDefaultSetting
);
237 Service
= Instance
->Service
;
240 Status
= gBS
->SetTimer (
241 Service
->TimerToGetMap
,
243 MTFTP4_TIME_TO_GETMAP
* TICKS_PER_SECOND
245 if (EFI_ERROR (Status
)) {
249 while (!EFI_ERROR (gBS
->CheckEvent (Service
->TimerToGetMap
))) {
252 if (!EFI_ERROR (Udp
->GetModeData (Udp
, NULL
, &Ip4Mode
, NULL
, NULL
)) &&
253 Ip4Mode
.IsConfigured
) {
255 Udp
->Configure (Udp
, NULL
);
256 return (BOOLEAN
) (Udp
->Configure (Udp
, UdpCfgData
) == EFI_SUCCESS
);
265 Configure the UDP port for unicast receiving.
267 @param UdpIo The UDP port
268 @param Instance The MTFTP session
270 @retval EFI_SUCCESS The UDP port is successfully configured for the
271 session to unicast receive.
275 Mtftp4ConfigUnicastPort (
276 IN UDP_IO_PORT
*UdpIo
,
277 IN MTFTP4_PROTOCOL
*Instance
280 EFI_MTFTP4_CONFIG_DATA
*Config
;
281 EFI_UDP4_CONFIG_DATA UdpConfig
;
285 Config
= &Instance
->Config
;
287 UdpConfig
.AcceptBroadcast
= FALSE
;
288 UdpConfig
.AcceptPromiscuous
= FALSE
;
289 UdpConfig
.AcceptAnyPort
= FALSE
;
290 UdpConfig
.AllowDuplicatePort
= FALSE
;
291 UdpConfig
.TypeOfService
= 0;
292 UdpConfig
.TimeToLive
= 64;
293 UdpConfig
.DoNotFragment
= FALSE
;
294 UdpConfig
.ReceiveTimeout
= 0;
295 UdpConfig
.TransmitTimeout
= 0;
296 UdpConfig
.UseDefaultAddress
= Config
->UseDefaultSetting
;
297 UdpConfig
.StationAddress
= Config
->StationIp
;
298 UdpConfig
.SubnetMask
= Config
->SubnetMask
;
299 UdpConfig
.StationPort
= 0;
300 UdpConfig
.RemotePort
= 0;
302 Ip
= HTONL (Instance
->ServerIp
);
303 CopyMem (&UdpConfig
.RemoteAddress
, &Ip
, sizeof (EFI_IPv4_ADDRESS
));
305 Status
= UdpIo
->Udp
->Configure (UdpIo
->Udp
, &UdpConfig
);
307 if ((Status
== EFI_NO_MAPPING
) && Mtftp4GetMapping (Instance
, UdpIo
, &UdpConfig
)) {
311 if (!Config
->UseDefaultSetting
&& !EFI_IP4_EQUAL (&mZeroIp4Addr
, &Config
->GatewayIp
)) {
313 // The station IP address is manually configured and the Gateway IP is not 0.
314 // Add the default route for this UDP instance.
316 Status
= UdpIo
->Udp
->Routes (UdpIo
->Udp
, FALSE
, &mZeroIp4Addr
, &mZeroIp4Addr
, &Config
->GatewayIp
);
317 if (EFI_ERROR (Status
)) {
318 UdpIo
->Udp
->Configure (UdpIo
->Udp
, NULL
);
326 Start the MTFTP session to do the operation, such as read file,
327 write file, and read directory.
329 @param This The MTFTP session
330 @param Token The token than encapsues the user's request.
331 @param Operation The operation to do
333 @retval EFI_INVALID_PARAMETER Some of the parameters are invalid.
334 @retval EFI_NOT_STARTED The MTFTP session hasn't been configured.
335 @retval EFI_ALREADY_STARTED There is pending operation for the session.
336 @retval EFI_SUCCESS The operation is successfully started.
341 IN EFI_MTFTP4_PROTOCOL
*This
,
342 IN EFI_MTFTP4_TOKEN
*Token
,
346 MTFTP4_PROTOCOL
*Instance
;
347 EFI_MTFTP4_OVERRIDE_DATA
*Override
;
348 EFI_MTFTP4_CONFIG_DATA
*Config
;
353 // Validate the parameters
355 if ((This
== NULL
) || (Token
== NULL
) || (Token
->Filename
== NULL
) ||
356 ((Token
->OptionCount
!= 0) && (Token
->OptionList
== NULL
))) {
357 return EFI_INVALID_PARAMETER
;
361 // User must provide at least one method to collect the data for download.
363 if (((Operation
== EFI_MTFTP4_OPCODE_RRQ
) || (Operation
== EFI_MTFTP4_OPCODE_DIR
)) &&
364 ((Token
->Buffer
== NULL
) && (Token
->CheckPacket
== NULL
))) {
365 return EFI_INVALID_PARAMETER
;
369 // User must provide at least one method to provide the data for upload.
371 if ((Operation
== EFI_MTFTP4_OPCODE_WRQ
) &&
372 ((Token
->Buffer
== NULL
) && (Token
->PacketNeeded
== NULL
))) {
373 return EFI_INVALID_PARAMETER
;
376 Instance
= MTFTP4_PROTOCOL_FROM_THIS (This
);
378 Status
= EFI_SUCCESS
;
379 OldTpl
= gBS
->RaiseTPL (TPL_CALLBACK
);
381 if (Instance
->State
!= MTFTP4_STATE_CONFIGED
) {
382 Status
= EFI_NOT_STARTED
;
385 if (Instance
->Operation
!= 0) {
386 Status
= EFI_ACCESS_DENIED
;
389 if (EFI_ERROR (Status
)) {
390 gBS
->RestoreTPL (OldTpl
);
395 // Set the Operation now to prevent the application start other
398 Instance
->Operation
= Operation
;
399 Override
= Token
->OverrideData
;
401 if ((Override
!= NULL
) && !Mtftp4OverrideValid (Instance
, Override
)) {
402 Status
= EFI_INVALID_PARAMETER
;
406 if (Token
->OptionCount
!= 0) {
407 Status
= Mtftp4ParseOption (
411 &Instance
->RequestOption
414 if (EFI_ERROR (Status
)) {
420 // Set the operation parameters from the configuration or override data.
422 Config
= &Instance
->Config
;
423 Instance
->Token
= Token
;
424 Instance
->BlkSize
= MTFTP4_DEFAULT_BLKSIZE
;
426 CopyMem (&Instance
->ServerIp
, &Config
->ServerIp
, sizeof (IP4_ADDR
));
427 Instance
->ServerIp
= NTOHL (Instance
->ServerIp
);
429 Instance
->ListeningPort
= Config
->InitialServerPort
;
430 Instance
->ConnectedPort
= 0;
432 CopyMem (&Instance
->Gateway
, &Config
->GatewayIp
, sizeof (IP4_ADDR
));
433 Instance
->Gateway
= NTOHL (Instance
->Gateway
);
435 Instance
->MaxRetry
= Config
->TryCount
;
436 Instance
->Timeout
= Config
->TimeoutValue
;
437 Instance
->Master
= TRUE
;
439 if (Override
!= NULL
) {
440 CopyMem (&Instance
->ServerIp
, &Override
->ServerIp
, sizeof (IP4_ADDR
));
441 CopyMem (&Instance
->Gateway
, &Override
->GatewayIp
, sizeof (IP4_ADDR
));
443 Instance
->ServerIp
= NTOHL (Instance
->ServerIp
);
444 Instance
->Gateway
= NTOHL (Instance
->Gateway
);
446 Instance
->ListeningPort
= Override
->ServerPort
;
447 Instance
->MaxRetry
= Override
->TryCount
;
448 Instance
->Timeout
= Override
->TimeoutValue
;
451 if (Instance
->ListeningPort
== 0) {
452 Instance
->ListeningPort
= MTFTP4_DEFAULT_SERVER_PORT
;
455 if (Instance
->MaxRetry
== 0) {
456 Instance
->MaxRetry
= MTFTP4_DEFAULT_RETRY
;
459 if (Instance
->Timeout
== 0) {
460 Instance
->Timeout
= MTFTP4_DEFAULT_TIMEOUT
;
464 // Config the unicast UDP child to send initial request
466 Status
= Mtftp4ConfigUnicastPort (Instance
->UnicastPort
, Instance
);
468 if (EFI_ERROR (Status
)) {
473 // Set initial status.
475 Token
->Status
= EFI_NOT_READY
;
478 // Build and send an initial requests
480 if (Operation
== EFI_MTFTP4_OPCODE_WRQ
) {
481 Status
= Mtftp4WrqStart (Instance
, Operation
);
483 Status
= Mtftp4RrqStart (Instance
, Operation
);
486 gBS
->RestoreTPL (OldTpl
);
488 if (EFI_ERROR (Status
)) {
492 if (Token
->Event
!= NULL
) {
497 // Return immediately for asynchronous operation or poll the
498 // instance for synchronous operation.
500 while (Token
->Status
== EFI_NOT_READY
) {
504 return Token
->Status
;
507 Mtftp4CleanOperation (Instance
, Status
);
508 gBS
->RestoreTPL (OldTpl
);
515 Reads the current operational settings.
517 The GetModeData()function reads the current operational settings of this
518 EFI MTFTPv4 Protocol driver instance.
520 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
521 @param ModeData Pointer to storage for the EFI MTFTPv4 Protocol
524 @retval EFI_SUCCESS The configuration data was successfully returned.
525 @retval EFI_OUT_OF_RESOURCES The required mode data could not be allocated.
526 @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
531 EfiMtftp4GetModeData (
532 IN EFI_MTFTP4_PROTOCOL
*This
,
533 OUT EFI_MTFTP4_MODE_DATA
*ModeData
536 MTFTP4_PROTOCOL
*Instance
;
539 if ((This
== NULL
) || (ModeData
== NULL
)) {
540 return EFI_INVALID_PARAMETER
;
543 OldTpl
= gBS
->RaiseTPL (TPL_CALLBACK
);
545 Instance
= MTFTP4_PROTOCOL_FROM_THIS (This
);
546 CopyMem(&ModeData
->ConfigData
, &Instance
->Config
, sizeof (Instance
->Config
));
547 ModeData
->SupportedOptionCount
= MTFTP4_SUPPORTED_OPTIONS
;
548 ModeData
->SupportedOptoins
= (UINT8
**) mMtftp4SupportedOptions
;
549 ModeData
->UnsupportedOptionCount
= 0;
550 ModeData
->UnsupportedOptoins
= NULL
;
552 gBS
->RestoreTPL (OldTpl
);
560 Initializes, changes, or resets the default operational setting for this
561 EFI MTFTPv4 Protocol driver instance.
563 The Configure() function is used to set and change the configuration data for
564 this EFI MTFTPv4 Protocol driver instance. The configuration data can be reset
565 to startup defaults by calling Configure() with MtftpConfigData set to NULL.
566 Whenever the instance is reset, any pending operation is aborted. By changing
567 the EFI MTFTPv4 Protocol driver instance configuration data, the client can
568 connect to different MTFTPv4 servers. The configuration parameters in
569 MtftpConfigData are used as the default parameters in later MTFTPv4 operations
570 and can be overridden in later operations.
572 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
573 @param ConfigData MtftpConfigDataPointer to the configuration data
576 @retval EFI_SUCCESS The EFI MTFTPv4 Protocol driver was configured
578 @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:
580 2.MtftpConfigData.UseDefaultSetting is FALSE and
581 MtftpConfigData.StationIp is not a valid IPv4
583 3.MtftpCofigData.UseDefaultSetting is FALSE and
584 MtftpConfigData.SubnetMask is invalid.
585 4.MtftpCofigData.ServerIp is not a valid IPv4
587 5.MtftpConfigData.UseDefaultSetting is FALSE and
588 MtftpConfigData.GatewayIp is not a valid IPv4
589 unicast address or is not in the same subnet
590 with station address.
591 @retval EFI_ACCESS_DENIED The EFI configuration could not be changed at this
592 time because there is one MTFTP background operation
594 @retval EFI_NO_MAPPING When using a default address, configuration
595 (DHCP, BOOTP, RARP, etc.) has not finished yet.
596 @retval EFI_UNSUPPORTED A configuration protocol (DHCP, BOOTP, RARP, etc.)
597 could not be located when clients choose to use
598 the default address settings.
599 @retval EFI_OUT_OF_RESOURCES The EFI MTFTPv4 Protocol driver instance data could
601 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
602 The EFI MTFTPv4 Protocol driver instance is not
609 IN EFI_MTFTP4_PROTOCOL
*This
,
610 IN EFI_MTFTP4_CONFIG_DATA
*ConfigData
613 MTFTP4_PROTOCOL
*Instance
;
621 return EFI_INVALID_PARAMETER
;
624 Instance
= MTFTP4_PROTOCOL_FROM_THIS (This
);
626 if (ConfigData
== NULL
) {
628 // Reset the operation if ConfigData is NULL
630 OldTpl
= gBS
->RaiseTPL (TPL_CALLBACK
);
632 Mtftp4CleanOperation (Instance
, EFI_ABORTED
);
633 ZeroMem (&Instance
->Config
, sizeof (EFI_MTFTP4_CONFIG_DATA
));
634 Instance
->State
= MTFTP4_STATE_UNCONFIGED
;
636 gBS
->RestoreTPL (OldTpl
);
640 // Configure the parameters for new operation.
642 CopyMem (&Ip
, &ConfigData
->StationIp
, sizeof (IP4_ADDR
));
643 CopyMem (&Netmask
, &ConfigData
->SubnetMask
, sizeof (IP4_ADDR
));
644 CopyMem (&Gateway
, &ConfigData
->GatewayIp
, sizeof (IP4_ADDR
));
645 CopyMem (&ServerIp
, &ConfigData
->ServerIp
, sizeof (IP4_ADDR
));
648 Netmask
= NTOHL (Netmask
);
649 Gateway
= NTOHL (Gateway
);
650 ServerIp
= NTOHL (ServerIp
);
652 if (!Ip4IsUnicast (ServerIp
, 0)) {
653 return EFI_INVALID_PARAMETER
;
656 if (!ConfigData
->UseDefaultSetting
&&
657 ((!IP4_IS_VALID_NETMASK (Netmask
) || !Ip4IsUnicast (Ip
, Netmask
)))) {
659 return EFI_INVALID_PARAMETER
;
662 if ((Gateway
!= 0) &&
663 (!IP4_NET_EQUAL (Gateway
, Ip
, Netmask
) || !Ip4IsUnicast (Gateway
, Netmask
))) {
665 return EFI_INVALID_PARAMETER
;
668 OldTpl
= gBS
->RaiseTPL (TPL_CALLBACK
);
670 if ((Instance
->State
== MTFTP4_STATE_CONFIGED
) && (Instance
->Operation
!= 0)) {
671 gBS
->RestoreTPL (OldTpl
);
672 return EFI_ACCESS_DENIED
;
675 CopyMem(&Instance
->Config
, ConfigData
, sizeof (*ConfigData
));;
676 Instance
->State
= MTFTP4_STATE_CONFIGED
;
678 gBS
->RestoreTPL (OldTpl
);
687 Parses the options in an MTFTPv4 OACK packet.
689 The ParseOptions() function parses the option fields in an MTFTPv4 OACK packet
690 and returns the number of options that were found and optionally a list of
691 pointers to the options in the packet.
692 If one or more of the option fields are not valid, then EFI_PROTOCOL_ERROR is
693 returned and *OptionCount and *OptionList stop at the last valid option.
694 The OptionList is allocated by this function, and caller should free it when used.
696 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
697 @param PacketLen Length of the OACK packet to be parsed.
698 @param Packet Pointer to the OACK packet to be parsed.
699 @param OptionCount Pointer to the number of options in following OptionList.
700 @param OptionList Pointer to EFI_MTFTP4_OPTION storage. Call the
701 EFI Boot Service FreePool() to release theOptionList
702 if the options in this OptionList are not needed
705 @retval EFI_SUCCESS The OACK packet was valid and the OptionCount and
706 OptionList parameters have been updated.
707 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
709 2.Packet is NULL or Packet is not a valid MTFTPv4 packet.
710 3.OptionCount is NULL.
711 @retval EFI_NOT_FOUND No options were found in the OACK packet.
712 @retval EFI_OUT_OF_RESOURCES Storage for the OptionList array cannot be allocated.
713 @retval EFI_PROTOCOL_ERROR One or more of the option fields is invalid.
718 EfiMtftp4ParseOptions (
719 IN EFI_MTFTP4_PROTOCOL
*This
,
721 IN EFI_MTFTP4_PACKET
*Packet
,
722 OUT UINT32
*OptionCount
,
723 OUT EFI_MTFTP4_OPTION
**OptionList OPTIONAL
728 if ((This
== NULL
) || (PacketLen
< MTFTP4_OPCODE_LEN
) ||
729 (Packet
== NULL
) || (OptionCount
== NULL
)) {
731 return EFI_INVALID_PARAMETER
;
734 Status
= Mtftp4ExtractOptions (Packet
, PacketLen
, OptionCount
, OptionList
);
736 if (EFI_ERROR (Status
)) {
740 if (*OptionCount
== 0) {
741 return EFI_NOT_FOUND
;
749 Downloads a file from an MTFTPv4 server.
751 The ReadFile() function is used to initialize and start an MTFTPv4 download
752 process and optionally wait for completion. When the download operation completes,
753 whether successfully or not, the Token.Status field is updated by the EFI MTFTPv4
754 Protocol driver and then Token.Event is signaled (if it is not NULL).
755 Data can be downloaded from the MTFTPv4 server into either of the following locations:
756 1.A fixed buffer that is pointed to by Token.Buffer
757 2.A download service function that is pointed to by Token.CheckPacket
758 If both Token.Buffer and Token.CheckPacket are used, then Token.CheckPacket
759 will be called first. If the call is successful, the packet will be stored in
762 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
763 @param Token Pointer to the token structure to provide the
764 parameters that are used in this operation.
766 @retval EFI_SUCCESS The data file has been transferred successfully.
767 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
768 @retval EFI_BUFFER_TOO_SMALL BufferSize is not large enough to hold the downloaded
769 data in downloading process.
770 @retval EFI_ABORTED Current operation is aborted by user.
771 @retval EFI_ICMP_ERROR An ICMP ERROR packet was received.
772 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
773 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received.
774 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
780 IN EFI_MTFTP4_PROTOCOL
*This
,
781 IN EFI_MTFTP4_TOKEN
*Token
784 return Mtftp4Start (This
, Token
, EFI_MTFTP4_OPCODE_RRQ
);
789 Sends a data file to an MTFTPv4 server. May be unsupported in some EFI implementations
791 The WriteFile() function is used to initialize an uploading operation with the
792 given option list and optionally wait for completion. If one or more of the
793 options is not supported by the server, the unsupported options are ignored and
794 a standard TFTP process starts instead. When the upload process completes,
795 whether successfully or not, Token.Event is signaled, and the EFI MTFTPv4 Protocol
796 driver updates Token.Status.
797 The caller can supply the data to be uploaded in the following two modes:
798 1.Through the user-provided buffer
799 2.Through a callback function
800 With the user-provided buffer, the Token.BufferSize field indicates the length
801 of the buffer, and the driver will upload the data in the buffer. With an
802 EFI_MTFTP4_PACKET_NEEDED callback function, the driver will call this callback
803 function to get more data from the user to upload. See the definition of
804 EFI_MTFTP4_PACKET_NEEDED for more information. These two modes cannot be used at
805 the same time. The callback function will be ignored if the user provides the buffer.
807 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
808 @param Token Pointer to the token structure to provide the
809 parameters that are used in this function
811 @retval EFI_SUCCESS The upload session has started.
812 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
813 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
816 3. Token.Filename is NULL.
817 4. Token.OptionCount is not zero and
818 Token.OptionList is NULL.
819 5. One or more options in Token.OptionList have wrong
821 6. Token.Buffer and Token.PacketNeeded are both
823 7. One or more IPv4 addresses in Token.OverrideData
824 are not valid unicast IPv4 addresses if
825 Token.OverrideData is not NULL.
826 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in the
827 unsupported list of structure EFI_MTFTP4_MODE_DATA.
828 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
829 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
830 BOOTP, RARP, etc.) is not finished yet.
831 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4
833 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
834 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
835 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
841 IN EFI_MTFTP4_PROTOCOL
*This
,
842 IN EFI_MTFTP4_TOKEN
*Token
845 return Mtftp4Start (This
, Token
, EFI_MTFTP4_OPCODE_WRQ
);
850 Downloads a data file "directory" from an MTFTPv4 server.
851 May be unsupported in some EFI implementations
853 The ReadDirectory() function is used to return a list of files on the MTFTPv4
854 server that are logically (or operationally) related to Token.Filename. The
855 directory request packet that is sent to the server is built with the option
856 list that was provided by caller, if present.
857 The file information that the server returns is put into either of the following
859 1.A fixed buffer that is pointed to by Token.Buffer
860 2.A download service function that is pointed to by Token.CheckPacket
861 If both Token.Buffer and Token.CheckPacket are used, then Token.CheckPacket will
862 be called first. If the call is successful, the packet will be stored in Token.Buffer.
863 The returned directory listing in the Token.Buffer or EFI_MTFTP4_PACKET consists
864 of a list of two or three variable-length ASCII strings, each terminated by a
865 null character, for each file in the directory. If the multicast option is involved,
866 the first field of each directory entry is the static multicast IP address and
867 UDP port number that is associated with the file name. The format of the field
868 is ip:ip:ip:ip:port. If the multicast option is not involved, this field and its
869 terminating null character are not present.
870 The next field of each directory entry is the file name and the last field is
871 the file information string. The information string contains the file size and
872 the create/modify timestamp. The format of the information string is filesize
873 yyyy-mm-dd hh:mm:ss:ffff. The timestamp is Coordinated Universal Time
874 (UTC; also known as Greenwich Mean Time [GMT]).
875 The only difference between ReadFile and ReadDirectory is the opcode used.
877 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
878 @param Token Pointer to the token structure to provide the
879 parameters that are used in this function
881 @retval EFI_SUCCESS The MTFTPv4 related file "directory" has been downloaded.
882 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
883 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
886 3. Token.Filename is NULL.
887 4. Token.OptionCount is not zero and
888 Token.OptionList is NULL.
889 5. One or more options in Token.OptionList have wrong
891 6. Token.Buffer and Token.PacketNeeded are both
893 7. One or more IPv4 addresses in Token.OverrideData
894 are not valid unicast IPv4 addresses if
895 Token.OverrideData is not NULL.
896 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in the
897 unsupported list of structure EFI_MTFTP4_MODE_DATA.
898 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
899 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
900 BOOTP, RARP, etc.) is not finished yet.
901 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4
903 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
904 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
905 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
910 EfiMtftp4ReadDirectory (
911 IN EFI_MTFTP4_PROTOCOL
*This
,
912 IN EFI_MTFTP4_TOKEN
*Token
915 return Mtftp4Start (This
, Token
, EFI_MTFTP4_OPCODE_DIR
);
920 Gets information about a file from an MTFTPv4 server.
922 The GetInfo() function assembles an MTFTPv4 request packet with options;
923 sends it to the MTFTPv4 server; and may return an MTFTPv4 OACK, MTFTPv4 ERROR,
924 or ICMP ERROR packet. Retries occur only if no response packets are received
925 from the MTFTPv4 server before the timeout expires.
926 It is implemented with EfiMtftp4ReadFile: build a token, then pass it to
927 EfiMtftp4ReadFile. In its check packet callback abort the opertions.
929 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
930 @param OverrideData Data that is used to override the existing
931 parameters. If NULL, the default parameters that
932 were set in the EFI_MTFTP4_PROTOCOL.Configure()
934 @param Filename Pointer to ASCIIZ file name string
935 @param ModeStr Pointer to ASCIIZ mode string. If NULL, "octet"
937 @param OptionCount Number of option/value string pairs in OptionList
938 @param OptionList Pointer to array of option/value string pairs.
939 Ignored if OptionCount is zero
940 @param PacketLength The number of bytes in the returned packet
941 @param Packet PacketThe pointer to the received packet. This
942 buffer must be freed by the caller.
944 @retval EFI_SUCCESS An MTFTPv4 OACK packet was received and is in
946 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
949 3.OptionCount is not zero and OptionList is NULL.
950 4.One or more options in OptionList have wrong format.
951 5.PacketLength is NULL.
952 6.One or more IPv4 addresses in OverrideData are
953 not valid unicast IPv4 addresses if OverrideData
955 @retval EFI_UNSUPPORTED One or more options in the OptionList are in the
956 unsupported list of structure EFI_MTFTP4_MODE_DATA
957 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
958 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
959 BOOTP, RARP, etc.) has not finished yet.
960 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
961 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
962 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received and is in
964 @retval EFI_ICMP_ERROR An ICMP ERROR packet was received and the Packet
966 @retval EFI_PROTOCOL_ERROR An unexpected MTFTPv4 packet was received and is
968 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
969 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
975 IN EFI_MTFTP4_PROTOCOL
*This
,
976 IN EFI_MTFTP4_OVERRIDE_DATA
*OverrideData OPTIONAL
,
978 IN UINT8
*ModeStr OPTIONAL
,
979 IN UINT8 OptionCount
,
980 IN EFI_MTFTP4_OPTION
*OptionList OPTIONAL
,
981 OUT UINT32
*PacketLength
,
982 OUT EFI_MTFTP4_PACKET
**Packet OPTIONAL
985 EFI_MTFTP4_TOKEN Token
;
986 MTFTP4_PROTOCOL
*Instance
;
987 MTFTP4_GETINFO_STATE
*State
;
990 if ((This
== NULL
) || (Filename
== NULL
) || (PacketLength
== NULL
) ||
991 ((OptionCount
!= 0) && (OptionList
== NULL
))) {
992 return EFI_INVALID_PARAMETER
;
995 if (Packet
!= NULL
) {
1000 Instance
= MTFTP4_PROTOCOL_FROM_THIS (This
);
1001 State
= &Instance
->GetInfoState
;
1002 State
->Packet
= Packet
;
1003 State
->PacketLen
= PacketLength
;
1004 State
->Status
= EFI_SUCCESS
;
1007 // Fill in the Token to issue an synchronous ReadFile operation
1009 Token
.Status
= EFI_SUCCESS
;
1011 Token
.OverrideData
= OverrideData
;
1012 Token
.Filename
= Filename
;
1013 Token
.ModeStr
= ModeStr
;
1014 Token
.OptionCount
= OptionCount
;
1015 Token
.OptionList
= OptionList
;
1016 Token
.BufferSize
= 0;
1017 Token
.Buffer
= NULL
;
1018 Token
.CheckPacket
= Mtftp4GetInfoCheckPacket
;
1019 Token
.TimeoutCallback
= NULL
;
1020 Token
.PacketNeeded
= NULL
;
1022 Status
= EfiMtftp4ReadFile (This
, &Token
);
1024 if (EFI_ABORTED
== Status
) {
1025 return State
->Status
;
1032 Polls for incoming data packets and processes outgoing data packets.
1034 The Poll() function can be used by network drivers and applications to increase
1035 the rate that data packets are moved between the communications device and the
1036 transmit and receive queues.
1037 In some systems, the periodic timer event in the managed network driver may not
1038 poll the underlying communications device fast enough to transmit and/or receive
1039 all data packets without missing incoming packets or dropping outgoing packets.
1040 Drivers and applications that are experiencing packet loss should try calling
1041 the Poll() function more often.
1043 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
1045 @retval EFI_SUCCESS Incoming or outgoing data was processed.
1046 @retval EFI_NOT_STARTED This EFI MTFTPv4 Protocol instance has not been started.
1047 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
1048 BOOTP, RARP, etc.) is not finished yet.
1049 @retval EFI_INVALID_PARAMETER This is NULL.
1050 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
1051 @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive
1052 queue. Consider increasing the polling rate.
1058 IN EFI_MTFTP4_PROTOCOL
*This
1061 MTFTP4_PROTOCOL
*Instance
;
1062 EFI_UDP4_PROTOCOL
*Udp
;
1065 return EFI_INVALID_PARAMETER
;
1068 Instance
= MTFTP4_PROTOCOL_FROM_THIS (This
);
1070 if (Instance
->State
== MTFTP4_STATE_UNCONFIGED
) {
1071 return EFI_NOT_STARTED
;
1072 } else if (Instance
->State
== MTFTP4_STATE_DESTORY
) {
1073 return EFI_DEVICE_ERROR
;
1076 Udp
= Instance
->UnicastPort
->Udp
;
1077 return Udp
->Poll (Udp
);
1080 EFI_MTFTP4_PROTOCOL gMtftp4ProtocolTemplate
= {
1081 EfiMtftp4GetModeData
,
1084 EfiMtftp4ParseOptions
,
1087 EfiMtftp4ReadDirectory
,