2 Interface routine for Mtftp4.
4 Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR>
5 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 UdpIoCleanIo (Instance
->UnicastPort
);
55 if (Instance
->LastPacket
!= NULL
) {
56 NetbufFree (Instance
->LastPacket
);
57 Instance
->LastPacket
= NULL
;
60 if (Instance
->McastUdpPort
!= NULL
) {
61 UdpIoFreeIo (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
);
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.
107 Mtftp4GetInfoCheckPacket (
108 IN EFI_MTFTP4_PROTOCOL
*This
,
109 IN EFI_MTFTP4_TOKEN
*Token
,
111 IN EFI_MTFTP4_PACKET
*Packet
114 MTFTP4_GETINFO_STATE
*State
;
118 State
= (MTFTP4_GETINFO_STATE
*) Token
->Context
;
119 OpCode
= NTOHS (Packet
->OpCode
);
122 // Set the GetInfo's return status according to the OpCode.
125 case EFI_MTFTP4_OPCODE_ERROR
:
126 State
->Status
= EFI_TFTP_ERROR
;
129 case EFI_MTFTP4_OPCODE_OACK
:
130 State
->Status
= EFI_SUCCESS
;
134 State
->Status
= EFI_PROTOCOL_ERROR
;
138 // Allocate buffer then copy the packet over. Use gBS->AllocatePool
139 // in case AllocatePool will implements something tricky.
141 Status
= gBS
->AllocatePool (EfiBootServicesData
, PacketLen
, (VOID
**) State
->Packet
);
143 if (EFI_ERROR (Status
)) {
144 State
->Status
= EFI_OUT_OF_RESOURCES
;
148 *(State
->PacketLen
) = PacketLen
;
149 CopyMem (*(State
->Packet
), Packet
, PacketLen
);
156 Check whether the override data is valid.
158 It will first validate whether the server is a valid unicast. If a gateway
159 is provided in the Override, it also check that it is a unicast on the
162 @param Instance The MTFTP instance
163 @param Override The override data to validate.
165 @retval TRUE The override data is valid
166 @retval FALSE The override data is invalid
170 Mtftp4OverrideValid (
171 IN MTFTP4_PROTOCOL
*Instance
,
172 IN EFI_MTFTP4_OVERRIDE_DATA
*Override
175 EFI_MTFTP4_CONFIG_DATA
*Config
;
180 CopyMem (&Ip
, &Override
->ServerIp
, sizeof (IP4_ADDR
));
181 if (!NetIp4IsUnicast (NTOHL (Ip
), 0)) {
185 Config
= &Instance
->Config
;
187 CopyMem (&Gateway
, &Override
->GatewayIp
, sizeof (IP4_ADDR
));
188 Gateway
= NTOHL (Gateway
);
190 if (!Config
->UseDefaultSetting
&& (Gateway
!= 0)) {
191 CopyMem (&Netmask
, &Config
->SubnetMask
, sizeof (IP4_ADDR
));
192 CopyMem (&Ip
, &Config
->StationIp
, sizeof (IP4_ADDR
));
194 Netmask
= NTOHL (Netmask
);
197 if (!NetIp4IsUnicast (Gateway
, Netmask
) || !IP4_NET_EQUAL (Gateway
, Ip
, Netmask
)) {
207 Poll the UDP to get the IP4 default address, which may be retrieved
210 The default time out value is 5 seconds. If IP has retrieved the default address,
211 the UDP is reconfigured.
213 @param Instance The Mtftp instance
214 @param UdpIo The UDP_IO to poll
215 @param UdpCfgData The UDP configure data to reconfigure the UDP_IO
217 @retval TRUE The default address is retrieved and UDP is reconfigured.
218 @retval FALSE Some error occured.
223 IN MTFTP4_PROTOCOL
*Instance
,
225 IN EFI_UDP4_CONFIG_DATA
*UdpCfgData
228 MTFTP4_SERVICE
*Service
;
229 EFI_IP4_MODE_DATA Ip4Mode
;
230 EFI_UDP4_PROTOCOL
*Udp
;
233 ASSERT (Instance
->Config
.UseDefaultSetting
);
235 Service
= Instance
->Service
;
236 Udp
= UdpIo
->Protocol
.Udp4
;
238 Status
= gBS
->SetTimer (
239 Service
->TimerToGetMap
,
241 MTFTP4_TIME_TO_GETMAP
* TICKS_PER_SECOND
243 if (EFI_ERROR (Status
)) {
247 while (!EFI_ERROR (gBS
->CheckEvent (Service
->TimerToGetMap
))) {
250 if (!EFI_ERROR (Udp
->GetModeData (Udp
, NULL
, &Ip4Mode
, NULL
, NULL
)) &&
251 Ip4Mode
.IsConfigured
) {
253 Udp
->Configure (Udp
, NULL
);
254 return (BOOLEAN
) (Udp
->Configure (Udp
, UdpCfgData
) == EFI_SUCCESS
);
263 Configure the UDP port for unicast receiving.
265 @param UdpIo The UDP_IO instance
266 @param Instance The MTFTP session
268 @retval EFI_SUCCESS The UDP port is successfully configured for the
269 session to unicast receive.
273 Mtftp4ConfigUnicastPort (
275 IN MTFTP4_PROTOCOL
*Instance
278 EFI_MTFTP4_CONFIG_DATA
*Config
;
279 EFI_UDP4_CONFIG_DATA UdpConfig
;
283 Config
= &Instance
->Config
;
285 UdpConfig
.AcceptBroadcast
= FALSE
;
286 UdpConfig
.AcceptPromiscuous
= FALSE
;
287 UdpConfig
.AcceptAnyPort
= FALSE
;
288 UdpConfig
.AllowDuplicatePort
= FALSE
;
289 UdpConfig
.TypeOfService
= 0;
290 UdpConfig
.TimeToLive
= 64;
291 UdpConfig
.DoNotFragment
= FALSE
;
292 UdpConfig
.ReceiveTimeout
= 0;
293 UdpConfig
.TransmitTimeout
= 0;
294 UdpConfig
.UseDefaultAddress
= Config
->UseDefaultSetting
;
295 UdpConfig
.StationAddress
= Config
->StationIp
;
296 UdpConfig
.SubnetMask
= Config
->SubnetMask
;
297 UdpConfig
.StationPort
= 0;
298 UdpConfig
.RemotePort
= 0;
300 Ip
= HTONL (Instance
->ServerIp
);
301 CopyMem (&UdpConfig
.RemoteAddress
, &Ip
, sizeof (EFI_IPv4_ADDRESS
));
303 Status
= UdpIo
->Protocol
.Udp4
->Configure (UdpIo
->Protocol
.Udp4
, &UdpConfig
);
305 if ((Status
== EFI_NO_MAPPING
) && Mtftp4GetMapping (Instance
, UdpIo
, &UdpConfig
)) {
309 if (!Config
->UseDefaultSetting
&& !EFI_IP4_EQUAL (&mZeroIp4Addr
, &Config
->GatewayIp
)) {
311 // The station IP address is manually configured and the Gateway IP is not 0.
312 // Add the default route for this UDP instance.
314 Status
= UdpIo
->Protocol
.Udp4
->Routes (
315 UdpIo
->Protocol
.Udp4
,
321 if (EFI_ERROR (Status
)) {
322 UdpIo
->Protocol
.Udp4
->Configure (UdpIo
->Protocol
.Udp4
, NULL
);
330 Start the MTFTP session to do the operation, such as read file,
331 write file, and read directory.
333 @param This The MTFTP session
334 @param Token The token than encapsues the user's request.
335 @param Operation The operation to do
337 @retval EFI_INVALID_PARAMETER Some of the parameters are invalid.
338 @retval EFI_NOT_STARTED The MTFTP session hasn't been configured.
339 @retval EFI_ALREADY_STARTED There is pending operation for the session.
340 @retval EFI_SUCCESS The operation is successfully started.
345 IN EFI_MTFTP4_PROTOCOL
*This
,
346 IN EFI_MTFTP4_TOKEN
*Token
,
350 MTFTP4_PROTOCOL
*Instance
;
351 EFI_MTFTP4_OVERRIDE_DATA
*Override
;
352 EFI_MTFTP4_CONFIG_DATA
*Config
;
357 // Validate the parameters
359 if ((This
== NULL
) || (Token
== NULL
) || (Token
->Filename
== NULL
) ||
360 ((Token
->OptionCount
!= 0) && (Token
->OptionList
== NULL
))) {
361 return EFI_INVALID_PARAMETER
;
365 // User must provide at least one method to collect the data for download.
367 if (((Operation
== EFI_MTFTP4_OPCODE_RRQ
) || (Operation
== EFI_MTFTP4_OPCODE_DIR
)) &&
368 ((Token
->Buffer
== NULL
) && (Token
->CheckPacket
== NULL
))) {
369 return EFI_INVALID_PARAMETER
;
373 // User must provide at least one method to provide the data for upload.
375 if ((Operation
== EFI_MTFTP4_OPCODE_WRQ
) &&
376 ((Token
->Buffer
== NULL
) && (Token
->PacketNeeded
== NULL
))) {
377 return EFI_INVALID_PARAMETER
;
380 Instance
= MTFTP4_PROTOCOL_FROM_THIS (This
);
382 Status
= EFI_SUCCESS
;
383 OldTpl
= gBS
->RaiseTPL (TPL_CALLBACK
);
385 if (Instance
->State
!= MTFTP4_STATE_CONFIGED
) {
386 Status
= EFI_NOT_STARTED
;
389 if (Instance
->Operation
!= 0) {
390 Status
= EFI_ACCESS_DENIED
;
393 if (EFI_ERROR (Status
)) {
394 gBS
->RestoreTPL (OldTpl
);
399 // Set the Operation now to prevent the application start other
402 Instance
->Operation
= Operation
;
403 Override
= Token
->OverrideData
;
405 if ((Override
!= NULL
) && !Mtftp4OverrideValid (Instance
, Override
)) {
406 Status
= EFI_INVALID_PARAMETER
;
410 if (Token
->OptionCount
!= 0) {
411 Status
= Mtftp4ParseOption (
415 &Instance
->RequestOption
418 if (EFI_ERROR (Status
)) {
424 // Set the operation parameters from the configuration or override data.
426 Config
= &Instance
->Config
;
427 Instance
->Token
= Token
;
428 Instance
->BlkSize
= MTFTP4_DEFAULT_BLKSIZE
;
430 CopyMem (&Instance
->ServerIp
, &Config
->ServerIp
, sizeof (IP4_ADDR
));
431 Instance
->ServerIp
= NTOHL (Instance
->ServerIp
);
433 Instance
->ListeningPort
= Config
->InitialServerPort
;
434 Instance
->ConnectedPort
= 0;
436 CopyMem (&Instance
->Gateway
, &Config
->GatewayIp
, sizeof (IP4_ADDR
));
437 Instance
->Gateway
= NTOHL (Instance
->Gateway
);
439 Instance
->MaxRetry
= Config
->TryCount
;
440 Instance
->Timeout
= Config
->TimeoutValue
;
441 Instance
->Master
= TRUE
;
443 if (Override
!= NULL
) {
444 CopyMem (&Instance
->ServerIp
, &Override
->ServerIp
, sizeof (IP4_ADDR
));
445 CopyMem (&Instance
->Gateway
, &Override
->GatewayIp
, sizeof (IP4_ADDR
));
447 Instance
->ServerIp
= NTOHL (Instance
->ServerIp
);
448 Instance
->Gateway
= NTOHL (Instance
->Gateway
);
450 Instance
->ListeningPort
= Override
->ServerPort
;
451 Instance
->MaxRetry
= Override
->TryCount
;
452 Instance
->Timeout
= Override
->TimeoutValue
;
455 if (Instance
->ListeningPort
== 0) {
456 Instance
->ListeningPort
= MTFTP4_DEFAULT_SERVER_PORT
;
459 if (Instance
->MaxRetry
== 0) {
460 Instance
->MaxRetry
= MTFTP4_DEFAULT_RETRY
;
463 if (Instance
->Timeout
== 0) {
464 Instance
->Timeout
= MTFTP4_DEFAULT_TIMEOUT
;
468 // Config the unicast UDP child to send initial request
470 Status
= Mtftp4ConfigUnicastPort (Instance
->UnicastPort
, Instance
);
472 if (EFI_ERROR (Status
)) {
477 // Set initial status.
479 Token
->Status
= EFI_NOT_READY
;
482 // Build and send an initial requests
484 if (Operation
== EFI_MTFTP4_OPCODE_WRQ
) {
485 Status
= Mtftp4WrqStart (Instance
, Operation
);
487 Status
= Mtftp4RrqStart (Instance
, Operation
);
490 gBS
->RestoreTPL (OldTpl
);
492 if (EFI_ERROR (Status
)) {
496 if (Token
->Event
!= NULL
) {
501 // Return immediately for asynchronous operation or poll the
502 // instance for synchronous operation.
504 while (Token
->Status
== EFI_NOT_READY
) {
508 return Token
->Status
;
511 Mtftp4CleanOperation (Instance
, Status
);
512 gBS
->RestoreTPL (OldTpl
);
519 Reads the current operational settings.
521 The GetModeData()function reads the current operational settings of this
522 EFI MTFTPv4 Protocol driver instance.
524 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
525 @param ModeData Pointer to storage for the EFI MTFTPv4 Protocol
528 @retval EFI_SUCCESS The configuration data was successfully returned.
529 @retval EFI_OUT_OF_RESOURCES The required mode data could not be allocated.
530 @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
535 EfiMtftp4GetModeData (
536 IN EFI_MTFTP4_PROTOCOL
*This
,
537 OUT EFI_MTFTP4_MODE_DATA
*ModeData
540 MTFTP4_PROTOCOL
*Instance
;
543 if ((This
== NULL
) || (ModeData
== NULL
)) {
544 return EFI_INVALID_PARAMETER
;
547 OldTpl
= gBS
->RaiseTPL (TPL_CALLBACK
);
549 Instance
= MTFTP4_PROTOCOL_FROM_THIS (This
);
550 CopyMem(&ModeData
->ConfigData
, &Instance
->Config
, sizeof (Instance
->Config
));
551 ModeData
->SupportedOptionCount
= MTFTP4_SUPPORTED_OPTIONS
;
552 ModeData
->SupportedOptoins
= (UINT8
**) mMtftp4SupportedOptions
;
553 ModeData
->UnsupportedOptionCount
= 0;
554 ModeData
->UnsupportedOptoins
= NULL
;
556 gBS
->RestoreTPL (OldTpl
);
564 Initializes, changes, or resets the default operational setting for this
565 EFI MTFTPv4 Protocol driver instance.
567 The Configure() function is used to set and change the configuration data for
568 this EFI MTFTPv4 Protocol driver instance. The configuration data can be reset
569 to startup defaults by calling Configure() with MtftpConfigData set to NULL.
570 Whenever the instance is reset, any pending operation is aborted. By changing
571 the EFI MTFTPv4 Protocol driver instance configuration data, the client can
572 connect to different MTFTPv4 servers. The configuration parameters in
573 MtftpConfigData are used as the default parameters in later MTFTPv4 operations
574 and can be overridden in later operations.
576 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
577 @param ConfigData MtftpConfigDataPointer to the configuration data
580 @retval EFI_SUCCESS The EFI MTFTPv4 Protocol driver was configured
582 @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:
584 2.MtftpConfigData.UseDefaultSetting is FALSE and
585 MtftpConfigData.StationIp is not a valid IPv4
587 3.MtftpCofigData.UseDefaultSetting is FALSE and
588 MtftpConfigData.SubnetMask is invalid.
589 4.MtftpCofigData.ServerIp is not a valid IPv4
591 5.MtftpConfigData.UseDefaultSetting is FALSE and
592 MtftpConfigData.GatewayIp is not a valid IPv4
593 unicast address or is not in the same subnet
594 with station address.
595 @retval EFI_ACCESS_DENIED The EFI configuration could not be changed at this
596 time because there is one MTFTP background operation
598 @retval EFI_NO_MAPPING When using a default address, configuration
599 (DHCP, BOOTP, RARP, etc.) has not finished yet.
600 @retval EFI_UNSUPPORTED A configuration protocol (DHCP, BOOTP, RARP, etc.)
601 could not be located when clients choose to use
602 the default address settings.
603 @retval EFI_OUT_OF_RESOURCES The EFI MTFTPv4 Protocol driver instance data could
605 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
606 The EFI MTFTPv4 Protocol driver instance is not
613 IN EFI_MTFTP4_PROTOCOL
*This
,
614 IN EFI_MTFTP4_CONFIG_DATA
*ConfigData
617 MTFTP4_PROTOCOL
*Instance
;
625 return EFI_INVALID_PARAMETER
;
628 Instance
= MTFTP4_PROTOCOL_FROM_THIS (This
);
630 if (ConfigData
== NULL
) {
632 // Reset the operation if ConfigData is NULL
634 OldTpl
= gBS
->RaiseTPL (TPL_CALLBACK
);
636 Mtftp4CleanOperation (Instance
, EFI_ABORTED
);
637 ZeroMem (&Instance
->Config
, sizeof (EFI_MTFTP4_CONFIG_DATA
));
638 Instance
->State
= MTFTP4_STATE_UNCONFIGED
;
640 gBS
->RestoreTPL (OldTpl
);
644 // Configure the parameters for new operation.
646 CopyMem (&Ip
, &ConfigData
->StationIp
, sizeof (IP4_ADDR
));
647 CopyMem (&Netmask
, &ConfigData
->SubnetMask
, sizeof (IP4_ADDR
));
648 CopyMem (&Gateway
, &ConfigData
->GatewayIp
, sizeof (IP4_ADDR
));
649 CopyMem (&ServerIp
, &ConfigData
->ServerIp
, sizeof (IP4_ADDR
));
652 Netmask
= NTOHL (Netmask
);
653 Gateway
= NTOHL (Gateway
);
654 ServerIp
= NTOHL (ServerIp
);
656 if (!NetIp4IsUnicast (ServerIp
, 0)) {
657 return EFI_INVALID_PARAMETER
;
660 if (!ConfigData
->UseDefaultSetting
&&
661 ((!IP4_IS_VALID_NETMASK (Netmask
) || !NetIp4IsUnicast (Ip
, Netmask
)))) {
663 return EFI_INVALID_PARAMETER
;
666 if ((Gateway
!= 0) &&
667 (!IP4_NET_EQUAL (Gateway
, Ip
, Netmask
) || !NetIp4IsUnicast (Gateway
, Netmask
))) {
669 return EFI_INVALID_PARAMETER
;
672 OldTpl
= gBS
->RaiseTPL (TPL_CALLBACK
);
674 if ((Instance
->State
== MTFTP4_STATE_CONFIGED
) && (Instance
->Operation
!= 0)) {
675 gBS
->RestoreTPL (OldTpl
);
676 return EFI_ACCESS_DENIED
;
679 CopyMem(&Instance
->Config
, ConfigData
, sizeof (*ConfigData
));;
680 Instance
->State
= MTFTP4_STATE_CONFIGED
;
682 gBS
->RestoreTPL (OldTpl
);
691 Parses the options in an MTFTPv4 OACK packet.
693 The ParseOptions() function parses the option fields in an MTFTPv4 OACK packet
694 and returns the number of options that were found and optionally a list of
695 pointers to the options in the packet.
696 If one or more of the option fields are not valid, then EFI_PROTOCOL_ERROR is
697 returned and *OptionCount and *OptionList stop at the last valid option.
698 The OptionList is allocated by this function, and caller should free it when used.
700 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
701 @param PacketLen Length of the OACK packet to be parsed.
702 @param Packet Pointer to the OACK packet to be parsed.
703 @param OptionCount Pointer to the number of options in following OptionList.
704 @param OptionList Pointer to EFI_MTFTP4_OPTION storage. Call the
705 EFI Boot Service FreePool() to release theOptionList
706 if the options in this OptionList are not needed
709 @retval EFI_SUCCESS The OACK packet was valid and the OptionCount and
710 OptionList parameters have been updated.
711 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
713 2.Packet is NULL or Packet is not a valid MTFTPv4 packet.
714 3.OptionCount is NULL.
715 @retval EFI_NOT_FOUND No options were found in the OACK packet.
716 @retval EFI_OUT_OF_RESOURCES Storage for the OptionList array cannot be allocated.
717 @retval EFI_PROTOCOL_ERROR One or more of the option fields is invalid.
722 EfiMtftp4ParseOptions (
723 IN EFI_MTFTP4_PROTOCOL
*This
,
725 IN EFI_MTFTP4_PACKET
*Packet
,
726 OUT UINT32
*OptionCount
,
727 OUT EFI_MTFTP4_OPTION
**OptionList OPTIONAL
732 if ((This
== NULL
) || (PacketLen
< MTFTP4_OPCODE_LEN
) ||
733 (Packet
== NULL
) || (OptionCount
== NULL
)) {
735 return EFI_INVALID_PARAMETER
;
738 Status
= Mtftp4ExtractOptions (Packet
, PacketLen
, OptionCount
, OptionList
);
740 if (EFI_ERROR (Status
)) {
744 if (*OptionCount
== 0) {
745 return EFI_NOT_FOUND
;
753 Downloads a file from an MTFTPv4 server.
755 The ReadFile() function is used to initialize and start an MTFTPv4 download
756 process and optionally wait for completion. When the download operation completes,
757 whether successfully or not, the Token.Status field is updated by the EFI MTFTPv4
758 Protocol driver and then Token.Event is signaled (if it is not NULL).
759 Data can be downloaded from the MTFTPv4 server into either of the following locations:
760 1.A fixed buffer that is pointed to by Token.Buffer
761 2.A download service function that is pointed to by Token.CheckPacket
762 If both Token.Buffer and Token.CheckPacket are used, then Token.CheckPacket
763 will be called first. If the call is successful, the packet will be stored in
766 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
767 @param Token Pointer to the token structure to provide the
768 parameters that are used in this operation.
770 @retval EFI_SUCCESS The data file has been transferred successfully.
771 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
772 @retval EFI_BUFFER_TOO_SMALL BufferSize is not large enough to hold the downloaded
773 data in downloading process.
774 @retval EFI_ABORTED Current operation is aborted by user.
775 @retval EFI_ICMP_ERROR An ICMP ERROR packet was received.
776 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
777 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received.
778 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
779 @retval EFI_NO_MEDIA There was a media error.
785 IN EFI_MTFTP4_PROTOCOL
*This
,
786 IN EFI_MTFTP4_TOKEN
*Token
789 return Mtftp4Start (This
, Token
, EFI_MTFTP4_OPCODE_RRQ
);
794 Sends a data file to an MTFTPv4 server. May be unsupported in some EFI implementations
796 The WriteFile() function is used to initialize an uploading operation with the
797 given option list and optionally wait for completion. If one or more of the
798 options is not supported by the server, the unsupported options are ignored and
799 a standard TFTP process starts instead. When the upload process completes,
800 whether successfully or not, Token.Event is signaled, and the EFI MTFTPv4 Protocol
801 driver updates Token.Status.
802 The caller can supply the data to be uploaded in the following two modes:
803 1.Through the user-provided buffer
804 2.Through a callback function
805 With the user-provided buffer, the Token.BufferSize field indicates the length
806 of the buffer, and the driver will upload the data in the buffer. With an
807 EFI_MTFTP4_PACKET_NEEDED callback function, the driver will call this callback
808 function to get more data from the user to upload. See the definition of
809 EFI_MTFTP4_PACKET_NEEDED for more information. These two modes cannot be used at
810 the same time. The callback function will be ignored if the user provides the buffer.
812 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
813 @param Token Pointer to the token structure to provide the
814 parameters that are used in this function
816 @retval EFI_SUCCESS The upload session has started.
817 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
818 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
821 3. Token.Filename is NULL.
822 4. Token.OptionCount is not zero and
823 Token.OptionList is NULL.
824 5. One or more options in Token.OptionList have wrong
826 6. Token.Buffer and Token.PacketNeeded are both
828 7. One or more IPv4 addresses in Token.OverrideData
829 are not valid unicast IPv4 addresses if
830 Token.OverrideData is not NULL.
831 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in the
832 unsupported list of structure EFI_MTFTP4_MODE_DATA.
833 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
834 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
835 BOOTP, RARP, etc.) is not finished yet.
836 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4
838 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
839 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
840 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
846 IN EFI_MTFTP4_PROTOCOL
*This
,
847 IN EFI_MTFTP4_TOKEN
*Token
850 return Mtftp4Start (This
, Token
, EFI_MTFTP4_OPCODE_WRQ
);
855 Downloads a data file "directory" from an MTFTPv4 server.
856 May be unsupported in some EFI implementations
858 The ReadDirectory() function is used to return a list of files on the MTFTPv4
859 server that are logically (or operationally) related to Token.Filename. The
860 directory request packet that is sent to the server is built with the option
861 list that was provided by caller, if present.
862 The file information that the server returns is put into either of the following
864 1.A fixed buffer that is pointed to by Token.Buffer
865 2.A download service function that is pointed to by Token.CheckPacket
866 If both Token.Buffer and Token.CheckPacket are used, then Token.CheckPacket will
867 be called first. If the call is successful, the packet will be stored in Token.Buffer.
868 The returned directory listing in the Token.Buffer or EFI_MTFTP4_PACKET consists
869 of a list of two or three variable-length ASCII strings, each terminated by a
870 null character, for each file in the directory. If the multicast option is involved,
871 the first field of each directory entry is the static multicast IP address and
872 UDP port number that is associated with the file name. The format of the field
873 is ip:ip:ip:ip:port. If the multicast option is not involved, this field and its
874 terminating null character are not present.
875 The next field of each directory entry is the file name and the last field is
876 the file information string. The information string contains the file size and
877 the create/modify timestamp. The format of the information string is filesize
878 yyyy-mm-dd hh:mm:ss:ffff. The timestamp is Coordinated Universal Time
879 (UTC; also known as Greenwich Mean Time [GMT]).
880 The only difference between ReadFile and ReadDirectory is the opcode used.
882 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
883 @param Token Pointer to the token structure to provide the
884 parameters that are used in this function
886 @retval EFI_SUCCESS The MTFTPv4 related file "directory" has been downloaded.
887 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
888 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
891 3. Token.Filename is NULL.
892 4. Token.OptionCount is not zero and
893 Token.OptionList is NULL.
894 5. One or more options in Token.OptionList have wrong
896 6. Token.Buffer and Token.PacketNeeded are both
898 7. One or more IPv4 addresses in Token.OverrideData
899 are not valid unicast IPv4 addresses if
900 Token.OverrideData is not NULL.
901 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in the
902 unsupported list of structure EFI_MTFTP4_MODE_DATA.
903 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
904 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
905 BOOTP, RARP, etc.) is not finished yet.
906 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4
908 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
909 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
910 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
915 EfiMtftp4ReadDirectory (
916 IN EFI_MTFTP4_PROTOCOL
*This
,
917 IN EFI_MTFTP4_TOKEN
*Token
920 return Mtftp4Start (This
, Token
, EFI_MTFTP4_OPCODE_DIR
);
925 Gets information about a file from an MTFTPv4 server.
927 The GetInfo() function assembles an MTFTPv4 request packet with options;
928 sends it to the MTFTPv4 server; and may return an MTFTPv4 OACK, MTFTPv4 ERROR,
929 or ICMP ERROR packet. Retries occur only if no response packets are received
930 from the MTFTPv4 server before the timeout expires.
931 It is implemented with EfiMtftp4ReadFile: build a token, then pass it to
932 EfiMtftp4ReadFile. In its check packet callback abort the opertions.
934 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
935 @param OverrideData Data that is used to override the existing
936 parameters. If NULL, the default parameters that
937 were set in the EFI_MTFTP4_PROTOCOL.Configure()
939 @param Filename Pointer to null-terminated ASCII file name string
940 @param ModeStr Pointer to null-terminated ASCII mode string. If NULL, "octet"
942 @param OptionCount Number of option/value string pairs in OptionList
943 @param OptionList Pointer to array of option/value string pairs.
944 Ignored if OptionCount is zero
945 @param PacketLength The number of bytes in the returned packet
946 @param Packet PacketThe pointer to the received packet. This
947 buffer must be freed by the caller.
949 @retval EFI_SUCCESS An MTFTPv4 OACK packet was received and is in
951 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
954 3.OptionCount is not zero and OptionList is NULL.
955 4.One or more options in OptionList have wrong format.
956 5.PacketLength is NULL.
957 6.One or more IPv4 addresses in OverrideData are
958 not valid unicast IPv4 addresses if OverrideData
960 @retval EFI_UNSUPPORTED One or more options in the OptionList are in the
961 unsupported list of structure EFI_MTFTP4_MODE_DATA
962 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
963 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
964 BOOTP, RARP, etc.) has not finished yet.
965 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
966 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
967 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received and is in
969 @retval EFI_ICMP_ERROR An ICMP ERROR packet was received and the Packet
971 @retval EFI_PROTOCOL_ERROR An unexpected MTFTPv4 packet was received and is
973 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
974 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
975 @retval EFI_NO_MEDIA There was a media error.
981 IN EFI_MTFTP4_PROTOCOL
*This
,
982 IN EFI_MTFTP4_OVERRIDE_DATA
*OverrideData OPTIONAL
,
984 IN UINT8
*ModeStr OPTIONAL
,
985 IN UINT8 OptionCount
,
986 IN EFI_MTFTP4_OPTION
*OptionList OPTIONAL
,
987 OUT UINT32
*PacketLength
,
988 OUT EFI_MTFTP4_PACKET
**Packet OPTIONAL
991 EFI_MTFTP4_TOKEN Token
;
992 MTFTP4_GETINFO_STATE State
;
995 if ((This
== NULL
) || (Filename
== NULL
) || (PacketLength
== NULL
) ||
996 ((OptionCount
!= 0) && (OptionList
== NULL
))) {
997 return EFI_INVALID_PARAMETER
;
1000 if (Packet
!= NULL
) {
1005 State
.Packet
= Packet
;
1006 State
.PacketLen
= PacketLength
;
1007 State
.Status
= EFI_SUCCESS
;
1010 // Fill in the Token to issue an synchronous ReadFile operation
1012 Token
.Status
= EFI_SUCCESS
;
1014 Token
.OverrideData
= OverrideData
;
1015 Token
.Filename
= Filename
;
1016 Token
.ModeStr
= ModeStr
;
1017 Token
.OptionCount
= OptionCount
;
1018 Token
.OptionList
= OptionList
;
1019 Token
.BufferSize
= 0;
1020 Token
.Buffer
= NULL
;
1021 Token
.Context
= &State
;
1022 Token
.CheckPacket
= Mtftp4GetInfoCheckPacket
;
1023 Token
.TimeoutCallback
= NULL
;
1024 Token
.PacketNeeded
= NULL
;
1026 Status
= EfiMtftp4ReadFile (This
, &Token
);
1028 if (EFI_ABORTED
== Status
) {
1029 return State
.Status
;
1036 Polls for incoming data packets and processes outgoing data packets.
1038 The Poll() function can be used by network drivers and applications to increase
1039 the rate that data packets are moved between the communications device and the
1040 transmit and receive queues.
1041 In some systems, the periodic timer event in the managed network driver may not
1042 poll the underlying communications device fast enough to transmit and/or receive
1043 all data packets without missing incoming packets or dropping outgoing packets.
1044 Drivers and applications that are experiencing packet loss should try calling
1045 the Poll() function more often.
1047 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
1049 @retval EFI_SUCCESS Incoming or outgoing data was processed.
1050 @retval EFI_NOT_STARTED This EFI MTFTPv4 Protocol instance has not been started.
1051 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
1052 BOOTP, RARP, etc.) is not finished yet.
1053 @retval EFI_INVALID_PARAMETER This is NULL.
1054 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
1055 @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive
1056 queue. Consider increasing the polling rate.
1062 IN EFI_MTFTP4_PROTOCOL
*This
1065 MTFTP4_PROTOCOL
*Instance
;
1066 EFI_UDP4_PROTOCOL
*Udp
;
1069 return EFI_INVALID_PARAMETER
;
1072 Instance
= MTFTP4_PROTOCOL_FROM_THIS (This
);
1074 if (Instance
->State
== MTFTP4_STATE_UNCONFIGED
) {
1075 return EFI_NOT_STARTED
;
1076 } else if (Instance
->State
== MTFTP4_STATE_DESTROY
) {
1077 return EFI_DEVICE_ERROR
;
1080 Udp
= Instance
->UnicastPort
->Protocol
.Udp4
;
1081 return Udp
->Poll (Udp
);
1084 EFI_MTFTP4_PROTOCOL gMtftp4ProtocolTemplate
= {
1085 EfiMtftp4GetModeData
,
1088 EfiMtftp4ParseOptions
,
1091 EfiMtftp4ReadDirectory
,