DNS Service Discovery C Reference

Overview

Functions

See the Overview for header-level documentation.

DNSServiceAddRecord

DNSServiceErrorType DNSServiceAddRecord (
   DNSServiceRef sdRef,
   DNSRecordRef *RecordRef,
   DNSServiceFlags flags,
   uint16_t rrtype,
   uint16_t rdlen,
   const void *rdata,
   uint32_t ttl );

DNSServiceBrowse

DNSServiceErrorType DNSServiceBrowse (
   DNSServiceRef *sdRef,
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   const char *regtype,
   const char *domain, /* may be NULL */
   DNSServiceBrowseReply callBack,
   void *context /* may be NULL */
   );

DNSServiceConstructFullName

DNSServiceErrorType DNSServiceConstructFullName (
   char *const fullName,
   const char *const service, /* may be NULL */
   const char *const regtype,
   const char *const domain );

DNSServiceCreateConnection

DNSServiceErrorType DNSServiceCreateConnection(
   DNSServiceRef *sdRef);

DNSServiceEnumerateDomains

DNSServiceErrorType DNSServiceEnumerateDomains (
   DNSServiceRef *sdRef,
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   DNSServiceDomainEnumReply callBack,
   void *context /* may be NULL */
   );

DNSServiceGetAddrInfo

DNSServiceErrorType DNSServiceGetAddrInfo (
   DNSServiceRef *sdRef,
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   DNSServiceProtocol protocol,
   const char *hostname,
   DNSServiceGetAddrInfoReply callBack,
   void *context /* may be NULL */
   );

DNSServiceGetProperty

DNSServiceErrorType DNSServiceGetProperty (
   const char *property, /* Requested property (i.e. kDNSServiceProperty_DaemonVersion) */
   void *result, /* Pointer to place to store result */
   uint32_t *size /* size of result location */
   );

DNSServiceNATPortMappingCreate

DNSServiceErrorType DNSServiceNATPortMappingCreate (
   DNSServiceRef *sdRef,
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   DNSServiceProtocol protocol, /* TCP and/or UDP          */
   uint16_t internalPort, /* network byte order      */
   uint16_t externalPort, /* network byte order      */
   uint32_t ttl, /* time to live in seconds */
   DNSServiceNATPortMappingReply callBack,
   void *context /* may be NULL             */
   );

DNSServiceProcessResult

DNSServiceErrorType DNSServiceProcessResult(
   DNSServiceRef sdRef);

DNSServiceQueryRecord

DNSServiceErrorType DNSServiceQueryRecord (
   DNSServiceRef *sdRef,
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   const char *fullname,
   uint16_t rrtype,
   uint16_t rrclass,
   DNSServiceQueryRecordReply callBack,
   void *context /* may be NULL */
   );

DNSServiceReconfirmRecord

DNSServiceErrorType DNSServiceReconfirmRecord (
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   const char *fullname,
   uint16_t rrtype,
   uint16_t rrclass,
   uint16_t rdlen,
   const void *rdata );

DNSServiceRefDeallocate

void DNSServiceRefDeallocate(
   DNSServiceRef sdRef);

DNSServiceRefSockFD

int DNSServiceRefSockFD(
   DNSServiceRef sdRef);

DNSServiceRegister

DNSServiceErrorType DNSServiceRegister (
   DNSServiceRef *sdRef,
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   const char *name, /* may be NULL */
   const char *regtype,
   const char *domain, /* may be NULL */
   const char *host, /* may be NULL */
   uint16_t port, /* In network byte order */
   uint16_t txtLen,
   const void *txtRecord, /* may be NULL */
   DNSServiceRegisterReply callBack, /* may be NULL */
   void *context /* may be NULL */
   );

DNSServiceRegisterRecord

DNSServiceErrorType DNSServiceRegisterRecord (
   DNSServiceRef sdRef,
   DNSRecordRef *RecordRef,
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   const char *fullname,
   uint16_t rrtype,
   uint16_t rrclass,
   uint16_t rdlen,
   const void *rdata,
   uint32_t ttl,
   DNSServiceRegisterRecordReply callBack,
   void *context /* may be NULL */
   );

DNSServiceRemoveRecord

DNSServiceErrorType DNSServiceRemoveRecord (
   DNSServiceRef sdRef,
   DNSRecordRef RecordRef,
   DNSServiceFlags flags );

DNSServiceResolve

DNSServiceErrorType DNSServiceResolve (
   DNSServiceRef *sdRef,
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   const char *name,
   const char *regtype,
   const char *domain,
   DNSServiceResolveReply callBack,
   void *context /* may be NULL */
   );

DNSServiceSetDispatchQueue

DNSServiceErrorType DNSServiceSetDispatchQueue (
   DNSServiceRef service,
   dispatch_queue_t queue );

DNSServiceUpdateRecord

DNSServiceErrorType DNSServiceUpdateRecord (
   DNSServiceRef sdRef,
   DNSRecordRef RecordRef, /* may be NULL */
   DNSServiceFlags flags,
   uint16_t rdlen,
   const void *rdata,
   uint32_t ttl );

TXTRecordContainsKey

int TXTRecordContainsKey (
   uint16_t txtLen,
   const void *txtRecord,
   const char *key );

TXTRecordCreate

void TXTRecordCreate (
   TXTRecordRef *txtRecord,
   uint16_t bufferLen,
   void *buffer );

