NetworkPkg/DnsDxe/DnsImpl.h

   1 /** @file
   2 DnsDxe support functions implementation.
   3
   4 Copyright (c) 2015, 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
   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 **/
  14
  15 #ifndef __EFI_DNS_IMPL_H_
  16 #define __EFI_DNS_IMPL_H_
  17
  18 #include <Uefi.h>
  19
  20 //
  21 // Libraries classes
  22 //
  23 #include <Library/BaseLib.h>
  24 #include <Library/UefiLib.h>
  25 #include <Library/UefiBootServicesTableLib.h>
  26 #include <Library/UefiDriverEntryPoint.h>
  27 #include <Library/UefiRuntimeServicesTableLib.h>
  28 #include <Library/BaseMemoryLib.h>
  29 #include <Library/MemoryAllocationLib.h>
  30 #include <Library/NetLib.h>
  31 #include <Library/DebugLib.h>
  32 #include <Library/DpcLib.h>
  33 #include <Library/PrintLib.h>
  34 #include <Library/UdpIoLib.h>
  35
  36 //
  37 // UEFI Driver Model Protocols
  38 //
  39 #include <Protocol/DriverBinding.h>
  40 #include <Protocol/ComponentName2.h>
  41 #include <Protocol/ComponentName.h>
  42
  43 #include <Protocol/Udp4.h>
  44 #include <Protocol/Dhcp4.h>
  45 #include <Protocol/Dns4.h>
  46
  47 #include <Protocol/Udp6.h>
  48 #include <Protocol/Dhcp6.h>
  49 #include <Protocol/Dns6.h>
  50
  51 #include <Protocol/Ip4Config2.h>
  52
  53 #include "DnsDriver.h"
  54 #include "DnsDhcp.h"
  55
  56 //
  57 // Driver Version
  58 //
  59 #define DNS_VERSION  0x00000000
  60
  61 //
  62 // Protocol instances
  63 //
  64 extern EFI_COMPONENT_NAME_PROTOCOL   gDnsComponentName;
  65 extern EFI_COMPONENT_NAME2_PROTOCOL  gDnsComponentName2;
  66 extern EFI_UNICODE_STRING_TABLE      *gDnsControllerNameTable;
  67
  68 extern EFI_DRIVER_BINDING_PROTOCOL   gDns4DriverBinding;
  69 extern EFI_SERVICE_BINDING_PROTOCOL  mDns4ServiceBinding;
  70 extern EFI_DNS4_PROTOCOL             mDns4Protocol;
  71
  72 extern EFI_DRIVER_BINDING_PROTOCOL   gDns6DriverBinding;
  73 extern EFI_SERVICE_BINDING_PROTOCOL  mDns6ServiceBinding;
  74 extern EFI_DNS6_PROTOCOL             mDns6Protocol;
  75
  76 //
  77 // DNS related
  78 //
  79 #define DNS_SERVER_PORT   53
  80
  81 #define DNS_PROTOCOL_UDP   EFI_IP_PROTO_UDP
  82 #define DNS_PROTOCOL_TCP   EFI_IP_PROTO_TCP
  83
  84 #define DNS_STATE_UNCONFIGED     0
  85 #define DNS_STATE_CONFIGED       1
  86 #define DNS_STATE_DESTROY        2
  87
  88 #define DNS_DEFAULT_TIMEOUT      2
  89 #define DNS_DEFAULT_RETRY        3
  90 #define DNS_DEFAULT_BLKSIZE      512
  91
  92 #define DNS_TIME_TO_GETMAP       5
  93
  94 #pragma pack(1)
  95
  96 typedef union _DNS_FLAGS  DNS_FLAGS;
  97
  98 typedef struct {
  99   LIST_ENTRY             AllCacheLink;
 100   EFI_DNS4_CACHE_ENTRY   DnsCache;
 101 } DNS4_CACHE;
 102
 103 typedef struct {
 104   LIST_ENTRY             AllCacheLink;
 105   EFI_DNS6_CACHE_ENTRY   DnsCache;
 106 } DNS6_CACHE;
 107
 108 typedef struct {
 109   LIST_ENTRY             AllServerLink;
 110   EFI_IPv4_ADDRESS       Dns4ServerIp;
 111 } DNS4_SERVER_IP;
 112
 113 typedef struct {
 114   LIST_ENTRY             AllServerLink;
 115   EFI_IPv6_ADDRESS       Dns6ServerIp;
 116 } DNS6_SERVER_IP;
 117
 118 typedef struct {
 119   UINT32                     PacketToLive;
 120   CHAR16                     *QueryHostName;
 121   EFI_IPv4_ADDRESS           QueryIpAddress;
 122   BOOLEAN                    GeneralLookUp;
 123   EFI_DNS4_COMPLETION_TOKEN  *Token;
 124 } DNS4_TOKEN_ENTRY;
 125
 126 typedef struct {
 127   UINT32                     PacketToLive;
 128   CHAR16                     *QueryHostName;
 129   EFI_IPv6_ADDRESS           QueryIpAddress;
 130   BOOLEAN                    GeneralLookUp;
 131   EFI_DNS6_COMPLETION_TOKEN  *Token;
 132 } DNS6_TOKEN_ENTRY;
 133
 134 union _DNS_FLAGS{
 135   struct {
 136     UINT16     RCode:4;
 137     UINT16     Zero:3;
 138     UINT16     RA:1;
 139     UINT16     RD:1;
 140     UINT16     TC:1;
 141     UINT16     AA:1;
 142     UINT16     OpCode:4;
 143     UINT16     QR:1;
 144   } Bits;
 145   UINT16  Uint16;
 146 };
 147
 148 #define DNS_FLAGS_QR_QUERY     0
 149 #define DNS_FLAGS_QR_RESPONSE  1
 150
 151 #define DNS_FLAGS_OPCODE_STANDARD     0
 152 #define DNS_FLAGS_OPCODE_INVERSE      1
 153 #define DNS_FLAGS_OPCODE_SERVER_STATE 2
 154
 155 #define DNS_FLAGS_RCODE_NO_ERROR    0
 156 #define DNS_FLAGS_RCODE_NAME_ERROR  3
 157
 158 typedef struct {
 159   UINT16      Identification;
 160   DNS_FLAGS   Flags;
 161   UINT16      QuestionsNum;
 162   UINT16      AnswersNum;
 163   UINT16      AuthorityNum;
 164   UINT16      AditionalNum;
 165 } DNS_HEADER;
 166
 167 typedef struct {
 168   UINT16      Type;
 169   UINT16      Class;
 170 } DNS_QUERY_SECTION;
 171
 172 typedef struct {
 173   UINT16      Type;
 174   UINT16      Class;
 175   UINT32      Ttl;
 176   UINT16      DataLength;
 177 } DNS_ANSWER_SECTION;
 178
 179 #define DNS_TYPE_A      1
 180 #define DNS_TYPE_NS     2
 181 #define DNS_TYPE_CNAME  5
 182 #define DNS_TYPE_PTR    12
 183 #define DNS_TYPE_HINFO  13
 184 #define DNS_TYPE_MX     15
 185 #define DNS_TYPE_AAAA   28
 186 #define DNS_TYPE_SRV_RR 33
 187 #define DNS_TYPE_AXFR   252
 188 #define DNS_TYPE_ANY    255
 189
 190 #define DNS_CLASS_INET  1
 191
 192 #define DNS4_DOMAIN  L"in-addr.arpa"
 193 #define DNS6_DOMAIN  L"IP6.ARPA"
 194
 195
 196 #pragma pack()
 197
 198 /**
 199   Remove TokenEntry from TokenMap.
 200
 201   @param[in] TokenMap          All DNSv4 Token entrys.
 202   @param[in] TokenEntry        TokenEntry need to be removed.
 203
 204   @retval EFI_SUCCESS          Remove TokenEntry from TokenMap sucessfully.
 205   @retval EFI_NOT_FOUND        TokenEntry is not found in TokenMap.
 206
 207 **/
 208 EFI_STATUS
 209 Dns4RemoveTokenEntry (
 210   IN NET_MAP                    *TokenMap,
 211   IN DNS4_TOKEN_ENTRY           *TokenEntry
 212   );
 213
 214 /**
 215   Remove TokenEntry from TokenMap.
 216
 217   @param[in] TokenMap           All DNSv6 Token entrys.
 218   @param[in] TokenEntry         TokenEntry need to be removed.
 219
 220   @retval EFI_SUCCESS           Remove TokenEntry from TokenMap sucessfully.
 221   @retval EFI_NOT_FOUND         TokenEntry is not found in TokenMap.
 222
 223 **/
 224 EFI_STATUS
 225 Dns6RemoveTokenEntry (
 226   IN NET_MAP                    *TokenMap,
 227   IN DNS6_TOKEN_ENTRY           *TokenEntry
 228   );
 229
 230 /**
 231   This function cancle the token specified by Arg in the Map.
 232
 233   @param[in]  Map             Pointer to the NET_MAP.
 234   @param[in]  Item            Pointer to the NET_MAP_ITEM.
 235   @param[in]  Arg             Pointer to the token to be cancelled. If NULL, all
 236                               the tokens in this Map will be cancelled.
 237                               This parameter is optional and may be NULL.
 238
 239   @retval EFI_SUCCESS         The token is cancelled if Arg is NULL, or the token
 240                               is not the same as that in the Item, if Arg is not
 241                               NULL.
 242   @retval EFI_ABORTED         Arg is not NULL, and the token specified by Arg is
 243                               cancelled.
 244
 245 **/
 246 EFI_STATUS
 247 EFIAPI
 248 Dns4CancelTokens (
 249   IN NET_MAP       *Map,
 250   IN NET_MAP_ITEM  *Item,
 251   IN VOID          *Arg OPTIONAL
 252   );
 253
 254 /**
 255   This function cancle the token specified by Arg in the Map.
 256
 257   @param[in]  Map             Pointer to the NET_MAP.
 258   @param[in]  Item            Pointer to the NET_MAP_ITEM.
 259   @param[in]  Arg             Pointer to the token to be cancelled. If NULL, all
 260                               the tokens in this Map will be cancelled.
 261                               This parameter is optional and may be NULL.
 262
 263   @retval EFI_SUCCESS         The token is cancelled if Arg is NULL, or the token
 264                               is not the same as that in the Item, if Arg is not
 265                               NULL.
 266   @retval EFI_ABORTED         Arg is not NULL, and the token specified by Arg is
 267                               cancelled.
 268
 269 **/
 270 EFI_STATUS
 271 EFIAPI
 272 Dns6CancelTokens (
 273   IN NET_MAP       *Map,
 274   IN NET_MAP_ITEM  *Item,
 275   IN VOID          *Arg OPTIONAL
 276   );
 277
 278 /**
 279   Get the TokenEntry from the TokensMap.
 280
 281   @param[in]  TokensMap           All DNSv4 Token entrys
 282   @param[in]  Token               Pointer to the token to be get.
 283   @param[out] TokenEntry          Pointer to TokenEntry corresponding Token.
 284
 285   @retval EFI_SUCCESS             Get the TokenEntry from the TokensMap sucessfully.
 286   @retval EFI_NOT_FOUND           TokenEntry is not found in TokenMap.
 287
 288 **/
 289 EFI_STATUS
 290 EFIAPI
 291 GetDns4TokenEntry (
 292   IN     NET_MAP                   *TokensMap,
 293   IN     EFI_DNS4_COMPLETION_TOKEN *Token,
 294      OUT DNS4_TOKEN_ENTRY          **TokenEntry
 295   );
 296
 297 /**
 298   Get the TokenEntry from the TokensMap.
 299
 300   @param[in]  TokensMap           All DNSv6 Token entrys
 301   @param[in]  Token               Pointer to the token to be get.
 302   @param[out] TokenEntry          Pointer to TokenEntry corresponding Token.
 303
 304   @retval EFI_SUCCESS             Get the TokenEntry from the TokensMap sucessfully.
 305   @retval EFI_NOT_FOUND           TokenEntry is not found in TokenMap.
 306
 307 **/
 308 EFI_STATUS
 309 EFIAPI
 310 GetDns6TokenEntry (
 311   IN     NET_MAP                   *TokensMap,
 312   IN     EFI_DNS6_COMPLETION_TOKEN *Token,
 313      OUT DNS6_TOKEN_ENTRY          **TokenEntry
 314   );
 315
 316 /**
 317   Cancel DNS4 tokens from the DNS4 instance.
 318
 319   @param[in]  Instance           Pointer to the DNS instance context data.
 320   @param[in]  Token              Pointer to the token to be canceled. If NULL, all
 321                                  tokens in this instance will be cancelled.
 322                                  This parameter is optional and may be NULL.
 323
 324   @retval EFI_SUCCESS            The Token is cancelled.
 325   @retval EFI_NOT_FOUND          The Token is not found.
 326
 327 **/
 328 EFI_STATUS
 329 Dns4InstanceCancelToken (
 330   IN DNS_INSTANCE               *Instance,
 331   IN EFI_DNS4_COMPLETION_TOKEN  *Token
 332   );
 333
 334 /**
 335   Cancel DNS6 tokens from the DNS6 instance.
 336
 337   @param[in]  Instance           Pointer to the DNS instance context data.
 338   @param[in]  Token              Pointer to the token to be canceled. If NULL, all
 339                                  tokens in this instance will be cancelled.
 340                                  This parameter is optional and may be NULL.
 341
 342   @retval EFI_SUCCESS            The Token is cancelled.
 343   @retval EFI_NOT_FOUND          The Token is not found.
 344
 345 **/
 346 EFI_STATUS
 347 Dns6InstanceCancelToken (
 348   IN DNS_INSTANCE               *Instance,
 349   IN EFI_DNS6_COMPLETION_TOKEN  *Token
 350   );
 351
 352 /**
 353   Free the resource related to the configure parameters.
 354
 355   @param  Config                 The DNS configure data
 356
 357 **/
 358 VOID
 359 Dns4CleanConfigure (
 360   IN OUT EFI_DNS4_CONFIG_DATA  *Config
 361   );
 362
 363 /**
 364   Free the resource related to the configure parameters.
 365
 366   @param  Config                 The DNS configure data
 367
 368 **/
 369 VOID
 370 Dns6CleanConfigure (
 371   IN OUT EFI_DNS6_CONFIG_DATA  *Config
 372   );
 373
 374 /**
 375   Allocate memory for configure parameter such as timeout value for Dst,
 376   then copy the configure parameter from Src to Dst.
 377
 378   @param[out]  Dst               The destination DHCP configure data.
 379   @param[in]   Src               The source DHCP configure data.
 380
 381   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
 382   @retval EFI_SUCCESS            The configure is copied.
 383
 384 **/
 385 EFI_STATUS
 386 Dns4CopyConfigure (
 387   OUT EFI_DNS4_CONFIG_DATA  *Dst,
 388   IN  EFI_DNS4_CONFIG_DATA  *Src
 389   );
 390
 391 /**
 392   Allocate memory for configure parameter such as timeout value for Dst,
 393   then copy the configure parameter from Src to Dst.
 394
 395   @param[out]  Dst               The destination DHCP configure data.
 396   @param[in]   Src               The source DHCP configure data.
 397
 398   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
 399   @retval EFI_SUCCESS            The configure is copied.
 400
 401 **/
 402 EFI_STATUS
 403 Dns6CopyConfigure (
 404   OUT EFI_DNS6_CONFIG_DATA  *Dst,
 405   IN  EFI_DNS6_CONFIG_DATA  *Src
 406   );
 407
 408 /**
 409   Callback of Dns packet. Does nothing.
 410
 411   @param Arg           The context.
 412
 413 **/
 414 VOID
 415 EFIAPI
 416 DnsDummyExtFree (
 417   IN VOID                   *Arg
 418   );
 419
 420 /**
 421   Poll the UDP to get the IP4 default address, which may be retrieved
 422   by DHCP.
 423
 424   The default time out value is 5 seconds. If IP has retrieved the default address,
 425   the UDP is reconfigured.
 426
 427   @param  Instance               The DNS instance
 428   @param  UdpIo                  The UDP_IO to poll
 429   @param  UdpCfgData             The UDP configure data to reconfigure the UDP_IO
 430
 431   @retval TRUE                   The default address is retrieved and UDP is reconfigured.
 432   @retval FALSE                  Some error occured.
 433
 434 **/
 435 BOOLEAN
 436 Dns4GetMapping (
 437   IN DNS_INSTANCE           *Instance,
 438   IN UDP_IO                 *UdpIo,
 439   IN EFI_UDP4_CONFIG_DATA   *UdpCfgData
 440   );
 441
 442 /**
 443   Configure the opened Udp6 instance until the corresponding Ip6 instance
 444   has been configured.
 445
 446   @param  Instance               The DNS instance
 447   @param  UdpIo                  The UDP_IO to poll
 448   @param  UdpCfgData             The UDP configure data to reconfigure the UDP_IO
 449
 450   @retval TRUE                   Configure the Udp6 instance successfully.
 451   @retval FALSE                  Some error occured.
 452
 453 **/
 454 BOOLEAN
 455 Dns6GetMapping (
 456   IN DNS_INSTANCE           *Instance,
 457   IN UDP_IO                 *UdpIo,
 458   IN EFI_UDP6_CONFIG_DATA   *UdpCfgData
 459   );
 460
 461 /**
 462   Configure the UDP.
 463
 464   @param  Instance               The DNS session
 465   @param  UdpIo                  The UDP_IO instance
 466
 467   @retval EFI_SUCCESS            The UDP is successfully configured for the
 468                                  session.
 469
 470 **/
 471 EFI_STATUS
 472 Dns4ConfigUdp (
 473   IN DNS_INSTANCE           *Instance,
 474   IN UDP_IO                 *UdpIo
 475   );
 476
 477 /**
 478   Configure the UDP.
 479
 480   @param  Instance               The DNS session
 481   @param  UdpIo                  The UDP_IO instance
 482
 483   @retval EFI_SUCCESS            The UDP is successfully configured for the
 484                                  session.
 485
 486 **/
 487 EFI_STATUS
 488 Dns6ConfigUdp (
 489   IN DNS_INSTANCE           *Instance,
 490   IN UDP_IO                 *UdpIo
 491   );
 492
 493 /**
 494   Update Dns4 cache to shared list of caches of all DNSv4 instances.
 495
 496   @param  Dns4CacheList      All Dns4 cache list.
 497   @param  DeleteFlag         If FALSE, this function is to add one entry to the DNS Cache.
 498                              If TRUE, this function will delete matching DNS Cache entry.
 499   @param  Override           If TRUE, the matching DNS cache entry will be overwritten with the supplied parameter.
 500                              If FALSE, EFI_ACCESS_DENIED will be returned if the entry to be added is already exists.
 501   @param  DnsCacheEntry      Entry Pointer to DNS Cache entry.
 502
 503   @retval EFI_SUCCESS        Update Dns4 cache successfully.
 504   @retval Others             Failed to update Dns4 cache.
 505
 506 **/
 507 EFI_STATUS
 508 EFIAPI
 509 UpdateDns4Cache (
 510   IN LIST_ENTRY             *Dns4CacheList,
 511   IN BOOLEAN                DeleteFlag,
 512   IN BOOLEAN                Override,
 513   IN EFI_DNS4_CACHE_ENTRY   DnsCacheEntry
 514   );
 515
 516 /**
 517   Update Dns6 cache to shared list of caches of all DNSv6 instances.
 518
 519   @param  Dns6CacheList      All Dns6 cache list.
 520   @param  DeleteFlag         If FALSE, this function is to add one entry to the DNS Cache.
 521                              If TRUE, this function will delete matching DNS Cache entry.
 522   @param  Override           If TRUE, the matching DNS cache entry will be overwritten with the supplied parameter.
 523                              If FALSE, EFI_ACCESS_DENIED will be returned if the entry to be added is already exists.
 524   @param  DnsCacheEntry      Entry Pointer to DNS Cache entry.
 525
 526   @retval EFI_SUCCESS        Update Dns6 cache successfully.
 527   @retval Others             Failed to update Dns6 cache.
 528 **/
 529 EFI_STATUS
 530 EFIAPI
 531 UpdateDns6Cache (
 532   IN LIST_ENTRY             *Dns6CacheList,
 533   IN BOOLEAN                DeleteFlag,
 534   IN BOOLEAN                Override,
 535   IN EFI_DNS6_CACHE_ENTRY   DnsCacheEntry
 536   );
 537
 538 /**
 539   Add Dns4 ServerIp to common list of addresses of all configured DNSv4 server.
 540
 541   @param  Dns4ServerList    Common list of addresses of all configured DNSv4 server.
 542   @param  ServerIp          DNS server Ip.
 543
 544   @retval EFI_SUCCESS       Add Dns4 ServerIp to common list successfully.
 545   @retval Others            Failed to add Dns4 ServerIp to common list.
 546
 547 **/
 548 EFI_STATUS
 549 EFIAPI
 550 AddDns4ServerIp (
 551   IN LIST_ENTRY                *Dns4ServerList,
 552   IN EFI_IPv4_ADDRESS           ServerIp
 553   );
 554
 555 /**
 556   Add Dns6 ServerIp to common list of addresses of all configured DNSv6 server.
 557
 558   @param  Dns6ServerList    Common list of addresses of all configured DNSv6 server.
 559   @param  ServerIp          DNS server Ip.
 560
 561   @retval EFI_SUCCESS       Add Dns6 ServerIp to common list successfully.
 562   @retval Others            Failed to add Dns6 ServerIp to common list.
 563
 564 **/
 565 EFI_STATUS
 566 EFIAPI
 567 AddDns6ServerIp (
 568   IN LIST_ENTRY                *Dns6ServerList,
 569   IN EFI_IPv6_ADDRESS           ServerIp
 570   );
 571
 572 /**
 573   Fill QName for IP querying. QName is a domain name represented as
 574   a sequence of labels, where each label consists of a length octet
 575   followed by that number of octets. The domain name terminates with
 576   the zero length octet for the null label of the root.
 577
 578   @param  HostName          Queried HostName
 579
 580   @retval NULL      Failed to fill QName.
 581   @return           QName filled successfully.
 582
 583 **/
 584 CHAR8 *
 585 EFIAPI
 586 DnsFillinQNameForQueryIp (
 587   IN  CHAR16              *HostName
 588   );
 589
 590 /**
 591   Find out whether the response is valid or invalid.
 592
 593   @param  TokensMap       All DNS transmittal Tokens entry.
 594   @param  Identification  Identification for queried packet.
 595   @param  Type            Type for queried packet.
 596   @param  Item            Return corresponding Token entry.
 597
 598   @retval TRUE            The response is valid.
 599   @retval FALSE           The response is invalid.
 600
 601 **/
 602 BOOLEAN
 603 IsValidDnsResponse (
 604   IN     NET_MAP      *TokensMap,
 605   IN     UINT16       Identification,
 606   IN     UINT16       Type,
 607      OUT NET_MAP_ITEM **Item
 608   );
 609
 610 /**
 611   Parse Dns Response.
 612
 613   @param  Instance              The DNS instance
 614   @param  RxString              Received buffer.
 615   @param  Completed             Flag to indicate that Dns response is valid.
 616
 617   @retval EFI_SUCCESS           Parse Dns Response successfully.
 618   @retval Others                Failed to parse Dns Response.
 619
 620 **/
 621 EFI_STATUS
 622 ParseDnsResponse (
 623   IN OUT DNS_INSTANCE              *Instance,
 624   IN     UINT8                     *RxString,
 625      OUT BOOLEAN                   *Completed
 626   );
 627
 628 /**
 629   Parse response packet.
 630
 631   @param  Packet                The packets received.
 632   @param  EndPoint              The local/remote UDP access point
 633   @param  IoStatus              The status of the UDP receive
 634   @param  Context               The opaque parameter to the function.
 635
 636 **/
 637 VOID
 638 EFIAPI
 639 DnsOnPacketReceived (
 640   NET_BUF                   *Packet,
 641   UDP_END_POINT             *EndPoint,
 642   EFI_STATUS                IoStatus,
 643   VOID                      *Context
 644   );
 645
 646 /**
 647   Release the net buffer when packet is sent.
 648
 649   @param  Packet                The packets received.
 650   @param  EndPoint              The local/remote UDP access point
 651   @param  IoStatus              The status of the UDP receive
 652   @param  Context               The opaque parameter to the function.
 653
 654 **/
 655 VOID
 656 EFIAPI
 657 DnsOnPacketSent (
 658   NET_BUF                   *Packet,
 659   UDP_END_POINT             *EndPoint,
 660   EFI_STATUS                IoStatus,
 661   VOID                      *Context
 662   );
 663
 664 /**
 665   Query request information.
 666
 667   @param  Instance              The DNS instance
 668   @param  Packet                The packet for querying request information.
 669
 670   @retval EFI_SUCCESS           Query request information successfully.
 671   @retval Others                Failed to query request information.
 672
 673 **/
 674 EFI_STATUS
 675 DoDnsQuery (
 676   IN  DNS_INSTANCE              *Instance,
 677   IN  NET_BUF                   *Packet
 678   );
 679
 680 /**
 681   Construct the Packet according query section.
 682
 683   @param  Instance              The DNS instance
 684   @param  QueryName             Queried Name
 685   @param  Type                  Queried Type
 686   @param  Class                 Queried Class
 687   @param  Packet                The packet for query
 688
 689   @retval EFI_SUCCESS           The packet is constructed.
 690   @retval Others                Failed to construct the Packet.
 691
 692 **/
 693 EFI_STATUS
 694 ConstructDNSQuery (
 695   IN  DNS_INSTANCE              *Instance,
 696   IN  CHAR8                     *QueryName,
 697   IN  UINT16                    Type,
 698   IN  UINT16                    Class,
 699   OUT NET_BUF                   **Packet
 700   );
 701
 702 /**
 703   Retransmit the packet.
 704
 705   @param  Instance              The DNS instance
 706   @param  Packet                Retransmit the packet
 707
 708   @retval EFI_SUCCESS           The packet is retransmitted.
 709   @retval Others                Failed to retransmit.
 710
 711 **/
 712 EFI_STATUS
 713 DnsRetransmit (
 714   IN DNS_INSTANCE        *Instance,
 715   IN NET_BUF             *Packet
 716   );
 717
 718 /**
 719   The timer ticking function for the DNS service.
 720
 721   @param  Event                 The ticking event
 722   @param  Context               The DNS service instance
 723
 724 **/
 725 VOID
 726 EFIAPI
 727 DnsOnTimerRetransmit (
 728   IN EFI_EVENT              Event,
 729   IN VOID                   *Context
 730   );
 731
 732 /**
 733   The timer ticking function for the DNS driver.
 734
 735   @param  Event                 The ticking event
 736   @param  Context               NULL
 737
 738 **/
 739 VOID
 740 EFIAPI
 741 DnsOnTimerUpdate (
 742   IN EFI_EVENT              Event,
 743   IN VOID                   *Context
 744   );
 745
 746
 747 /**
 748   This function is used to retrieve DNS mode data for this DNS instance.
 749
 750   @param[in]  This               Pointer to EFI_DNS4_PROTOCOL instance.
 751   @param[out] DnsModeData        Pointer to the caller-allocated storage for the EFI_DNS4_MODE_DATA structure.
 752
 753   @retval  EFI_SUCCESS           The operation completed successfully.
 754   @retval  EFI_NOT_STARTED       When DnsConfigData is queried, no configuration data is
 755                                  available because this instance has not been configured.
 756   @retval  EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.
 757   @retval  EFI_INVALID_PARAMETER This is NULL or DnsModeData is NULL.
 758
 759 **/
 760 EFI_STATUS
 761 EFIAPI
 762 Dns4GetModeData (
 763   IN  EFI_DNS4_PROTOCOL          *This,
 764   OUT EFI_DNS4_MODE_DATA         *DnsModeData
 765   );
 766
 767 /**
 768   This function is used to configure DNS configuration data for this DNS instance.
 769
 770   @param[in]  This               Pointer to EFI_DNS4_PROTOCOL instance.
 771   @param[in]  DnsConfigData      Pointer to caller-allocated buffer containing EFI_DNS4_CONFIG_DATA structure.
 772                                  If NULL, the driver will reinitialize the protocol instance to the unconfigured state.
 773
 774   @retval  EFI_SUCCESS           The operation completed successfully.
 775   @retval  EFI_UNSUPPORTED       The designated protocol is not supported.
 776   @retval  EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.
 777   @retval  EFI_INVALID_PARAMETER This is NULL.
 778                                  The StationIp address provided in DnsConfigData is not a valid unicast.
 779                                  DnsServerList is NULL while DnsServerListCount is not equal to Zero.
 780                                  DnsServerListCount is Zero while DnsServerListCount is not equal to NULL.
 781   @retval  EFI_DEVICE_ERROR      An unexpected system or network error occurred. The EFI DNSv4 Protocol instance is not configured.
 782
 783 **/
 784 EFI_STATUS
 785 EFIAPI
 786 Dns4Configure (
 787   IN EFI_DNS4_PROTOCOL           *This,
 788   IN EFI_DNS4_CONFIG_DATA        *DnsConfigData
 789   );
 790
 791 /**
 792   The function is used to translate the host name to host IP address.
 793   A type A query is used to get the one or more IP addresses for this host.
 794
 795   @param[in]  This               Pointer to EFI_DNS4_PROTOCOL instance.
 796   @param[in]  HostName           Pointer to caller-supplied buffer containing Host name to be translated.
 797                                  This buffer contains 16 bit characters but these are translated to ASCII for use with
 798                                  DNSv4 server and there is no requirement for driver to support non-ASCII Unicode characters.
 799   @param[in]  Token              Pointer to the caller-allocated completion token to return at the completion of the process to translate host name to host address.
 800
 801   @retval  EFI_SUCCESS           The operation completed successfully.
 802   @retval  EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.
 803   @retval  EFI_INVALID_PARAMETER This is NULL.
 804                                  Token is NULL.
 805                                  Token.Event is.NULL
 806                                  HostName is NULL
 807   @retval  EFI_NO_MAPPING        There's no source address is available for use.
 808   @retval  EFI_NOT_STARTED       This instance has not been started.
 809
 810 **/
 811 EFI_STATUS
 812 EFIAPI
 813 Dns4HostNameToIp (
 814   IN  EFI_DNS4_PROTOCOL          *This,
 815   IN  CHAR16                    *HostName,
 816   IN  EFI_DNS4_COMPLETION_TOKEN  *Token
 817   );
 818
 819 /**
 820   The function is used to translate the host address to host name.
 821   A type PTR query is used to get the primary name of the host.
 822
 823   @param[in]  This               Pointer to EFI_DNS4_PROTOCOL instance.
 824   @param[in]  IpAddress          IP address.
 825   @param[in]  Token              Pointer to the caller-allocated completion used token to translate host address to host name.
 826
 827   @retval  EFI_SUCCESS           The operation completed successfully.
 828   @retval  EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.
 829   @retval  EFI_INVALID_PARAMETER This is NULL.
 830                                  Token is NULL.
 831                                  Token.Event is NULL.
 832                                  IpAddress is not valid IP address.
 833   @retval  EFI_NO_MAPPING        There's no source address is available for use.
 834   @retval  EFI_NOT_STARTED       This instance has not been started.
 835   @retval  EFI_UNSUPPORTED       This function is not supported.
 836
 837 **/
 838 EFI_STATUS
 839 EFIAPI
 840 Dns4IpToHostName (
 841   IN  EFI_DNS4_PROTOCOL             *This,
 842   IN  EFI_IPv4_ADDRESS              IpAddress,
 843   IN  EFI_DNS4_COMPLETION_TOKEN     *Token
 844   );
 845
 846 /**
 847   This function retrieves arbitrary information from the DNS.
 848   The caller supplies a QNAME, QTYPE, and QCLASS, and all of the matching RRs are returned.
 849   All RR content (e.g., Ttl) was returned.
 850   The caller need parse the returned RR to get required information. This function is optional.
 851
 852   @param[in]  This               Pointer to EFI_DNS4_PROTOCOL instance.
 853   @param[in]  QName              Pointer to Query Name.
 854   @param[in]  QType              Query Type.
 855   @param[in]  QClass             Query Name.
 856   @param[in]  Token              Point to the caller-allocated completion token to retrieve arbitrary information.
 857
 858   @retval  EFI_SUCCESS           The operation completed successfully.
 859   @retval  EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.
 860   @retval  EFI_INVALID_PARAMETER This is NULL.
 861                                  Token is NULL.
 862                                  Token.Event is NULL.
 863                                  QName is NULL.
 864   @retval  EFI_NO_MAPPING        There's no source address is available for use.
 865   @retval  EFI_ALREADY_STARTED   This Token is being used in another DNS session.
 866   @retval  EFI_UNSUPPORTED       This function is not supported. Or the requested QType is not supported
 867
 868 **/
 869 EFI_STATUS
 870 EFIAPI
 871 Dns4GeneralLookUp (
 872   IN  EFI_DNS4_PROTOCOL                *This,
 873   IN  CHAR8                            *QName,
 874   IN  UINT16                           QType,
 875   IN  UINT16                           QClass,
 876   IN  EFI_DNS4_COMPLETION_TOKEN        *Token
 877   );
 878
 879 /**
 880   This function is used to add/delete/modify DNS cache entry.
 881   DNS cache can be normally dynamically updated after the DNS resolve succeeds.
 882   This function provided capability to manually add/delete/modify the DNS cache.
 883
 884   @param[in]  This               Pointer to EFI_DNS4_PROTOCOL instance.
 885   @param[in]  DeleteFlag         If FALSE, this function is to add one entry to the DNS Cache.
 886                                  If TRUE, this function will delete matching DNS Cache entry.
 887   @param[in]  Override           If TRUE, the matching DNS cache entry will be overwritten with the supplied parameter.
 888                                  If FALSE, EFI_ACCESS_DENIED will be returned if the entry to be added is already exists.
 889   @param[in]  DnsCacheEntry      Pointer to DNS Cache entry.
 890
 891   @retval  EFI_SUCCESS           The operation completed successfully.
 892   @retval  EFI_INVALID_PARAMETER This is NULL.
 893                                  DnsCacheEntry.HostName is NULL.
 894                                  DnsCacheEntry.IpAddress is NULL.
 895                                  DnsCacheEntry.Timeout is zero.
 896   @retval  EFI_ACCESS_DENIED     The DNS cache entry already exists and Override is not TRUE.
 897
 898 **/
 899 EFI_STATUS
 900 EFIAPI
 901 Dns4UpdateDnsCache (
 902   IN EFI_DNS4_PROTOCOL      *This,
 903   IN BOOLEAN               DeleteFlag,
 904   IN BOOLEAN               Override,
 905   IN EFI_DNS4_CACHE_ENTRY   DnsCacheEntry
 906   );
 907
 908 /**
 909   This function can be used by network drivers and applications to increase the rate that data packets are moved between
 910   the communications device and the transmit and receive queues. In some systems, the periodic timer event in the managed
 911   network driver may not poll the underlying communications device fast enough to transmit and/or receive all data packets
 912   without missing incoming packets or dropping outgoing packets.
 913
 914   @param[in]  This               Pointer to EFI_DNS4_PROTOCOL instance.
 915
 916   @retval  EFI_SUCCESS           Incoming or outgoing data was processed.
 917   @retval  EFI_INVALID_PARAMETER This is NULL.
 918   @retval  EFI_NOT_STARTED       This EFI DNS Protocol instance has not been started.
 919   @retval  EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 920   @retval  EFI_TIMEOUT           Data was dropped out of the transmit and/or receive queue.
 921                                  Consider increasing the polling rate.
 922
 923 **/
 924 EFI_STATUS
 925 EFIAPI
 926 Dns4Poll (
 927   IN EFI_DNS4_PROTOCOL    *This
 928   );
 929
 930 /**
 931   This function is used to abort a pending resolution request.
 932   After calling this function, Token.Status will be set to EFI_ABORTED and then Token.
 933
 934   @param[in]  This               Pointer to EFI_DNS4_PROTOCOL instance.
 935   @param[in]  Token              Pointer to a token that has been issued by EFI_DNS4_PROTOCOL.HostNameToIp(),
 936                                  EFI_DNS4_PROTOCOL.IpToHostName() or EFI_DNS4_PROTOCOL.GeneralLookup().
 937                                  If NULL, all pending tokens are aborted.
 938
 939   @retval  EFI_SUCCESS           Incoming or outgoing data was processed.
 940   @retval  EFI_INVALID_PARAMETER This is NULL.
 941   @retval  EFI_NOT_STARTED       This EFI DNS Protocol instance has not been started.
 942   @retval  EFI_NOT_FOUND         When Token is not NULL, and the asynchronous DNS operation was not found in the transmit queue.
 943                                  It was either completed or was not issued by HostNameToIp(), IpToHostName() or GeneralLookup().
 944
 945 **/
 946 EFI_STATUS
 947 EFIAPI
 948 Dns4Cancel (
 949   IN  EFI_DNS4_PROTOCOL          *This,
 950   IN  EFI_DNS4_COMPLETION_TOKEN  *Token
 951   );
 952
 953
 954 /**
 955   This function is used to retrieve DNS mode data for this DNS instance.
 956
 957   @param[in]  This               Pointer to EFI_DNS6_PROTOCOL instance.
 958   @param[out] DnsModeData        Pointer to the caller-allocated storage for the EFI_DNS6_MODE_DATA structure.
 959
 960   @retval  EFI_SUCCESS           The operation completed successfully.
 961   @retval  EFI_NOT_STARTED       When DnsConfigData is queried, no configuration data is
 962                                  available because this instance has not been configured.
 963   @retval  EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.
 964   @retval  EFI_INVALID_PARAMETER This is NULL or DnsModeData is NULL.
 965
 966 **/
 967 EFI_STATUS
 968 EFIAPI
 969 Dns6GetModeData (
 970   IN  EFI_DNS6_PROTOCOL          *This,
 971   OUT EFI_DNS6_MODE_DATA         *DnsModeData
 972   );
 973
 974 /**
 975   The function is used to set and change the configuration data for this EFI DNSv6 Protocol driver instance.
 976   Reset the DNS instance if DnsConfigData is NULL.
 977
 978   @param[in]  This               Pointer to EFI_DNS6_PROTOCOL instance.
 979   @param[in]  DnsConfigData      Pointer to the configuration data structure.
 980                                  All associated storage to be allocated and released by caller.
 981
 982   @retval  EFI_SUCCESS           The operation completed successfully.
 983   @retval  EFI_UNSUPPORTED       The designated protocol is not supported.
 984   @retval  EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.
 985   @retval  EFI_INVALID_PARAMETER This is NULL.
 986                                  The StationIp address provided in DnsConfigData is not a valid unicast.
 987                                  DnsServerList is NULL while DnsServerListCount is not equal to Zero.
 988                                  DnsServerListCount is Zero while DnsServerList is not equal to NULL.
 989   @retval  EFI_DEVICE_ERROR      An unexpected system or network error occurred. The EFI DNSv6 Protocol instance is not configured.
 990
 991 **/
 992 EFI_STATUS
 993 EFIAPI
 994 Dns6Configure (
 995   IN EFI_DNS6_PROTOCOL           *This,
 996   IN EFI_DNS6_CONFIG_DATA        *DnsConfigData
 997   );
 998
 999 /**
1000   The function is used to translate the host name to host IP address.
1001   A type AAAA query is used to get the one or more IPv6 addresses for this host.
1002
1003   @param[in]  This               Pointer to EFI_DNS6_PROTOCOL instance.
1004   @param[in]  HostName           Pointer to caller-supplied buffer containing Host name to be translated.
1005                                  This buffer contains 16 bit characters but these are translated to ASCII for use with
1006                                  DNSv4 server and there is no requirement for driver to support non-ASCII Unicode characters.
1007   @param[in]  Token              Pointer to the caller-allocated completion token to return at the completion of the process to translate host name to host address.
1008
1009   @retval  EFI_SUCCESS           The operation completed successfully.
1010   @retval  EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.
1011   @retval  EFI_INVALID_PARAMETER This is NULL.
1012                                  Token is NULL.
1013                                  Token.Event is.NULL
1014                                  HostName is NULL
1015   @retval  EFI_NO_MAPPING        There's no source address is available for use.
1016   @retval  EFI_NOT_STARTED       This instance has not been started.
1017
1018 **/
1019 EFI_STATUS
1020 EFIAPI
1021 Dns6HostNameToIp (
1022   IN  EFI_DNS6_PROTOCOL          *This,
1023   IN  CHAR16                     *HostName,
1024   IN  EFI_DNS6_COMPLETION_TOKEN  *Token
1025   );
1026
1027 /**
1028   The function is used to translate the host address to host name.
1029   A type PTR query is used to get the primary name of the host.
1030
1031   @param[in]  This               Pointer to EFI_DNS6_PROTOCOL instance.
1032   @param[in]  IpAddress          IP address.
1033   @param[in]  Token              Pointer to the caller-allocated completion used token to translate host address to host name.
1034
1035   @retval  EFI_SUCCESS           The operation completed successfully.
1036   @retval  EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.
1037   @retval  EFI_INVALID_PARAMETER This is NULL.
1038                                  Token is NULL.
1039                                  Token.Event is NULL.
1040                                  IpAddress is not valid IP address.
1041   @retval  EFI_NO_MAPPING        There's no source address is available for use.
1042   @retval  EFI_NOT_STARTED       This instance has not been started.
1043   @retval  EFI_UNSUPPORTED       This function is not supported.
1044
1045 **/
1046 EFI_STATUS
1047 EFIAPI
1048 Dns6IpToHostName (
1049   IN  EFI_DNS6_PROTOCOL             *This,
1050   IN  EFI_IPv6_ADDRESS              IpAddress,
1051   IN  EFI_DNS6_COMPLETION_TOKEN     *Token
1052   );
1053
1054 /**
1055   This function retrieves arbitrary information from the DNS.
1056   The caller supplies a QNAME, QTYPE, and QCLASS, and all of the matching RRs are returned.
1057   All RR content (e.g., Ttl) was returned.
1058   The caller need parse the returned RR to get required information. This function is optional.
1059
1060   @param[in]  This               Pointer to EFI_DNS6_PROTOCOL instance.
1061   @param[in]  QName              Pointer to Query Name.
1062   @param[in]  QType              Query Type.
1063   @param[in]  QClass             Query Name.
1064   @param[in]  Token              Point to the caller-allocated completion token to retrieve arbitrary information.
1065
1066   @retval  EFI_SUCCESS           The operation completed successfully.
1067   @retval  EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.
1068   @retval  EFI_INVALID_PARAMETER This is NULL.
1069                                  Token is NULL.
1070                                  Token.Event is NULL.
1071                                  QName is NULL.
1072   @retval  EFI_NO_MAPPING        There's no source address is available for use.
1073   @retval  EFI_NOT_STARTED       This instance has not been started.
1074   @retval  EFI_UNSUPPORTED       This function is not supported. Or the requested QType is not supported
1075
1076 **/
1077 EFI_STATUS
1078 EFIAPI
1079 Dns6GeneralLookUp (
1080   IN  EFI_DNS6_PROTOCOL                *This,
1081   IN  CHAR8                            *QName,
1082   IN  UINT16                           QType,
1083   IN  UINT16                           QClass,
1084   IN  EFI_DNS6_COMPLETION_TOKEN        *Token
1085   );
1086
1087 /**
1088   This function is used to add/delete/modify DNS cache entry.
1089   DNS cache can be normally dynamically updated after the DNS resolve succeeds.
1090   This function provided capability to manually add/delete/modify the DNS cache.
1091
1092   @param[in]  This               Pointer to EFI_DNS6_PROTOCOL instance.
1093   @param[in]  DeleteFlag         If FALSE, this function is to add one entry to the DNS Cache.
1094                                  If TRUE, this function will delete matching DNS Cache entry.
1095   @param[in]  Override           If TRUE, the matching DNS cache entry will be overwritten with the supplied parameter.
1096                                  If FALSE, EFI_ACCESS_DENIED will be returned if the entry to be added is already exists.
1097   @param[in]  DnsCacheEntry      Pointer to DNS Cache entry.
1098
1099   @retval  EFI_SUCCESS           The operation completed successfully.
1100   @retval  EFI_INVALID_PARAMETER This is NULL.
1101                                  DnsCacheEntry.HostName is NULL.
1102                                  DnsCacheEntry.IpAddress is NULL.
1103                                  DnsCacheEntry.Timeout is zero.
1104   @retval  EFI_ACCESS_DENIED     The DNS cache entry already exists and Override is not TRUE.
1105
1106 **/
1107 EFI_STATUS
1108 EFIAPI
1109 Dns6UpdateDnsCache (
1110   IN EFI_DNS6_PROTOCOL      *This,
1111   IN BOOLEAN               DeleteFlag,
1112   IN BOOLEAN               Override,
1113   IN EFI_DNS6_CACHE_ENTRY   DnsCacheEntry
1114   );
1115
1116 /**
1117   This function can be used by network drivers and applications to increase the rate that data packets are moved between
1118   the communications device and the transmit and receive queues. In some systems, the periodic timer event in the managed
1119   network driver may not poll the underlying communications device fast enough to transmit and/or receive all data packets
1120   without missing incoming packets or dropping outgoing packets.
1121
1122   @param[in]  This               Pointer to EFI_DNS6_PROTOCOL instance.
1123
1124   @retval  EFI_SUCCESS           Incoming or outgoing data was processed.
1125   @retval  EFI_INVALID_PARAMETER This is NULL.
1126   @retval  EFI_NOT_STARTED       This EFI DNS Protocol instance has not been started.
1127   @retval  EFI_DEVICE_ERROR      An unexpected system or network error occurred.
1128   @retval  EFI_TIMEOUT           Data was dropped out of the transmit and/or receive queue.
1129                                  Consider increasing the polling rate.
1130
1131 **/
1132 EFI_STATUS
1133 EFIAPI
1134 Dns6Poll (
1135   IN EFI_DNS6_PROTOCOL    *This
1136   );
1137
1138 /**
1139   This function is used to abort a pending resolution request.
1140   After calling this function, Token.Status will be set to EFI_ABORTED and then Token.
1141
1142   @param[in]  This               Pointer to EFI_DNS6_PROTOCOL instance.
1143   @param[in]  Token              Pointer to a token that has been issued by EFI_DNS6_PROTOCOL.HostNameToIp(),
1144                                  EFI_DNS6_PROTOCOL.IpToHostName() or EFI_DNS6_PROTOCOL.GeneralLookup().
1145                                  If NULL, all pending tokens are aborted.
1146
1147   @retval  EFI_SUCCESS           Incoming or outgoing data was processed.
1148   @retval  EFI_INVALID_PARAMETER This is NULL.
1149   @retval  EFI_NOT_STARTED       This EFI DNS Protocol instance has not been started.
1150   @retval  EFI_NOT_FOUND         When Token is not NULL, and the asynchronous DNS operation was not found in the transmit queue.
1151                                  It was either completed or was not issued by HostNameToIp(), IpToHostName() or GeneralLookup().
1152
1153 **/
1154 EFI_STATUS
1155 EFIAPI
1156 Dns6Cancel (
1157   IN  EFI_DNS6_PROTOCOL          *This,
1158   IN  EFI_DNS6_COMPLETION_TOKEN  *Token
1159   );
1160
1161 #endif