NetworkPkg/DnsDxe/DnsImpl.h

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