TXTRecordDeallocate

void TXTRecordDeallocate (
   TXTRecordRef *txtRecord );

TXTRecordGetBytesPtr

const void * TXTRecordGetBytesPtr (
   const TXTRecordRef *txtRecord );

TXTRecordGetCount

uint16_t TXTRecordGetCount (
   uint16_t txtLen,
   const void *txtRecord );

TXTRecordGetItemAtIndex

DNSServiceErrorType TXTRecordGetItemAtIndex (
   uint16_t txtLen,
   const void *txtRecord,
   uint16_t itemIndex,
   uint16_t keyBufLen,
   char *key,
   uint8_t *valueLen,
   const void **value );

TXTRecordGetLength

uint16_t TXTRecordGetLength (
   const TXTRecordRef *txtRecord );

TXTRecordGetValuePtr

const void * TXTRecordGetValuePtr (
   uint16_t txtLen,
   const void *txtRecord,
   const char *key,
   uint8_t *valueLen );

TXTRecordRemoveValue

DNSServiceErrorType TXTRecordRemoveValue (
   TXTRecordRef *txtRecord,
   const char *key );

TXTRecordSetValue

DNSServiceErrorType TXTRecordSetValue (
   TXTRecordRef *txtRecord,
   const char *key,
   uint8_t valueSize, /* may be zero */
   const void *value /* may be NULL */
   );

Callbacks

See the Overview for header-level documentation.

DNSServiceBrowseReply

typedef void ( *DNSServiceBrowseReply) (
   DNSServiceRef sdRef,
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   DNSServiceErrorType errorCode,
   const char *serviceName,
   const char *regtype,
   const char *replyDomain,
   void *context );

DNSServiceDomainEnumReply

typedef void ( *DNSServiceDomainEnumReply) (
   DNSServiceRef sdRef,
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   DNSServiceErrorType errorCode,
   const char *replyDomain,
   void *context );

DNSServiceGetAddrInfoReply

typedef void ( *DNSServiceGetAddrInfoReply) (
   DNSServiceRef sdRef,
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   DNSServiceErrorType errorCode,
   const char *hostname,
   const struct sockaddr *address,
   uint32_t ttl,
   void *context );

DNSServiceNATPortMappingReply

typedef void ( *DNSServiceNATPortMappingReply) (
   DNSServiceRef sdRef,
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   DNSServiceErrorType errorCode,
   uint32_t externalAddress, /* four byte IPv4 address in network byte order */
   DNSServiceProtocol protocol,
   uint16_t internalPort, /* In network byte order */
   uint16_t externalPort, /* In network byte order and may be different than the requested port */
   uint32_t ttl, /* may be different than the requested ttl */
   void *context );

DNSServiceQueryRecordReply

typedef void ( *DNSServiceQueryRecordReply) (
   DNSServiceRef sdRef,
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   DNSServiceErrorType errorCode,
   const char *fullname,
   uint16_t rrtype,
   uint16_t rrclass,
   uint16_t rdlen,
   const void *rdata,
   uint32_t ttl,
   void *context );

DNSServiceRegisterRecordReply

typedef void ( *DNSServiceRegisterRecordReply) (
   DNSServiceRef sdRef,
   DNSRecordRef RecordRef,
   DNSServiceFlags flags,
   DNSServiceErrorType errorCode,
   void *context );

DNSServiceRegisterReply

typedef void ( *DNSServiceRegisterReply) (
   DNSServiceRef sdRef,
   DNSServiceFlags flags,
   DNSServiceErrorType errorCode,
   const char *name,
   const char *regtype,
   const char *domain,
   void *context );

DNSServiceResolveReply

typedef void ( *DNSServiceResolveReply) (
   DNSServiceRef sdRef,
   DNSServiceFlags flags,
   uint32_t interfaceIndex,
   DNSServiceErrorType errorCode,
   const char *fullname,
   const char *hosttarget,
   uint16_t port, /* In network byte order */
   uint16_t txtLen,
   const unsigned char *txtRecord,
   void *context );

Data Types

See the Overview for header-level documentation.

DNSServiceErrorType

typedef int32_t DNSServiceErrorType;

DNSServiceFlags

typedef uint32_t DNSServiceFlags;

DNSServiceProtocol

typedef uint32_t DNSServiceProtocol;

TXTRecordRef

typedef union _TXTRecordRef_t {
   char PrivateData[16];
   char *ForceNaturalAlignment;
} TXTRecordRef;

Constants

See the Overview for header-level documentation.

Constants for specifying an interface index

   
#define kDNSServiceInterfaceIndexAny 0
#define kDNSServiceInterfaceIndexLocalOnly ((uint32_t)-1)
#define kDNSServiceInterfaceIndexP2P ((uint32_t)-3)
#define kDNSServiceInterfaceIndexUnicast ((uint32_t)-2)

Constants

kDNSServiceInterfaceIndexAny

Specific interface indexes are identified via a 32-bit unsigned integer returned by the if_nametoindex() family of calls.

If the client passes 0 for interface index, that means "do the right thing", which (at present) means, "if the name is in an mDNS local multicast domain (e.g. 'local.', '254.169.in-addr.arpa.', '{8,9,A,B}.E.F.ip6.arpa.') then multicast on all applicable interfaces, otherwise send via unicast to the appropriate DNS server." Normally, most clients will use 0 for interface index to automatically get the default sensible behaviour.

