NetworkPkg/DnsDxe/DnsImpl.h

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