2 * Copyright (c) 2002 Apple Computer, Inc. All rights reserved.
4 * @APPLE_LICENSE_HEADER_START@
6 * The contents of this file constitute Original Code as defined in and
7 * are subject to the Apple Public Source License Version 1.1 (the
8 * "License"). You may not use this file except in compliance with the
9 * License. Please obtain a copy of the License at
10 * http://www.apple.com/publicsource and read it before using this file.
12 * This Original Code and all software distributed under the License are
13 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
14 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
15 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
17 * License for the specific language governing rights and limitations
20 * @APPLE_LICENSE_HEADER_END@
23 #ifndef __DNS_SERVICE_DISCOVERY_H
24 #define __DNS_SERVICE_DISCOVERY_H
26 #include <mach/mach_types.h>
28 #include <sys/types.h>
29 #include <sys/socket.h>
30 #include <sys/cdefs.h>
32 #include <netinet/in.h>
34 #include <AvailabilityMacros.h>
38 /* Opaque internal data type */
39 typedef struct _dns_service_discovery_t
* dns_service_discovery_ref
;
41 /* possible reply flags values */
44 kDNSServiceDiscoveryNoFlags
= 0,
45 kDNSServiceDiscoveryMoreRepliesImmediately
= 1 << 0,
49 /* possible error code values */
52 kDNSServiceDiscoveryWaiting
= 1,
53 kDNSServiceDiscoveryNoError
= 0,
54 // mDNS Error codes are in the range
55 // FFFE FF00 (-65792) to FFFE FFFF (-65537)
56 kDNSServiceDiscoveryUnknownErr
= -65537, // 0xFFFE FFFF
57 kDNSServiceDiscoveryNoSuchNameErr
= -65538,
58 kDNSServiceDiscoveryNoMemoryErr
= -65539,
59 kDNSServiceDiscoveryBadParamErr
= -65540,
60 kDNSServiceDiscoveryBadReferenceErr
= -65541,
61 kDNSServiceDiscoveryBadStateErr
= -65542,
62 kDNSServiceDiscoveryBadFlagsErr
= -65543,
63 kDNSServiceDiscoveryUnsupportedErr
= -65544,
64 kDNSServiceDiscoveryNotInitializedErr
= -65545,
65 kDNSServiceDiscoveryNoCache
= -65546,
66 kDNSServiceDiscoveryAlreadyRegistered
= -65547,
67 kDNSServiceDiscoveryNameConflict
= -65548,
68 kDNSServiceDiscoveryInvalid
= -65549,
69 kDNSServiceDiscoveryMemFree
= -65792 // 0xFFFE FF00
70 } DNSServiceRegistrationReplyErrorType
;
72 typedef uint32_t DNSRecordReference
;
76 @function DNSServiceResolver_handleReply
77 @description This function should be called with the Mach message sent
78 to the port returned by the call to DNSServiceResolverResolve.
79 The reply message will be interpreted and will result in a
80 call to the specified callout function.
81 @param replyMsg The Mach message.
83 void DNSServiceDiscovery_handleReply(void *replyMsg
);
85 /* Service Registration */
87 typedef void (*DNSServiceRegistrationReply
) (
88 DNSServiceRegistrationReplyErrorType errorCode
,
93 @function DNSServiceRegistrationCreate
94 @description Register a named service with DNS Service Discovery
95 @param name The name of this service instance (e.g. "Steve's Printer")
96 @param regtype The service type (e.g. "_printer._tcp." -- see
97 RFC 2782 (DNS SRV) and <http://www.iana.org/assignments/port-numbers>)
98 @param domain The domain in which to register the service (e.g. "apple.com.")
99 @param port The local port on which this service is being offered (in network byte order)
100 @param txtRecord Optional protocol-specific additional information
101 @param callBack The DNSServiceRegistrationReply function to be called
102 @param context A user specified context which will be passed to the callout function.
103 @result A dns_registration_t
105 dns_service_discovery_ref DNSServiceRegistrationCreate
111 const char *txtRecord
,
112 DNSServiceRegistrationReply callBack
,
114 ) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED
;
116 /***************************************************************************/
117 /* DNS Domain Enumeration */
121 DNSServiceDomainEnumerationReplyAddDomain
, // Domain found
122 DNSServiceDomainEnumerationReplyAddDomainDefault
, // Domain found (and should be selected by default)
123 DNSServiceDomainEnumerationReplyRemoveDomain
, // Domain has been removed from network
124 } DNSServiceDomainEnumerationReplyResultType
;
128 DNSServiceDiscoverReplyFlagsFinished
,
129 DNSServiceDiscoverReplyFlagsMoreComing
,
130 } DNSServiceDiscoveryReplyFlags
;
132 typedef void (*DNSServiceDomainEnumerationReply
) (
133 DNSServiceDomainEnumerationReplyResultType resultType
, // One of DNSServiceDomainEnumerationReplyResultType
134 const char *replyDomain
,
135 DNSServiceDiscoveryReplyFlags flags
, // DNS Service Discovery reply flags information
140 @function DNSServiceDomainEnumerationCreate
141 @description Asynchronously create a DNS Domain Enumerator
142 @param registrationDomains A boolean indicating whether you are looking
143 for recommended registration domains
144 (e.g. equivalent to the AppleTalk zone list in the AppleTalk Control Panel)
145 or recommended browsing domains
146 (e.g. equivalent to the AppleTalk zone list in the Chooser).
147 @param callBack The function to be called when domains are found or removed
148 @param context A user specified context which will be passed to the callout function.
149 @result A dns_registration_t
151 dns_service_discovery_ref DNSServiceDomainEnumerationCreate
153 int registrationDomains
,
154 DNSServiceDomainEnumerationReply callBack
,
156 ) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED
;
158 /***************************************************************************/
159 /* DNS Service Browser */
163 DNSServiceBrowserReplyAddInstance
, // Instance of service found
164 DNSServiceBrowserReplyRemoveInstance
// Instance has been removed from network
165 } DNSServiceBrowserReplyResultType
;
167 typedef void (*DNSServiceBrowserReply
) (
168 DNSServiceBrowserReplyResultType resultType
, // One of DNSServiceBrowserReplyResultType
169 const char *replyName
,
170 const char *replyType
,
171 const char *replyDomain
,
172 DNSServiceDiscoveryReplyFlags flags
, // DNS Service Discovery reply flags information
177 @function DNSServiceBrowserCreate
178 @description Asynchronously create a DNS Service browser
179 @param regtype The type of service
180 @param domain The domain in which to find the service
181 @param callBack The function to be called when service instances are found or removed
182 @param context A user specified context which will be passed to the callout function.
183 @result A dns_registration_t
185 dns_service_discovery_ref DNSServiceBrowserCreate
189 DNSServiceBrowserReply callBack
,
191 ) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED
;
193 /***************************************************************************/
194 /* Resolver requests */
196 typedef void (*DNSServiceResolverReply
) (
197 struct sockaddr
*interface
, // Needed for scoped addresses like link-local
198 struct sockaddr
*address
,
199 const char *txtRecord
,
200 DNSServiceDiscoveryReplyFlags flags
, // DNS Service Discovery reply flags information
205 @function DNSServiceResolverResolve
206 @description Resolved a named instance of a service to its address, port, and
207 (optionally) other demultiplexing information contained in the TXT record.
208 @param name The name of the service instance
209 @param regtype The type of service
210 @param domain The domain in which to find the service
211 @param callBack The DNSServiceResolverReply function to be called when the specified
212 address has been resolved.
213 @param context A user specified context which will be passed to the callout function.
214 @result A dns_registration_t
217 dns_service_discovery_ref DNSServiceResolverResolve
222 DNSServiceResolverReply callBack
,
224 ) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED
;
226 /***************************************************************************/
227 /* Mach port accessor and deallocation */
230 @function DNSServiceDiscoveryMachPort
231 @description Returns the mach port for a dns_service_discovery_ref
232 @param registration A dns_service_discovery_ref as returned from DNSServiceRegistrationCreate
233 @result A mach reply port which will be sent messages as appropriate.
234 These messages should be passed to the DNSServiceDiscovery_handleReply
235 function. A NULL value indicates that no address was
236 specified or some other error occurred which prevented the
237 resolution from being started.
239 mach_port_t
DNSServiceDiscoveryMachPort(dns_service_discovery_ref dnsServiceDiscovery
) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED
;
242 @function DNSServiceDiscoveryDeallocate
243 @description Deallocates the DNS Service Discovery type / closes the connection to the server
244 @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a creation or enumeration call
247 void DNSServiceDiscoveryDeallocate(dns_service_discovery_ref dnsServiceDiscovery
) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED
;
249 /***************************************************************************/
250 /* Registration updating */
254 @function DNSServiceRegistrationAddRecord
255 @description Request that the mDNS Responder add the DNS Record of a specific type
256 @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call
257 @param rrtype A standard DNS Resource Record Type, from http://www.iana.org/assignments/dns-parameters
258 @param rdlen Length of the data
259 @param rdata Opaque binary Resource Record data, up to 64 kB.
260 @param ttl time to live for the added record.
261 @result DNSRecordReference An opaque reference that can be passed to the update and remove record calls. If an error occurs, this value will be zero or negative
263 DNSRecordReference
DNSServiceRegistrationAddRecord(dns_service_discovery_ref dnsServiceDiscovery
, uint16_t rrtype
, uint16_t rdlen
, const char *rdata
, uint32_t ttl
)
264 AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED
;
267 @function DNSServiceRegistrationUpdateRecord
268 @description Request that the mDNS Responder add the DNS Record of a specific type
269 @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call
270 @param dnsRecordReference A dnsRecordReference as returned from a DNSServiceRegistrationAddRecord call
271 @param rdlen Length of the data
272 @param rdata Opaque binary Resource Record data, up to 64 kB.
273 @param ttl time to live for the updated record.
274 @result DNSServiceRegistrationReplyErrorType If an error occurs, this value will be non zero
276 DNSServiceRegistrationReplyErrorType
DNSServiceRegistrationUpdateRecord(dns_service_discovery_ref ref
, DNSRecordReference reference
, uint16_t rdlen
, const char *rdata
, uint32_t ttl
)
277 AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED
;
280 @function DNSServiceRegistrationRemoveRecord
281 @description Request that the mDNS Responder remove the DNS Record(s) of a specific type
282 @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call
283 @param dnsRecordReference A dnsRecordReference as returned from a DNSServiceRegistrationAddRecord call
284 @result DNSServiceRegistrationReplyErrorType If an error occurs, this value will be non zero
286 DNSServiceRegistrationReplyErrorType
DNSServiceRegistrationRemoveRecord(dns_service_discovery_ref ref
, DNSRecordReference reference
)
287 AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED
;
292 #endif /* __DNS_SERVICE_DISCOVERY_H */