If the client passes a positive interface index, then for multicast names that indicates to do the operation only on that one interface. For unicast names the interface index is ignored unless kDNSServiceFlagsForceMulticast is also set.

If the client passes kDNSServiceInterfaceIndexLocalOnly when registering a service, then that service will be found *only* by other local clients on the same machine that are browsing using kDNSServiceInterfaceIndexLocalOnly or kDNSServiceInterfaceIndexAny. If a client has a 'private' service, accessible only to other processes running on the same machine, this allows the client to advertise that service in a way such that it does not inadvertently appear in service lists on all the other machines on the network.

If the client passes kDNSServiceInterfaceIndexLocalOnly when browsing then it will find *all* records registered on that same local machine. Clients explicitly wishing to discover *only* LocalOnly services can accomplish this by inspecting the interfaceIndex of each service reported to their DNSServiceBrowseReply() callback function, and discarding those where the interface index is not kDNSServiceInterfaceIndexLocalOnly.

kDNSServiceInterfaceIndexP2P is meaningful only in Browse, QueryRecord, and Resolve operations. It should not be used in other DNSService APIs.

- If kDNSServiceInterfaceIndexP2P is passed to DNSServiceBrowse or DNSServiceQueryRecord, it restricts the operation to P2P.

- If kDNSServiceInterfaceIndexP2P is passed to DNSServiceResolve, it is mapped internally to kDNSServiceInterfaceIndexAny, because resolving a P2P service may create and/or enable an interface whose index is not known a priori. The resolve callback will indicate the index of the interface via which the service can be accessed.

If applications pass kDNSServiceInterfaceIndexAny to DNSServiceBrowse or DNSServiceQueryRecord, they must set the kDNSServiceFlagsIncludeP2P flag to include P2P. In this case, if a service instance or the record being queried is found over P2P, the resulting ADD event will indicate kDNSServiceInterfaceIndexP2P as the interface index.

kDNSServiceInterfaceIndexLocalOnly

Specific interface indexes are identified via a 32-bit unsigned integer returned by the if_nametoindex() family of calls.

If the client passes 0 for interface index, that means "do the right thing", which (at present) means, "if the name is in an mDNS local multicast domain (e.g. 'local.', '254.169.in-addr.arpa.', '{8,9,A,B}.E.F.ip6.arpa.') then multicast on all applicable interfaces, otherwise send via unicast to the appropriate DNS server." Normally, most clients will use 0 for interface index to automatically get the default sensible behaviour.

If the client passes a positive interface index, then for multicast names that indicates to do the operation only on that one interface. For unicast names the interface index is ignored unless kDNSServiceFlagsForceMulticast is also set.

If the client passes kDNSServiceInterfaceIndexLocalOnly when registering a service, then that service will be found *only* by other local clients on the same machine that are browsing using kDNSServiceInterfaceIndexLocalOnly or kDNSServiceInterfaceIndexAny. If a client has a 'private' service, accessible only to other processes running on the same machine, this allows the client to advertise that service in a way such that it does not inadvertently appear in service lists on all the other machines on the network.

If the client passes kDNSServiceInterfaceIndexLocalOnly when browsing then it will find *all* records registered on that same local machine. Clients explicitly wishing to discover *only* LocalOnly services can accomplish this by inspecting the interfaceIndex of each service reported to their DNSServiceBrowseReply() callback function, and discarding those where the interface index is not kDNSServiceInterfaceIndexLocalOnly.

kDNSServiceInterfaceIndexP2P is meaningful only in Browse, QueryRecord, and Resolve operations. It should not be used in other DNSService APIs.

- If kDNSServiceInterfaceIndexP2P is passed to DNSServiceBrowse or DNSServiceQueryRecord, it restricts the operation to P2P.

- If kDNSServiceInterfaceIndexP2P is passed to DNSServiceResolve, it is mapped internally to kDNSServiceInterfaceIndexAny, because resolving a P2P service may create and/or enable an interface whose index is not known a priori. The resolve callback will indicate the index of the interface via which the service can be accessed.

If applications pass kDNSServiceInterfaceIndexAny to DNSServiceBrowse or DNSServiceQueryRecord, they must set the kDNSServiceFlagsIncludeP2P flag to include P2P. In this case, if a service instance or the record being queried is found over P2P, the resulting ADD event will indicate kDNSServiceInterfaceIndexP2P as the interface index.

kDNSServiceInterfaceIndexP2P

Specific interface indexes are identified via a 32-bit unsigned integer returned by the if_nametoindex() family of calls.

If the client passes 0 for interface index, that means "do the right thing", which (at present) means, "if the name is in an mDNS local multicast domain (e.g. 'local.', '254.169.in-addr.arpa.', '{8,9,A,B}.E.F.ip6.arpa.') then multicast on all applicable interfaces, otherwise send via unicast to the appropriate DNS server." Normally, most clients will use 0 for interface index to automatically get the default sensible behaviour.

If the client passes a positive interface index, then for multicast names that indicates to do the operation only on that one interface. For unicast names the interface index is ignored unless kDNSServiceFlagsForceMulticast is also set.

