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