mirror of
https://github.com/CloverHackyColor/CloverBootloader.git
synced 2024-11-23 11:35:19 +01:00
534 lines
21 KiB
C
534 lines
21 KiB
C
/** @file
|
|
This file defines the EFI DNSv6 (Domain Name Service version 6) Protocol. It is split
|
|
into the following two main sections:
|
|
DNSv6 Service Binding Protocol (DNSv6SB)
|
|
DNSv6 Protocol (DNSv6)
|
|
|
|
Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR>
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
|
|
@par Revision Reference:
|
|
This Protocol is introduced in UEFI Specification 2.5
|
|
|
|
**/
|
|
|
|
#ifndef __EFI_DNS6_PROTOCOL_H__
|
|
#define __EFI_DNS6_PROTOCOL_H__
|
|
|
|
#define EFI_DNS6_SERVICE_BINDING_PROTOCOL_GUID \
|
|
{ \
|
|
0x7f1647c8, 0xb76e, 0x44b2, {0xa5, 0x65, 0xf7, 0xf, 0xf1, 0x9c, 0xd1, 0x9e } \
|
|
}
|
|
|
|
#define EFI_DNS6_PROTOCOL_GUID \
|
|
{ \
|
|
0xca37bc1f, 0xa327, 0x4ae9, {0x82, 0x8a, 0x8c, 0x40, 0xd8, 0x50, 0x6a, 0x17 } \
|
|
}
|
|
|
|
typedef struct _EFI_DNS6_PROTOCOL EFI_DNS6_PROTOCOL;
|
|
|
|
///
|
|
/// EFI_DNS6_CONFIG_DATA
|
|
///
|
|
typedef struct {
|
|
///
|
|
/// If TRUE, enable DNS cache function for this DNS instance. If FALSE, all DNS query
|
|
/// will not lookup local DNS cache.
|
|
///
|
|
BOOLEAN EnableDnsCache;
|
|
///
|
|
/// Use the protocol number defined in
|
|
/// http://www.iana.org/assignments/protocol-numbers. Beside TCP/UDP, Other protocol
|
|
/// is invalid value. An implementation can choose to support UDP, or both TCP and UDP.
|
|
///
|
|
UINT8 Protocol;
|
|
///
|
|
/// The local IP address to use. Set to zero to let the underlying IPv6
|
|
/// driver choose a source address. If not zero it must be one of the
|
|
/// configured IP addresses in the underlying IPv6 driver.
|
|
///
|
|
EFI_IPv6_ADDRESS StationIp;
|
|
///
|
|
/// Local port number. Set to zero to use the automatically assigned port number.
|
|
///
|
|
UINT16 LocalPort;
|
|
///
|
|
/// Count of the DNS servers. When used with GetModeData(),
|
|
/// this field is the count of originally configured servers when
|
|
/// Configure() was called for this instance. When used with
|
|
/// Configure() this is the count of caller-supplied servers. If the
|
|
/// DnsServerListCount is zero, the DNS server configuration
|
|
/// will be retrieved from DHCP server automatically.
|
|
///
|
|
UINT32 DnsServerCount;
|
|
///
|
|
/// Pointer to DNS server list containing DnsServerListCount
|
|
/// entries or NULL if DnsServerListCount is 0. For Configure(),
|
|
/// this will be NULL when there are no caller supplied server addresses
|
|
/// and the DNS instance will retrieve DNS server from DHCP Server.
|
|
/// The provided DNS server list is recommended to be filled up in the sequence
|
|
/// of preference. When used with GetModeData(), the buffer containing the list
|
|
/// will be allocated by the driver implementing this protocol and must be
|
|
/// freed by the caller. When used with Configure(), the buffer
|
|
/// containing the list will be allocated and released by the caller.
|
|
///
|
|
EFI_IPv6_ADDRESS *DnsServerList;
|
|
///
|
|
/// Retry number if no response received after RetryInterval.
|
|
///
|
|
UINT32 RetryCount;
|
|
///
|
|
/// Minimum interval of retry is 2 second. If the retry interval is less than 2
|
|
/// seconds, then use the 2 seconds.
|
|
UINT32 RetryInterval;
|
|
} EFI_DNS6_CONFIG_DATA;
|
|
|
|
///
|
|
/// EFI_DNS6_CACHE_ENTRY
|
|
///
|
|
typedef struct {
|
|
///
|
|
/// Host name. This should be interpreted as Unicode characters.
|
|
///
|
|
CHAR16 *HostName;
|
|
///
|
|
/// IP address of this host.
|
|
///
|
|
EFI_IPv6_ADDRESS *IpAddress;
|
|
///
|
|
/// Time in second unit that this entry will remain in DNS cache. A value of zero means
|
|
/// that this entry is permanent. A nonzero value will override the existing one if
|
|
/// this entry to be added is dynamic entry. Implementations may set its default
|
|
/// timeout value for the dynamically created DNS cache entry after one DNS resolve
|
|
/// succeeds.
|
|
UINT32 Timeout;
|
|
} EFI_DNS6_CACHE_ENTRY;
|
|
|
|
///
|
|
/// EFI_DNS6_MODE_DATA
|
|
///
|
|
typedef struct {
|
|
///
|
|
/// The configuration data of this instance.
|
|
///
|
|
EFI_DNS6_CONFIG_DATA DnsConfigData;
|
|
///
|
|
/// Number of configured DNS6 servers.
|
|
///
|
|
UINT32 DnsServerCount;
|
|
///
|
|
/// Pointer to common list of addresses of all configured DNS server used by EFI_DNS6_PROTOCOL
|
|
/// instances. List will include DNS servers configured by this or any other EFI_DNS6_PROTOCOL
|
|
/// instance. The storage for this list is allocated by the driver publishing this protocol,
|
|
/// and must be freed by the caller.
|
|
///
|
|
EFI_IPv6_ADDRESS *DnsServerList;
|
|
///
|
|
/// Number of DNS Cache entries. The DNS Cache is shared among all DNS instances.
|
|
///
|
|
UINT32 DnsCacheCount;
|
|
///
|
|
/// Pointer to a buffer containing DnsCacheCount DNS Cache
|
|
/// entry structures. The storage for thislist is allocated by the driver
|
|
/// publishing this protocol and must be freed by caller.
|
|
///
|
|
EFI_DNS6_CACHE_ENTRY *DnsCacheList;
|
|
} EFI_DNS6_MODE_DATA;
|
|
|
|
///
|
|
/// DNS6_HOST_TO_ADDR_DATA
|
|
///
|
|
typedef struct {
|
|
///
|
|
/// Number of the returned IP address.
|
|
///
|
|
UINT32 IpCount;
|
|
///
|
|
/// Pointer to the all the returned IP address.
|
|
///
|
|
EFI_IPv6_ADDRESS *IpList;
|
|
} DNS6_HOST_TO_ADDR_DATA;
|
|
|
|
///
|
|
/// DNS6_ADDR_TO_HOST_DATA
|
|
///
|
|
typedef struct {
|
|
///
|
|
/// Pointer to the primary name for this host address. It's the caller's
|
|
/// responsibility to free the response memory.
|
|
///
|
|
CHAR16 *HostName;
|
|
} DNS6_ADDR_TO_HOST_DATA;
|
|
|
|
///
|
|
/// DNS6_RESOURCE_RECORD
|
|
///
|
|
typedef struct {
|
|
///
|
|
/// The Owner name.
|
|
///
|
|
CHAR8 *QName;
|
|
///
|
|
/// The Type Code of this RR.
|
|
///
|
|
UINT16 QType;
|
|
///
|
|
/// The CLASS code of this RR.
|
|
///
|
|
UINT16 QClass;
|
|
///
|
|
/// 32 bit integer which specify the time interval that the resource record may be
|
|
/// cached before the source of the information should again be consulted. Zero means
|
|
/// this RR cannot be cached.
|
|
///
|
|
UINT32 TTL;
|
|
///
|
|
/// 16 big integer which specify the length of RData.
|
|
///
|
|
UINT16 DataLength;
|
|
///
|
|
/// A string of octets that describe the resource, the format of this information
|
|
/// varies according to QType and QClass difference.
|
|
///
|
|
CHAR8 *RData;
|
|
} DNS6_RESOURCE_RECORD;
|
|
|
|
///
|
|
/// DNS6_GENERAL_LOOKUP_DATA
|
|
///
|
|
typedef struct {
|
|
///
|
|
/// Number of returned matching RRs.
|
|
///
|
|
UINTN RRCount;
|
|
///
|
|
/// Pointer to the all the returned matching RRs. It's caller responsibility to free
|
|
/// the allocated memory to hold the returned RRs.
|
|
///
|
|
DNS6_RESOURCE_RECORD *RRList;
|
|
} DNS6_GENERAL_LOOKUP_DATA;
|
|
|
|
///
|
|
/// EFI_DNS6_COMPLETION_TOKEN
|
|
///
|
|
typedef struct {
|
|
///
|
|
/// This Event will be signaled after the Status field is updated by the EFI DNSv6
|
|
/// protocol driver. The type of Event must be EFI_NOTIFY_SIGNAL.
|
|
///
|
|
EFI_EVENT Event;
|
|
///
|
|
/// Will be set to one of the following values:
|
|
/// EFI_SUCCESS: The host name to address translation completed successfully.
|
|
/// EFI_NOT_FOUND: No matching Resource Record (RR) is found.
|
|
/// EFI_TIMEOUT: No DNS server reachable, or RetryCount was exhausted without
|
|
/// response from all specified DNS servers.
|
|
/// EFI_DEVICE_ERROR: An unexpected system or network error occurred.
|
|
/// EFI_NO_MEDIA: There was a media error.
|
|
///
|
|
EFI_STATUS Status;
|
|
///
|
|
/// The parameter configured through DNSv6.Configure() interface. Retry number if no
|
|
/// response received after RetryInterval.
|
|
///
|
|
UINT32 RetryCount;
|
|
///
|
|
/// The parameter configured through DNSv6.Configure() interface. Minimum interval of
|
|
/// retry is 2 seconds. If the retry interval is less than 2 seconds, then use the 2
|
|
/// seconds.
|
|
///
|
|
UINT32 RetryInterval;
|
|
///
|
|
/// DNSv6 completion token data
|
|
///
|
|
union {
|
|
///
|
|
/// When the Token is used for host name to address translation, H2AData is a pointer
|
|
/// to the DNS6_HOST_TO_ADDR_DATA.
|
|
///
|
|
DNS6_HOST_TO_ADDR_DATA *H2AData;
|
|
///
|
|
/// When the Token is used for host address to host name translation, A2HData is a
|
|
/// pointer to the DNS6_ADDR_TO_HOST_DATA.
|
|
///
|
|
DNS6_ADDR_TO_HOST_DATA *A2HData;
|
|
///
|
|
/// When the Token is used for a general lookup function, GLookupDATA is a pointer to
|
|
/// the DNS6_GENERAL_LOOKUP_DATA.
|
|
///
|
|
DNS6_GENERAL_LOOKUP_DATA *GLookupData;
|
|
} RspData;
|
|
} EFI_DNS6_COMPLETION_TOKEN;
|
|
|
|
/**
|
|
Retrieve mode data of this DNS instance.
|
|
|
|
This function is used to retrieve DNS mode data for 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 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.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI * EFI_DNS6_GET_MODE_DATA)(
|
|
IN EFI_DNS6_PROTOCOL *This,
|
|
OUT EFI_DNS6_MODE_DATA *DnsModeData
|
|
);
|
|
|
|
/**
|
|
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_PARAMETER 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.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI * EFI_DNS6_CONFIGURE)(
|
|
IN EFI_DNS6_PROTOCOL *This,
|
|
IN EFI_DNS6_CONFIG_DATA *DnsConfigData
|
|
);
|
|
|
|
/**
|
|
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.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *EFI_DNS6_HOST_NAME_TO_IP) (
|
|
IN EFI_DNS6_PROTOCOL *This,
|
|
IN CHAR16 *HostName,
|
|
IN EFI_DNS6_COMPLETION_TOKEN *Token
|
|
);
|
|
|
|
/**
|
|
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.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *EFI_DNS6_IP_TO_HOST_NAME) (
|
|
IN EFI_DNS6_PROTOCOL *This,
|
|
IN EFI_IPv6_ADDRESS IpAddress,
|
|
IN EFI_DNS6_COMPLETION_TOKEN *Token
|
|
);
|
|
|
|
/**
|
|
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.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *EFI_DNS6_GENERAL_LOOKUP) (
|
|
IN EFI_DNS6_PROTOCOL *This,
|
|
IN CHAR8 *QName,
|
|
IN UINT16 QType,
|
|
IN UINT16 QClass,
|
|
IN EFI_DNS6_COMPLETION_TOKEN *Token
|
|
);
|
|
|
|
/**
|
|
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.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *EFI_DNS6_UPDATE_DNS_CACHE) (
|
|
IN EFI_DNS6_PROTOCOL *This,
|
|
IN BOOLEAN DeleteFlag,
|
|
IN BOOLEAN Override,
|
|
IN EFI_DNS6_CACHE_ENTRY DnsCacheEntry
|
|
);
|
|
|
|
/**
|
|
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.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *EFI_DNS6_POLL) (
|
|
IN EFI_DNS6_PROTOCOL *This
|
|
);
|
|
|
|
/**
|
|
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().
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *EFI_DNS6_CANCEL) (
|
|
IN EFI_DNS6_PROTOCOL *This,
|
|
IN EFI_DNS6_COMPLETION_TOKEN *Token
|
|
);
|
|
|
|
///
|
|
/// The EFI_DNS6_PROTOCOL provides the function to get the host name and address
|
|
/// mapping, also provide pass through interface to retrieve arbitrary information from
|
|
/// DNSv6.
|
|
///
|
|
struct _EFI_DNS6_PROTOCOL {
|
|
EFI_DNS6_GET_MODE_DATA GetModeData;
|
|
EFI_DNS6_CONFIGURE Configure;
|
|
EFI_DNS6_HOST_NAME_TO_IP HostNameToIp;
|
|
EFI_DNS6_IP_TO_HOST_NAME IpToHostName;
|
|
EFI_DNS6_GENERAL_LOOKUP GeneralLookUp;
|
|
EFI_DNS6_UPDATE_DNS_CACHE UpdateDnsCache;
|
|
EFI_DNS6_POLL Poll;
|
|
EFI_DNS6_CANCEL Cancel;
|
|
};
|
|
|
|
extern EFI_GUID gEfiDns6ServiceBindingProtocolGuid;
|
|
extern EFI_GUID gEfiDns6ProtocolGuid;
|
|
|
|
#endif
|