If the client passes kDNSServiceInterfaceIndexLocalOnly when registering a service, then that service will be found *only* by other local clients on the same machine that are browsing using kDNSServiceInterfaceIndexLocalOnly or kDNSServiceInterfaceIndexAny. If a client has a 'private' service, accessible only to other processes running on the same machine, this allows the client to advertise that service in a way such that it does not inadvertently appear in service lists on all the other machines on the network.

If the client passes kDNSServiceInterfaceIndexLocalOnly when browsing then it will find *all* records registered on that same local machine. Clients explicitly wishing to discover *only* LocalOnly services can accomplish this by inspecting the interfaceIndex of each service reported to their DNSServiceBrowseReply() callback function, and discarding those where the interface index is not kDNSServiceInterfaceIndexLocalOnly.

kDNSServiceInterfaceIndexP2P is meaningful only in Browse, QueryRecord, and Resolve operations. It should not be used in other DNSService APIs.

- If kDNSServiceInterfaceIndexP2P is passed to DNSServiceBrowse or DNSServiceQueryRecord, it restricts the operation to P2P.

- If kDNSServiceInterfaceIndexP2P is passed to DNSServiceResolve, it is mapped internally to kDNSServiceInterfaceIndexAny, because resolving a P2P service may create and/or enable an interface whose index is not known a priori. The resolve callback will indicate the index of the interface via which the service can be accessed.

If applications pass kDNSServiceInterfaceIndexAny to DNSServiceBrowse or DNSServiceQueryRecord, they must set the kDNSServiceFlagsIncludeP2P flag to include P2P. In this case, if a service instance or the record being queried is found over P2P, the resulting ADD event will indicate kDNSServiceInterfaceIndexP2P as the interface index.

kDNSServiceInterfaceIndexUnicast

Specific interface indexes are identified via a 32-bit unsigned integer returned by the if_nametoindex() family of calls.

If the client passes 0 for interface index, that means "do the right thing", which (at present) means, "if the name is in an mDNS local multicast domain (e.g. 'local.', '254.169.in-addr.arpa.', '{8,9,A,B}.E.F.ip6.arpa.') then multicast on all applicable interfaces, otherwise send via unicast to the appropriate DNS server." Normally, most clients will use 0 for interface index to automatically get the default sensible behaviour.

If the client passes a positive interface index, then for multicast names that indicates to do the operation only on that one interface. For unicast names the interface index is ignored unless kDNSServiceFlagsForceMulticast is also set.

If the client passes kDNSServiceInterfaceIndexLocalOnly when registering a service, then that service will be found *only* by other local clients on the same machine that are browsing using kDNSServiceInterfaceIndexLocalOnly or kDNSServiceInterfaceIndexAny. If a client has a 'private' service, accessible only to other processes running on the same machine, this allows the client to advertise that service in a way such that it does not inadvertently appear in service lists on all the other machines on the network.

If the client passes kDNSServiceInterfaceIndexLocalOnly when browsing then it will find *all* records registered on that same local machine. Clients explicitly wishing to discover *only* LocalOnly services can accomplish this by inspecting the interfaceIndex of each service reported to their DNSServiceBrowseReply() callback function, and discarding those where the interface index is not kDNSServiceInterfaceIndexLocalOnly.

kDNSServiceInterfaceIndexP2P is meaningful only in Browse, QueryRecord, and Resolve operations. It should not be used in other DNSService APIs.

- If kDNSServiceInterfaceIndexP2P is passed to DNSServiceBrowse or DNSServiceQueryRecord, it restricts the operation to P2P.

- If kDNSServiceInterfaceIndexP2P is passed to DNSServiceResolve, it is mapped internally to kDNSServiceInterfaceIndexAny, because resolving a P2P service may create and/or enable an interface whose index is not known a priori. The resolve callback will indicate the index of the interface via which the service can be accessed.

If applications pass kDNSServiceInterfaceIndexAny to DNSServiceBrowse or DNSServiceQueryRecord, they must set the kDNSServiceFlagsIncludeP2P flag to include P2P. In this case, if a service instance or the record being queried is found over P2P, the resulting ADD event will indicate kDNSServiceInterfaceIndexP2P as the interface index.

Miscellaneous Defines

   
#define _DNS_SD_H 3792700
#define kDNSServiceMaxDomainName 1009
#define kDNSServiceMaxServiceName 64
#define kDNSServiceProperty_DaemonVersion "DaemonVersion"

Constants

_DNS_SD_H

_DNS_SD_H contains the mDNSResponder version number for this header file, formatted as follows:

Major part of the build number * 10000 +

minor part of the build number * 100

For example, OS X v10.4.9 has mDNSResponder-108.4, which would be represented as version 1080400. This allows C code to do simple greater-than and less-than comparisons: e.g. an application that requires the DNSServiceGetProperty() call (new in mDNSResponder-126) can check:

#if _DNS_SD_H+0 >= 1260000

... some C code that calls DNSServiceGetProperty() ...

#endif

The version defined in this header file symbol allows for compile-time checking, so that C code building with earlier versions of the header file can avoid compile errors trying to use functions that aren't even defined in those earlier versions. Similar checks may also be performed at run-time:

=> weak linking -- to avoid link failures if run with an earlier version of the library that's missing some desired symbol, or

=> DNSServiceGetProperty(DaemonVersion) -- to verify whether the running daemon ("system service" on Windows) meets some required minimum functionality level.

