diff options
Diffstat (limited to 'NetworkPkg/DnsDxe/DnsImpl.h')
| -rw-r--r-- | NetworkPkg/DnsDxe/DnsImpl.h | 583 |
1 files changed, 332 insertions, 251 deletions
diff --git a/NetworkPkg/DnsDxe/DnsImpl.h b/NetworkPkg/DnsDxe/DnsImpl.h index 72b85cb111..8cd73e73a6 100644 --- a/NetworkPkg/DnsDxe/DnsImpl.h +++ b/NetworkPkg/DnsDxe/DnsImpl.h @@ -732,17 +732,19 @@ DnsOnTimerUpdate ( /**
- This function is used to retrieve DNS mode data for this DNS instance.
+ Retrieve mode data of this DNS instance.
- @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
- @param[out] DnsModeData Pointer to the caller-allocated storage for the EFI_DNS4_MODE_DATA structure.
+ This function is used to retrieve DNS mode data for this DNS instance.
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_NOT_STARTED When DnsConfigData is queried, no configuration data is
- available because this instance has not been configured.
- @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
- @retval EFI_INVALID_PARAMETER This is NULL or DnsModeData is NULL.
+ @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
+ @param[out] DnsModeData Point to the mode data.
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_NOT_STARTED When DnsConfigData is queried, no configuration data
+ is available because this instance has not been
+ configured.
+ @retval EFI_INVALID_PARAMETER This is NULL or DnsModeData is NULL.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
**/
EFI_STATUS
EFIAPI
@@ -752,21 +754,29 @@ Dns4GetModeData ( );
/**
- This function is used to configure DNS configuration data for this DNS instance.
-
- @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
- @param[in] DnsConfigData Pointer to caller-allocated buffer containing EFI_DNS4_CONFIG_DATA structure.
- If NULL, the driver will reinitialize the protocol instance to the unconfigured state.
-
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_UNSUPPORTED The designated protocol is not supported.
- @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
- @retval EFI_INVALID_PARAMETER This is NULL.
- The StationIp address provided in DnsConfigData is not a valid unicast.
- DnsServerList is NULL while DnsServerListCount is not equal to Zero.
- DnsServerListCount is Zero while DnsServerListCount is not equal to NULL.
- @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI DNSv4 Protocol instance is not configured.
-
+ Configure this DNS instance.
+
+ This function is used to configure DNS mode data for this DNS instance.
+
+ @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
+ @param[in] DnsConfigData Point to the Configuration data.
+
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_UNSUPPORTED The designated protocol is not supported.
+ @retval EFI_INVALID_PARAMTER Thisis NULL.
+ The StationIp address provided in DnsConfigData is not a
+ valid unicast.
+ DnsServerList is NULL while DnsServerListCount
+ is not ZERO.
+ DnsServerListCount is ZERO while DnsServerList
+ is not NULL
+ @retval EFI_OUT_OF_RESOURCES The DNS instance data or required space could not be
+ allocated.
+ @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The
+ EFI DNSv4 Protocol instance is not configured.
+ @retval EFI_ALREADY_STARTED Second call to Configure() with DnsConfigData. To
+ reconfigure the instance the caller must call Configure()
+ with NULL first to return driver to unconfigured state.
**/
EFI_STATUS
EFIAPI
@@ -776,24 +786,24 @@ Dns4Configure ( );
/**
- The function is used to translate the host name to host IP address.
- A type A query is used to get the one or more IP addresses for this host.
-
- @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
- @param[in] HostName Pointer to caller-supplied buffer containing Host name to be translated.
- This buffer contains 16 bit characters but these are translated to ASCII for use with
- DNSv4 server and there is no requirement for driver to support non-ASCII Unicode characters.
- @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.
-
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
- @retval EFI_INVALID_PARAMETER This is NULL.
- Token is NULL.
- Token.Event is.NULL
- HostName is NULL
- @retval EFI_NO_MAPPING There's no source address is available for use.
- @retval EFI_NOT_STARTED This instance has not been started.
-
+ Host name to host address translation.
+
+ The HostNameToIp () function is used to translate the host name to host IP address. A
+ type A query is used to get the one or more IP addresses for this host.
+
+ @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
+ @param[in] HostName Host name.
+ @param[in] Token Point to the completion token to translate host name
+ to host address.
+
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ This is NULL.
+ Token is NULL.
+ Token.Event is NULL.
+ HostName is NULL. HostName string is unsupported format.
+ @retval EFI_NO_MAPPING There's no source address is available for use.
+ @retval EFI_NOT_STARTED This instance has not been started.
**/
EFI_STATUS
EFIAPI
@@ -804,23 +814,26 @@ Dns4HostNameToIp ( );
/**
- The function is used to translate the host address to host name.
- A type PTR query is used to get the primary name of the host.
-
- @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
- @param[in] IpAddress IP address.
- @param[in] Token Pointer to the caller-allocated completion used token to translate host address to host name.
-
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
- @retval EFI_INVALID_PARAMETER This is NULL.
- Token is NULL.
- Token.Event is NULL.
- IpAddress is not valid IP address.
- @retval EFI_NO_MAPPING There's no source address is available for use.
- @retval EFI_NOT_STARTED This instance has not been started.
- @retval EFI_UNSUPPORTED This function is not supported.
-
+ IPv4 address to host name translation also known as Reverse DNS lookup.
+
+ The IpToHostName() function is used to translate the host address to host name. A type PTR
+ query is used to get the primary name of the host. Support of this function is optional.
+
+ @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
+ @param[in] IpAddress Ip Address.
+ @param[in] Token Point to the completion token to translate host
+ address to host name.
+
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_UNSUPPORTED This function is not supported.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ This is NULL.
+ Token is NULL.
+ Token.Event is NULL.
+ IpAddress is not valid IP address .
+ @retval EFI_NO_MAPPING There's no source address is available for use.
+ @retval EFI_ALREADY_STARTED This Token is being used in another DNS session.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
**/
EFI_STATUS
EFIAPI
@@ -831,27 +844,31 @@ Dns4IpToHostName ( );
/**
- This function retrieves arbitrary information from the DNS.
- The caller supplies a QNAME, QTYPE, and QCLASS, and all of the matching RRs are returned.
- All RR content (e.g., Ttl) was returned.
- The caller need parse the returned RR to get required information. This function is optional.
-
- @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
- @param[in] QName Pointer to Query Name.
- @param[in] QType Query Type.
- @param[in] QClass Query Name.
- @param[in] Token Point to the caller-allocated completion token to retrieve arbitrary information.
-
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
- @retval EFI_INVALID_PARAMETER This is NULL.
- Token is NULL.
- Token.Event is NULL.
- QName is NULL.
- @retval EFI_NO_MAPPING There's no source address is available for use.
- @retval EFI_ALREADY_STARTED This Token is being used in another DNS session.
- @retval EFI_UNSUPPORTED This function is not supported. Or the requested QType is not supported
-
+ Retrieve arbitrary information from the DNS server.
+
+ This GeneralLookup() function retrieves arbitrary information from the DNS. The caller
+ supplies a QNAME, QTYPE, and QCLASS, and all of the matching RRs are returned. All
+ RR content (e.g., TTL) was returned. The caller need parse the returned RR to get
+ required information. The function is optional.
+
+ @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
+ @param[in] QName Pointer to Query Name.
+ @param[in] QType Query Type.
+ @param[in] QClass Query Name.
+ @param[in] Token Point to the completion token to retrieve arbitrary
+ information.
+
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_UNSUPPORTED This function is not supported. Or the requested
+ QType is not supported
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ This is NULL.
+ Token is NULL.
+ Token.Event is NULL.
+ QName is NULL.
+ @retval EFI_NO_MAPPING There's no source address is available for use.
+ @retval EFI_ALREADY_STARTED This Token is being used in another DNS session.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
**/
EFI_STATUS
EFIAPI
@@ -864,24 +881,30 @@ Dns4GeneralLookUp ( );
/**
- This function is used to add/delete/modify DNS cache entry.
- DNS cache can be normally dynamically updated after the DNS resolve succeeds.
- This function provided capability to manually add/delete/modify the DNS cache.
-
- @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
- @param[in] DeleteFlag If FALSE, this function is to add one entry to the DNS Cache.
- If TRUE, this function will delete matching DNS Cache entry.
- @param[in] Override If TRUE, the matching DNS cache entry will be overwritten with the supplied parameter.
- If FALSE, EFI_ACCESS_DENIED will be returned if the entry to be added is already exists.
- @param[in] DnsCacheEntry Pointer to DNS Cache entry.
-
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_INVALID_PARAMETER This is NULL.
- DnsCacheEntry.HostName is NULL.
- DnsCacheEntry.IpAddress is NULL.
- DnsCacheEntry.Timeout is zero.
- @retval EFI_ACCESS_DENIED The DNS cache entry already exists and Override is not TRUE.
-
+ This function is to update the DNS Cache.
+
+ The UpdateDnsCache() function is used to add/delete/modify DNS cache entry. DNS cache
+ can be normally dynamically updated after the DNS resolve succeeds. This function
+ provided capability to manually add/delete/modify the DNS cache.
+
+ @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
+ @param[in] DeleteFlag If FALSE, this function is to add one entry to the
+ DNS Cahce. If TRUE, this function will delete
+ matching DNS Cache entry.
+ @param[in] Override If TRUE, the maching DNS cache entry will be
+ overwritten with the supplied parameter. If FALSE,
+ EFI_ACCESS_DENIED will be returned if the entry to
+ be added is already existed.
+ @param[in] DnsCacheEntry Pointer to DNS Cache entry.
+
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ This is NULL.
+ DnsCacheEntry.HostName is NULL.
+ DnsCacheEntry.IpAddress is NULL.
+ DnsCacheEntry.Timeout is zero.
+ @retval EFI_ACCESS_DENIED The DNS cache entry already exists and Override is
+ not TRUE.
**/
EFI_STATUS
EFIAPI
@@ -893,20 +916,25 @@ Dns4UpdateDnsCache ( );
/**
- This function can be used by network drivers and applications to increase the rate that data packets are moved between
- the communications device and the transmit and receive queues. In some systems, the periodic timer event in the managed
- network driver may not poll the underlying communications device fast enough to transmit and/or receive all data packets
- without missing incoming packets or dropping outgoing packets.
-
- @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
-
- @retval EFI_SUCCESS Incoming or outgoing data was processed.
- @retval EFI_INVALID_PARAMETER This is NULL.
- @retval EFI_NOT_STARTED This EFI DNS Protocol instance has not been started.
- @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
- @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue.
- Consider increasing the polling rate.
-
+ Polls for incoming data packets and processes outgoing data packets.
+
+ The Poll() function can be used by network drivers and applications to increase the
+ rate that data packets are moved between the communications device and the transmit
+ and receive queues.
+ In some systems, the periodic timer event in the managed network driver may not poll
+ the underlying communications device fast enough to transmit and/or receive all data
+ packets without missing incoming packets or dropping outgoing packets. Drivers and
+ applications that are experiencing packet loss should try calling the Poll()
+ function more often.
+
+ @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
+
+ @retval EFI_SUCCESS Incoming or outgoing data was processed.
+ @retval EFI_NOT_STARTED This EFI DNS Protocol instance has not been started.
+ @retval EFI_INVALID_PARAMETER This is NULL.
+ @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
+ @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive
+ queue. Consider increasing the polling rate.
**/
EFI_STATUS
EFIAPI
@@ -915,20 +943,29 @@ Dns4Poll ( );
/**
- This function is used to abort a pending resolution request.
- After calling this function, Token.Status will be set to EFI_ABORTED and then Token.
-
- @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
- @param[in] Token Pointer to a token that has been issued by EFI_DNS4_PROTOCOL.HostNameToIp(),
- EFI_DNS4_PROTOCOL.IpToHostName() or EFI_DNS4_PROTOCOL.GeneralLookup().
- If NULL, all pending tokens are aborted.
-
- @retval EFI_SUCCESS Incoming or outgoing data was processed.
- @retval EFI_INVALID_PARAMETER This is NULL.
- @retval EFI_NOT_STARTED This EFI DNS Protocol instance has not been started.
- @retval EFI_NOT_FOUND When Token is not NULL, and the asynchronous DNS operation was not found in the transmit queue.
- It was either completed or was not issued by HostNameToIp(), IpToHostName() or GeneralLookup().
-
+ Abort an asynchronous DNS operation, including translation between IP and Host, and
+ general look up behavior.
+
+ The Cancel() function is used to abort a pending resolution request. After calling
+ this function, Token.Status will be set to EFI_ABORTED and then Token.Event will be
+ signaled. If the token is not in one of the queues, which usually means that the
+ asynchronous operation has completed, this function will not signal the token and
+ EFI_NOT_FOUND is returned.
+
+ @param[in] This Pointer to EFI_DNS4_PROTOCOL instance.
+ @param[in] Token Pointer to a token that has been issued by
+ EFI_DNS4_PROTOCOL.HostNameToIp (),
+ EFI_DNS4_PROTOCOL.IpToHostName() or
+ EFI_DNS4_PROTOCOL.GeneralLookup().
+ If NULL, all pending tokens are aborted.
+
+ @retval EFI_SUCCESS Incoming or outgoing data was processed.
+ @retval EFI_NOT_STARTED This EFI DNS4 Protocol instance has not been started.
+ @retval EFI_INVALID_PARAMETER This is NULL.
+ @retval EFI_NOT_FOUND When Token is not NULL, and the asynchronous DNS
+ operation was not found in the transmit queue. It
+ was either completed or was not issued by
+ HostNameToIp(), IpToHostName() or GeneralLookup().
**/
EFI_STATUS
EFIAPI
@@ -939,17 +976,20 @@ Dns4Cancel ( /**
- This function is used to retrieve DNS mode data for this DNS instance.
+ Retrieve mode data of this DNS instance.
- @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
- @param[out] DnsModeData Pointer to the caller-allocated storage for the EFI_DNS6_MODE_DATA structure.
+ This function is used to retrieve DNS mode data for this DNS instance.
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_NOT_STARTED When DnsConfigData is queried, no configuration data is
- available because this instance has not been configured.
- @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
- @retval EFI_INVALID_PARAMETER This is NULL or DnsModeData is NULL.
+ @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
+ @param[out] DnsModeData Pointer to the caller-allocated storage for the
+ EFI_DNS6_MODE_DATA data.
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_NOT_STARTED When DnsConfigData is queried, no configuration data
+ is available because this instance has not been
+ configured.
+ @retval EFI_INVALID_PARAMETER This is NULL or DnsModeData is NULL.
+ @retval EFI_OUT_OF_RESOURCE Failed to allocate needed resources.
**/
EFI_STATUS
EFIAPI
@@ -959,22 +999,27 @@ Dns6GetModeData ( );
/**
- The function is used to set and change the configuration data for this EFI DNSv6 Protocol driver instance.
- Reset the DNS instance if DnsConfigData is NULL.
-
- @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
- @param[in] DnsConfigData Pointer to the configuration data structure.
- All associated storage to be allocated and released by caller.
-
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_UNSUPPORTED The designated protocol is not supported.
- @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
- @retval EFI_INVALID_PARAMETER This is NULL.
- The StationIp address provided in DnsConfigData is not a valid unicast.
- DnsServerList is NULL while DnsServerListCount is not equal to Zero.
- DnsServerListCount is Zero while DnsServerList is not equal to NULL.
- @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI DNSv6 Protocol instance is not configured.
-
+ Configure this DNS instance.
+
+ The Configure() function is used to set and change the configuration data for this
+ EFI DNSv6 Protocol driver instance. Reset the DNS instance if DnsConfigData is NULL.
+
+ @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
+ @param[in] DnsConfigData Pointer to the configuration data structure. All associated
+ storage to be allocated and released by caller.
+
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_INVALID_PARAMTER This is NULL.
+ The StationIp address provided in DnsConfigData is not zero and not a valid unicast.
+ DnsServerList is NULL while DnsServerList Count is not ZERO.
+ DnsServerList Count is ZERO while DnsServerList is not NULL.
+ @retval EFI_OUT_OF_RESOURCES The DNS instance data or required space could not be allocated.
+ @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The
+ EFI DNSv6 Protocol instance is not configured.
+ @retval EFI_UNSUPPORTED The designated protocol is not supported.
+ @retval EFI_ALREADY_STARTED Second call to Configure() with DnsConfigData. To
+ reconfigure the instance the caller must call Configure() with
+ NULL first to return driver to unconfigured state.
**/
EFI_STATUS
EFIAPI
@@ -984,24 +1029,26 @@ Dns6Configure ( );
/**
- The function is used to translate the host name to host IP address.
- A type AAAA query is used to get the one or more IPv6 addresses for this host.
-
- @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
- @param[in] HostName Pointer to caller-supplied buffer containing Host name to be translated.
- This buffer contains 16 bit characters but these are translated to ASCII for use with
- DNSv4 server and there is no requirement for driver to support non-ASCII Unicode characters.
- @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.
-
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
- @retval EFI_INVALID_PARAMETER This is NULL.
- Token is NULL.
- Token.Event is.NULL
- HostName is NULL
- @retval EFI_NO_MAPPING There's no source address is available for use.
- @retval EFI_NOT_STARTED This instance has not been started.
-
+ Host name to host address translation.
+
+ The HostNameToIp () function is used to translate the host name to host IP address. A
+ type AAAA query is used to get the one or more IPv6 addresses for this host.
+
+ @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
+ @param[in] HostName Host name.
+ @param[in] Token Point to the completion token to translate host name
+ to host address.
+
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ This is NULL.
+ Token is NULL.
+ Token.Event is NULL.
+ HostName is NULL or buffer contained unsupported characters.
+ @retval EFI_NO_MAPPING There's no source address is available for use.
+ @retval EFI_ALREADY_STARTED This Token is being used in another DNS session.
+ @retval EFI_NOT_STARTED This instance has not been started.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
**/
EFI_STATUS
EFIAPI
@@ -1012,23 +1059,27 @@ Dns6HostNameToIp ( );
/**
- The function is used to translate the host address to host name.
- A type PTR query is used to get the primary name of the host.
-
- @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
- @param[in] IpAddress IP address.
- @param[in] Token Pointer to the caller-allocated completion used token to translate host address to host name.
-
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
- @retval EFI_INVALID_PARAMETER This is NULL.
- Token is NULL.
- Token.Event is NULL.
- IpAddress is not valid IP address.
- @retval EFI_NO_MAPPING There's no source address is available for use.
- @retval EFI_NOT_STARTED This instance has not been started.
- @retval EFI_UNSUPPORTED This function is not supported.
-
+ Host address to host name translation.
+
+ The IpToHostName () function is used to translate the host address to host name. A
+ type PTR query is used to get the primary name of the host. Implementation can choose
+ to support this function or not.
+
+ @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
+ @param[in] IpAddress Ip Address.
+ @param[in] Token Point to the completion token to translate host
+ address to host name.
+
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_UNSUPPORTED This function is not supported.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ This is NULL.
+ Token is NULL.
+ Token.Event is NULL.
+ IpAddress is not valid IP address.
+ @retval EFI_NO_MAPPING There's no source address is available for use.
+ @retval EFI_NOT_STARTED This instance has not been started.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
**/
EFI_STATUS
EFIAPI
@@ -1039,27 +1090,33 @@ Dns6IpToHostName ( );
/**
- This function retrieves arbitrary information from the DNS.
- The caller supplies a QNAME, QTYPE, and QCLASS, and all of the matching RRs are returned.
- All RR content (e.g., Ttl) was returned.
- The caller need parse the returned RR to get required information. This function is optional.
-
- @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
- @param[in] QName Pointer to Query Name.
- @param[in] QType Query Type.
- @param[in] QClass Query Name.
- @param[in] Token Point to the caller-allocated completion token to retrieve arbitrary information.
-
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
- @retval EFI_INVALID_PARAMETER This is NULL.
- Token is NULL.
- Token.Event is NULL.
- QName is NULL.
- @retval EFI_NO_MAPPING There's no source address is available for use.
- @retval EFI_NOT_STARTED This instance has not been started.
- @retval EFI_UNSUPPORTED This function is not supported. Or the requested QType is not supported
-
+ This function provides capability to retrieve arbitrary information from the DNS
+ server.
+
+ This GeneralLookup() function retrieves arbitrary information from the DNS. The caller
+ supplies a QNAME, QTYPE, and QCLASS, and all of the matching RRs are returned. All
+ RR content (e.g., TTL) was returned. The caller need parse the returned RR to get
+ required information. The function is optional. Implementation can choose to support
+ it or not.
+
+ @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
+ @param[in] QName Pointer to Query Name.
+ @param[in] QType Query Type.
+ @param[in] QClass Query Name.
+ @param[in] Token Point to the completion token to retrieve arbitrary
+ information.
+
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_UNSUPPORTED This function is not supported. Or the requested
+ QType is not supported
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ This is NULL.
+ Token is NULL.
+ Token.Event is NULL.
+ QName is NULL.
+ @retval EFI_NO_MAPPING There's no source address is available for use.
+ @retval EFI_NOT_STARTED This instance has not been started.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
**/
EFI_STATUS
EFIAPI
@@ -1072,24 +1129,31 @@ Dns6GeneralLookUp ( );
/**
- This function is used to add/delete/modify DNS cache entry.
- DNS cache can be normally dynamically updated after the DNS resolve succeeds.
- This function provided capability to manually add/delete/modify the DNS cache.
-
- @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
- @param[in] DeleteFlag If FALSE, this function is to add one entry to the DNS Cache.
- If TRUE, this function will delete matching DNS Cache entry.
- @param[in] Override If TRUE, the matching DNS cache entry will be overwritten with the supplied parameter.
- If FALSE, EFI_ACCESS_DENIED will be returned if the entry to be added is already exists.
- @param[in] DnsCacheEntry Pointer to DNS Cache entry.
-
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_INVALID_PARAMETER This is NULL.
- DnsCacheEntry.HostName is NULL.
- DnsCacheEntry.IpAddress is NULL.
- DnsCacheEntry.Timeout is zero.
- @retval EFI_ACCESS_DENIED The DNS cache entry already exists and Override is not TRUE.
-
+ This function is to update the DNS Cache.
+
+ The UpdateDnsCache() function is used to add/delete/modify DNS cache entry. DNS cache
+ can be normally dynamically updated after the DNS resolve succeeds. This function
+ provided capability to manually add/delete/modify the DNS cache.
+
+ @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
+ @param[in] DeleteFlag If FALSE, this function is to add one entry to the
+ DNS Cahce. If TRUE, this function will delete
+ matching DNS Cache entry.
+ @param[in] Override If TRUE, the maching DNS cache entry will be
+ overwritten with the supplied parameter. If FALSE,
+ EFI_ACCESS_DENIED will be returned if the entry to
+ be added is already existed.
+ @param[in] DnsCacheEntry Pointer to DNS Cache entry.
+
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ This is NULL.
+ DnsCacheEntry.HostName is NULL.
+ DnsCacheEntry.IpAddress is NULL.
+ DnsCacheEntry.Timeout is zero.
+ @retval EFI_ACCESS_DENIED The DNS cache entry already exists and Override is
+ not TRUE.
+ @retval EFI_OUT_OF_RESOURCE Failed to allocate needed resources.
**/
EFI_STATUS
EFIAPI
@@ -1101,20 +1165,27 @@ Dns6UpdateDnsCache ( );
/**
- This function can be used by network drivers and applications to increase the rate that data packets are moved between
- the communications device and the transmit and receive queues. In some systems, the periodic timer event in the managed
- network driver may not poll the underlying communications device fast enough to transmit and/or receive all data packets
- without missing incoming packets or dropping outgoing packets.
-
- @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
-
- @retval EFI_SUCCESS Incoming or outgoing data was processed.
- @retval EFI_INVALID_PARAMETER This is NULL.
- @retval EFI_NOT_STARTED This EFI DNS Protocol instance has not been started.
- @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
- @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue.
- Consider increasing the polling rate.
-
+ Polls for incoming data packets and processes outgoing data packets.
+
+ The Poll() function can be used by network drivers and applications to increase the
+ rate that data packets are moved between the communications device and the transmit
+ and receive queues.
+
+ In some systems, the periodic timer event in the managed network driver may not poll
+ the underlying communications device fast enough to transmit and/or receive all data
+ packets without missing incoming packets or dropping outgoing packets. Drivers and
+ applications that are experiencing packet loss should try calling the Poll()
+ function more often.
+
+ @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
+
+ @retval EFI_SUCCESS Incoming or outgoing data was processed.
+ @retval EFI_NOT_STARTED This EFI DNS Protocol instance has not been started.
+ @retval EFI_INVALID_PARAMETER This is NULL.
+ @retval EFI_NO_MAPPING There is no source address is available for use.
+ @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
+ @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive
+ queue. Consider increasing the polling rate.
**/
EFI_STATUS
EFIAPI
@@ -1123,20 +1194,30 @@ Dns6Poll ( );
/**
- This function is used to abort a pending resolution request.
- After calling this function, Token.Status will be set to EFI_ABORTED and then Token.
-
- @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
- @param[in] Token Pointer to a token that has been issued by EFI_DNS6_PROTOCOL.HostNameToIp(),
- EFI_DNS6_PROTOCOL.IpToHostName() or EFI_DNS6_PROTOCOL.GeneralLookup().
- If NULL, all pending tokens are aborted.
-
- @retval EFI_SUCCESS Incoming or outgoing data was processed.
- @retval EFI_INVALID_PARAMETER This is NULL.
- @retval EFI_NOT_STARTED This EFI DNS Protocol instance has not been started.
- @retval EFI_NOT_FOUND When Token is not NULL, and the asynchronous DNS operation was not found in the transmit queue.
- It was either completed or was not issued by HostNameToIp(), IpToHostName() or GeneralLookup().
-
+ Abort an asynchronous DNS operation, including translation between IP and Host, and
+ general look up behavior.
+
+ The Cancel() function is used to abort a pending resolution request. After calling
+ this function, Token.Status will be set to EFI_ABORTED and then Token.Event will be
+ signaled. If the token is not in one of the queues, which usually means that the
+ asynchronous operation has completed, this function will not signal the token and
+ EFI_NOT_FOUND is returned.
+
+ @param[in] This Pointer to EFI_DNS6_PROTOCOL instance.
+ @param[in] Token Pointer to a token that has been issued by
+ EFI_DNS6_PROTOCOL.HostNameToIp (),
+ EFI_DNS6_PROTOCOL.IpToHostName() or
+ EFI_DNS6_PROTOCOL.GeneralLookup().
+ If NULL, all pending tokens are aborted.
+
+ @retval EFI_SUCCESS Incoming or outgoing data was processed.
+ @retval EFI_NOT_STARTED This EFI DNS6 Protocol instance has not been started.
+ @retval EFI_INVALID_PARAMETER This is NULL.
+ @retval EFI_NO_MAPPING There's no source address is available for use.
+ @retval EFI_NOT_FOUND When Token is not NULL, and the asynchronous DNS
+ operation was not found in the transmit queue. It
+ was either completed or was not issued by
+ HostNameToIp(), IpToHostName() or GeneralLookup().
**/
EFI_STATUS
EFIAPI
|