kDNSServiceMaxDomainName

Maximum length, in bytes, of a domain name represented as an *escaped* C-String including the final trailing dot, and the C-String terminating NULL at the end.

kDNSServiceMaxServiceName

Maximum length, in bytes, of a service name represented as a literal C-String, including the terminating NULL at the end.

kDNSServiceProperty_DaemonVersion

When requesting kDNSServiceProperty_DaemonVersion, the result pointer must point to a 32-bit unsigned integer, and the size parameter must be set to sizeof(uint32_t).

On return, the 32-bit unsigned integer contains the version number, formatted as follows:

Major part of the build number * 10000 +

minor part of the build number * 100

For example, OS X v10.4.9 has mDNSResponder-108.4, which would be represented as version 1080400. This allows applications to do simple greater-than and less-than comparisons: e.g. an application that requires at least mDNSResponder-108.4 can check:

if (version >= 1080400) ...

Example usage:

uint32_t version;

uint32_t size = sizeof(version);

DNSServiceErrorType err = DNSServiceGetProperty(kDNSServiceProperty_DaemonVersion, &version, &size);

if (!err) printf("Bonjour version is %d.%d\n", version / 10000, version / 100 % 100);

DNS Classes

enum {
   kDNSServiceClass_IN = 1 /* Internet */
};

DNS Error Codes

enum {
   kDNSServiceErr_NoError = 0,
   kDNSServiceErr_Unknown = -65537, /* 0xFFFE FFFF */
   kDNSServiceErr_NoSuchName = -65538,
   kDNSServiceErr_NoMemory = -65539,
   kDNSServiceErr_BadParam = -65540,
   kDNSServiceErr_BadReference = -65541,
   kDNSServiceErr_BadState = -65542,
   kDNSServiceErr_BadFlags = -65543,
   kDNSServiceErr_Unsupported = -65544,
   kDNSServiceErr_NotInitialized = -65545,
   kDNSServiceErr_AlreadyRegistered = -65547,
   kDNSServiceErr_NameConflict = -65548,
   kDNSServiceErr_Invalid = -65549,
   kDNSServiceErr_Firewall = -65550,
   kDNSServiceErr_Incompatible = -65551, /* client library incompatible with daemon */
   kDNSServiceErr_BadInterfaceIndex = -65552,
   kDNSServiceErr_Refused = -65553,
   kDNSServiceErr_NoSuchRecord = -65554,
   kDNSServiceErr_NoAuth = -65555,
   kDNSServiceErr_NoSuchKey = -65556,
   kDNSServiceErr_NATTraversal = -65557,
   kDNSServiceErr_DoubleNAT = -65558,
   kDNSServiceErr_BadTime = -65559, /* Codes up to here existed in Tiger */
   kDNSServiceErr_BadSig = -65560,
   kDNSServiceErr_BadKey = -65561,
   kDNSServiceErr_Transient = -65562,
   kDNSServiceErr_ServiceNotRunning = -65563, /* Background daemon not running */
   kDNSServiceErr_NATPortMappingUnsupported = -65564, /* NAT doesn't support NAT-PMP or UPnP */
   kDNSServiceErr_NATPortMappingDisabled = -65565, /* NAT supports NAT-PMP or UPnP but it's disabled by the administrator */
   kDNSServiceErr_NoRouter = -65566, /* No router currently configured (probably no network connectivity) */
   kDNSServiceErr_PollingMode = -65567,
   kDNSServiceErr_Timeout = -65568  /* mDNS Error codes are in the range
   */
};

DNS Service Types

enum {
   kDNSServiceType_A = 1, /* Host address. */
   kDNSServiceType_NS = 2, /* Authoritative server. */
   kDNSServiceType_MD = 3, /* Mail destination. */
   kDNSServiceType_MF = 4, /* Mail forwarder. */
   kDNSServiceType_CNAME = 5, /* Canonical name. */
   kDNSServiceType_SOA = 6, /* Start of authority zone. */
   kDNSServiceType_MB = 7, /* Mailbox domain name. */
   kDNSServiceType_MG = 8, /* Mail group member. */
   kDNSServiceType_MR = 9, /* Mail rename name. */
   kDNSServiceType_NULL = 10, /* Null resource record. */
   kDNSServiceType_WKS = 11, /* Well known service. */
   kDNSServiceType_PTR = 12, /* Domain name pointer. */
   kDNSServiceType_HINFO = 13, /* Host information. */
   kDNSServiceType_MINFO = 14, /* Mailbox information. */
   kDNSServiceType_MX = 15, /* Mail routing information. */
   kDNSServiceType_TXT = 16, /* One or more text strings (NOT "zero or more..."). */
   kDNSServiceType_RP = 17, /* Responsible person. */
   kDNSServiceType_AFSDB = 18, /* AFS cell database. */
   kDNSServiceType_X25 = 19, /* X_25 calling address. */
   kDNSServiceType_ISDN = 20, /* ISDN calling address. */
   kDNSServiceType_RT = 21, /* Router. */
   kDNSServiceType_NSAP = 22, /* NSAP address. */
   kDNSServiceType_NSAP_PTR = 23, /* Reverse NSAP lookup (deprecated). */
   kDNSServiceType_SIG = 24, /* Security signature. */
   kDNSServiceType_KEY = 25, /* Security key. */
   kDNSServiceType_PX = 26, /* X.400 mail mapping. */
   kDNSServiceType_GPOS = 27, /* Geographical position (withdrawn). */
   kDNSServiceType_AAAA = 28, /* IPv6 Address. */
   kDNSServiceType_LOC = 29, /* Location Information. */
   kDNSServiceType_NXT = 30, /* Next domain (security). */
   kDNSServiceType_EID = 31, /* Endpoint identifier. */
   kDNSServiceType_NIMLOC = 32, /* Nimrod Locator. */
   kDNSServiceType_SRV = 33, /* Server Selection. */
   kDNSServiceType_ATMA = 34, /* ATM Address */
   kDNSServiceType_NAPTR = 35, /* Naming Authority PoinTeR */
   kDNSServiceType_KX = 36, /* Key Exchange */
   kDNSServiceType_CERT = 37, /* Certification record */
   kDNSServiceType_A6 = 38, /* IPv6 Address (deprecated) */
   kDNSServiceType_DNAME = 39, /* Non-terminal DNAME (for IPv6) */
   kDNSServiceType_SINK = 40, /* Kitchen sink (experimental) */
   kDNSServiceType_OPT = 41, /* EDNS0 option (meta-RR) */
   kDNSServiceType_APL = 42, /* Address Prefix List */
   kDNSServiceType_DS = 43, /* Delegation Signer */
   kDNSServiceType_SSHFP = 44, /* SSH Key Fingerprint */
   kDNSServiceType_IPSECKEY = 45, /* IPSECKEY */
   kDNSServiceType_RRSIG = 46, /* RRSIG */
   kDNSServiceType_NSEC = 47, /* Denial of Existence */
   kDNSServiceType_DNSKEY = 48, /* DNSKEY */
   kDNSServiceType_DHCID = 49, /* DHCP Client Identifier */
   kDNSServiceType_NSEC3 = 50, /* Hashed Authenticated Denial of Existence */
   kDNSServiceType_NSEC3PARAM = 51, /* Hashed Authenticated Denial of Existence */
   kDNSServiceType_HIP = 55, /* Host Identity Protocol */
   kDNSServiceType_SPF = 99, /* Sender Policy Framework for E-Mail */
   kDNSServiceType_UINFO = 100, /* IANA-Reserved */
   kDNSServiceType_UID = 101, /* IANA-Reserved */
   kDNSServiceType_GID = 102, /* IANA-Reserved */
   kDNSServiceType_UNSPEC = 103, /* IANA-Reserved */
   kDNSServiceType_TKEY = 249, /* Transaction key */
   kDNSServiceType_TSIG = 250, /* Transaction signature. */
   kDNSServiceType_IXFR = 251, /* Incremental zone transfer. */
   kDNSServiceType_AXFR = 252, /* Transfer zone of authority. */
   kDNSServiceType_MAILB = 253, /* Transfer mailbox records. */
   kDNSServiceType_MAILA = 254, /* Transfer mail agent records. */
   kDNSServiceType_ANY = 255 /* Wildcard match. */
};

DNSServiceNATPortMappingCreate Protocols

enum {
   kDNSServiceProtocol_IPv4 = 0x01,
   kDNSServiceProtocol_IPv6 = 0x02,
   /* 0x04 and x08 reserved for future internetwork protocols */
   kDNSServiceProtocol_UDP = 0x10,
   kDNSServiceProtocol_TCP = 0x20 /* 0x40 and x80 reserved for future transport protocols,
   e.g. SCTP [RFC 2960]
   * or DCCP [RFC 4340]. If future NAT gateways are created that support port
   * mappings for these protocols,
   new constants will be defined here.
   */
};

General flags

enum {
   /*! MoreComing indicates to a callback that at least one more result is
   */
   kDNSServiceFlagsMoreComing = 0x1,
   /*! Flags for domain enumeration and browse/query reply callbacks.
   */
   kDNSServiceFlagsAdd = 0x2,
   /*! Flags for domain enumeration and browse/query reply callbacks.
   */
   kDNSServiceFlagsDefault = 0x4,
   /*! Flag for specifying renaming behavior on name conflict when registering
   */
   kDNSServiceFlagsNoAutoRename = 0x8,
   /*! Flag for registering individual records on a connected
   */
   kDNSServiceFlagsShared = 0x10,
   /*! Flag for registering individual records on a connected
   */
   kDNSServiceFlagsUnique = 0x20,
   /*! Flags for specifying domain enumeration type in DNSServiceEnumerateDomains.
   */
   kDNSServiceFlagsBrowseDomains = 0x40,
   /*! Flags for specifying domain enumeration type in DNSServiceEnumerateDomains.
   */
   kDNSServiceFlagsRegistrationDomains = 0x80,
   /*! Flag for creating a long-lived unicast query for the DNSServiceQueryRecord call.
   */
   kDNSServiceFlagsLongLivedQuery = 0x100,
   /*! Flag for creating a record for which we will answer remote queries
   */
   kDNSServiceFlagsAllowRemoteQuery = 0x200,
   /*! Flag for signifying that a query or registration should be performed exclusively via multicast
   */
   kDNSServiceFlagsForceMulticast = 0x400,
   /*! Flag for signifying a "stronger" variant of an operation.
   */
   kDNSServiceFlagsForce = 0x800,
   /*! Flag for returning intermediate results.
   */
   kDNSServiceFlagsReturnIntermediates = 0x1000,
   /*! A service registered with the NonBrowsable flag set can be resolved using
   */
   kDNSServiceFlagsNonBrowsable = 0x2000,
   /*! For efficiency,
   clients that perform many concurrent operations may want to use a
   */
   kDNSServiceFlagsShareConnection = 0x4000,
   /*!
   */
   kDNSServiceFlagsSuppressUnusable = 0x8000,
   /*!
   */
   kDNSServiceFlagsTimeout = 0x10000,
   /*!
   */
   kDNSServiceFlagsIncludeP2P = 0x20000,
   /*!
   */
   kDNSServiceFlagsWakeOnResolve = 0x40000,
   /*!
   */
   kDNSServiceFlagsBackgroundTrafficClass = 0x80000,
   /*!
   */
   kDNSServiceFlagsIncludeAWDL = 0x100000
};

Constants

kDNSServiceFlagsMoreComing

MoreComing indicates to a callback that at least one more result is queued and will be delivered following immediately after this one. When the MoreComing flag is set, applications should not immediately update their UI, because this can result in a great deal of ugly flickering on the screen, and can waste a great deal of CPU time repeatedly updating the screen with content that is then immediately erased, over and over. Applications should wait until MoreComing is not set, and then update their UI when no more changes are imminent.

When MoreComing is not set, that doesn't mean there will be no more answers EVER, just that there are no more answers immediately available right now at this instant. If more answers become available in the future they will be delivered as usual.

kDNSServiceFlagsAdd

Flags for domain enumeration and browse/query reply callbacks. An enumeration callback with the "Add" flag NOT set indicates a "Remove", i.e. the domain is no longer valid.

kDNSServiceFlagsDefault

Flags for domain enumeration and browse/query reply callbacks. "Default" applies only to enumeration and is only valid in conjunction with "Add".

kDNSServiceFlagsNoAutoRename

Flag for specifying renaming behavior on name conflict when registering non-shared records. By default, name conflicts are automatically handled by renaming the service. NoAutoRename overrides this behavior - with this flag set, name conflicts will result in a callback. The NoAutorename flag is only valid if a name is explicitly specified when registering a service (i.e. the default name is not used.)

kDNSServiceFlagsShared

Flag for registering individual records on a connected DNSServiceRef. Shared indicates that there may be multiple records with this name on the network (e.g. PTR records).

kDNSServiceFlagsUnique

Flag for registering individual records on a connected DNSServiceRef. Unique indicates that the record's name is to be unique on the network (e.g. SRV records).

kDNSServiceFlagsBrowseDomains

Flags for specifying domain enumeration type in DNSServiceEnumerateDomains. BrowseDomains enumerates domains recommended for browsing.

kDNSServiceFlagsRegistrationDomains

Flags for specifying domain enumeration type in DNSServiceEnumerateDomains. RegistrationDomains enumerates domains recommended for registration.

kDNSServiceFlagsLongLivedQuery

Flag for creating a long-lived unicast query for the DNSServiceQueryRecord call.

kDNSServiceFlagsAllowRemoteQuery

Flag for creating a record for which we will answer remote queries (queries from hosts more than one hop away; hosts not directly connected to the local link).

kDNSServiceFlagsForceMulticast

Flag for signifying that a query or registration should be performed exclusively via multicast DNS, even for a name in a domain (e.g. foo.apple.com.) that would normally imply unicast DNS.

kDNSServiceFlagsForce

Flag for signifying a "stronger" variant of an operation. Currently defined only for DNSServiceReconfirmRecord(), where it forces a record to be removed from the cache immediately, instead of querying for a few seconds before concluding that the record is no longer valid and then removing it. This flag should be used with caution because if a service browsing PTR record is indeed still valid on the network, forcing its removal will result in a user-interface flap -- the discovered service instance will disappear, and then re-appear moments later.

kDNSServiceFlagsReturnIntermediates

Flag for returning intermediate results. For example, if a query results in an authoritative NXDomain (name does not exist) then that result is returned to the client. However the query is not implicitly cancelled -- it remains active and if the answer subsequently changes (e.g. because a VPN tunnel is subsequently established) then that positive result will still be returned to the client. Similarly, if a query results in a CNAME record, then in addition to following the CNAME referral, the intermediate CNAME result is also returned to the client. When this flag is not set, NXDomain errors are not returned, and CNAME records are followed silently without informing the client of the intermediate steps. (In earlier builds this flag was briefly called kDNSServiceFlagsReturnCNAME)

kDNSServiceFlagsNonBrowsable

A service registered with the NonBrowsable flag set can be resolved using DNSServiceResolve(), but will not be discoverable using DNSServiceBrowse(). This is for cases where the name is actually a GUID; it is found by other means; there is no end-user benefit to browsing to find a long list of opaque GUIDs. Using the NonBrowsable flag creates SRV+TXT without the cost of also advertising an associated PTR record.

kDNSServiceFlagsShareConnection

For efficiency, clients that perform many concurrent operations may want to use a single Unix Domain Socket connection with the background daemon, instead of having a separate connection for each independent operation. To use this mode, clients first call DNSServiceCreateConnection(&MainRef) to initialize the main DNSServiceRef. For each subsequent operation that is to share that same connection, the client copies the MainRef, and then passes the address of that copy, setting the ShareConnection flag to tell the library that this DNSServiceRef is not a typical uninitialized DNSServiceRef; it's a copy of an existing DNSServiceRef whose connection information should be reused.

For example:

DNSServiceErrorType error;

DNSServiceRef MainRef;

error = DNSServiceCreateConnection(&MainRef);

if (error) ...

DNSServiceRef BrowseRef = MainRef; // Important: COPY the primary DNSServiceRef first...

error = DNSServiceBrowse(&BrowseRef, kDNSServiceFlagsShareConnection, ...); // then use the copy

if (error) ...

...

DNSServiceRefDeallocate(BrowseRef); // Terminate the browse operation

DNSServiceRefDeallocate(MainRef); // Terminate the shared connection

Notes:

1. Collective kDNSServiceFlagsMoreComing flag When callbacks are invoked using a shared DNSServiceRef, the kDNSServiceFlagsMoreComing flag applies collectively to *all* active operations sharing the same parent DNSServiceRef. If the MoreComing flag is set it means that there are more results queued on this parent DNSServiceRef, but not necessarily more results for this particular callback function. The implication of this for client programmers is that when a callback is invoked with the MoreComing flag set, the code should update its internal data structures with the new result, and set a variable indicating that its UI needs to be updated. Then, later when a callback is eventually invoked with the MoreComing flag not set, the code should update *all* stale UI elements related to that shared parent DNSServiceRef that need updating, not just the UI elements related to the particular callback that happened to be the last one to be invoked.

2. Canceling operations and kDNSServiceFlagsMoreComing Whenever you cancel any operation for which you had deferred UI updates waiting because of a kDNSServiceFlagsMoreComing flag, you should perform those deferred UI updates. This is because, after cancelling the operation, you can no longer wait for a callback *without* MoreComing set, to tell you do perform your deferred UI updates (the operation has been canceled, so there will be no more callbacks). An implication of the collective kDNSServiceFlagsMoreComing flag for shared connections is that this guideline applies more broadly -- any time you cancel an operation on a shared connection, you should perform all deferred UI updates for all operations sharing that connection. This is because the MoreComing flag might have been referring to events coming for the operation you canceled, which will now not be coming because the operation has been canceled.

3. Only share DNSServiceRef's created with DNSServiceCreateConnection Calling DNSServiceCreateConnection(&ref) creates a special shareable DNSServiceRef. DNSServiceRef's created by other calls like DNSServiceBrowse() or DNSServiceResolve() cannot be shared by copying them and using kDNSServiceFlagsShareConnection.

4. Don't Double-Deallocate Calling DNSServiceRefDeallocate(ref) for a particular operation's DNSServiceRef terminates just that operation. Calling DNSServiceRefDeallocate(ref) for the main shared DNSServiceRef (the parent DNSServiceRef, originally created by DNSServiceCreateConnection(&ref)) automatically terminates the shared connection and all operations that were still using it. After doing this, DO NOT then attempt to deallocate any remaining subordinate DNSServiceRef's. The memory used by those subordinate DNSServiceRef's has already been freed, so any attempt to do a DNSServiceRefDeallocate (or any other operation) on them will result in accesses to freed memory, leading to crashes or other equally undesirable results.

5. Thread Safety The dns_sd.h API does not presuppose any particular threading model, and consequently does no locking of its own (which would require linking some specific threading library). If client code calls API routines on the same DNSServiceRef concurrently from multiple threads, it is the client's responsibility to use a mutext lock or take similar appropriate precautions to serialize those calls.

kDNSServiceFlagsSuppressUnusable

This flag is meaningful only in DNSServiceQueryRecord which suppresses unusable queries on the wire. If "hostname" is a wide-area unicast DNS hostname (i.e. not a ".local." name) but this host has no routable IPv6 address, then the call will not try to look up IPv6 addresses for "hostname", since any addresses it found would be unlikely to be of any use anyway. Similarly, if this host has no routable IPv4 address, the call will not try to look up IPv4 addresses for "hostname".

kDNSServiceFlagsTimeout

When kDNServiceFlagsTimeout is passed to DNSServiceQueryRecord or DNSServiceGetAddrInfo, the query is stopped after a certain number of seconds have elapsed. The time at which the query will be stopped is determined by the system and cannot be configured by the user. The query will be stopped irrespective of whether a response was given earlier or not. When the query is stopped, the callback will be called with an error code of kDNSServiceErr_Timeout and a NULL sockaddr will be returned for DNSServiceGetAddrInfo and zero length rdata will be returned for DNSServiceQueryRecord.

kDNSServiceFlagsIncludeP2P

Include P2P interfaces when kDNSServiceInterfaceIndexAny is specified. By default, specifying kDNSServiceInterfaceIndexAny does not include P2P interfaces.

kDNSServiceFlagsWakeOnResolve

This flag is meaningful only in DNSServiceResolve. When set, it tries to send a magic packet to wake up the client.

kDNSServiceFlagsBackgroundTrafficClass

This flag is meaningful in DNSServiceBrowse, DNSServiceGetAddrInfo, DNSServiceQueryRecord, and DNSServiceResolve. When set, it uses the background traffic class for packets that service the request.

kDNSServiceFlagsIncludeAWDL

Include AWDL interface when kDNSServiceInterfaceIndexAny is specified.