1 | /* -*- Mode: C; tab-width: 4 -*- |
---|
2 | * |
---|
3 | * Copyright (c) 2002, 2004, 2006, 2011 Apple Inc. All rights reserved. |
---|
4 | * |
---|
5 | * Licensed under the Apache License, Version 2.0 (the "License"); |
---|
6 | * you may not use this file except in compliance with the License. |
---|
7 | * You may obtain a copy of the License at |
---|
8 | * |
---|
9 | * http://www.apache.org/licenses/LICENSE-2.0 |
---|
10 | * |
---|
11 | * Unless required by applicable law or agreed to in writing, software |
---|
12 | * distributed under the License is distributed on an "AS IS" BASIS, |
---|
13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
---|
14 | * See the License for the specific language governing permissions and |
---|
15 | * limitations under the License. |
---|
16 | */ |
---|
17 | |
---|
18 | /*! @header DNS Service Discovery (Deprecated Mach-based API) |
---|
19 | * |
---|
20 | * @discussion This section describes the functions, callbacks, and data structures that |
---|
21 | * make up the DNS Service Discovery API. |
---|
22 | * |
---|
23 | * The DNS Service Discovery API is part of Bonjour, Apple's implementation of |
---|
24 | * zero-configuration networking (ZEROCONF). |
---|
25 | * |
---|
26 | * Bonjour allows you to register a network service, such as a |
---|
27 | * printer or file server, so that it can be found by name or browsed |
---|
28 | * for by service type and domain. Using Bonjour, applications can |
---|
29 | * discover what services are available on the network, along with |
---|
30 | * all necessary access information-such as name, IP address, and port |
---|
31 | * number-for a given service. |
---|
32 | * |
---|
33 | * In effect, Bonjour combines the functions of a local DNS server |
---|
34 | * and AppleTalk. Bonjour allows applications to provide user-friendly printer |
---|
35 | * and server browsing, among other things, over standard IP networks. |
---|
36 | * This behavior is a result of combining protocols such as multicast and DNS |
---|
37 | * to add new functionality to the network (such as multicast DNS). |
---|
38 | * |
---|
39 | * Bonjour gives applications easy access to services over local IP |
---|
40 | * networks without requiring the service or the application to support |
---|
41 | * an AppleTalk or a Netbeui stack, and without requiring a DNS server |
---|
42 | * for the local network. |
---|
43 | * |
---|
44 | * Note that this API was deprecated in Mac OS X 10.3, and replaced |
---|
45 | * by the portable cross-platform /usr/include/dns_sd.h API. |
---|
46 | */ |
---|
47 | |
---|
48 | #ifndef __DNS_SERVICE_DISCOVERY_H |
---|
49 | #define __DNS_SERVICE_DISCOVERY_H |
---|
50 | |
---|
51 | #include <mach/mach_types.h> |
---|
52 | |
---|
53 | #include <sys/types.h> |
---|
54 | #include <sys/socket.h> |
---|
55 | #include <sys/cdefs.h> |
---|
56 | |
---|
57 | #include <netinet/in.h> |
---|
58 | |
---|
59 | #include <AvailabilityMacros.h> |
---|
60 | |
---|
61 | __BEGIN_DECLS |
---|
62 | |
---|
63 | /* Opaque internal data type */ |
---|
64 | typedef struct _dns_service_discovery_t * dns_service_discovery_ref; |
---|
65 | |
---|
66 | /* possible reply flags values */ |
---|
67 | |
---|
68 | enum { |
---|
69 | kDNSServiceDiscoveryNoFlags = 0, |
---|
70 | kDNSServiceDiscoveryMoreRepliesImmediately = 1 << 0, |
---|
71 | }; |
---|
72 | |
---|
73 | |
---|
74 | /* possible error code values */ |
---|
75 | typedef enum |
---|
76 | { |
---|
77 | kDNSServiceDiscoveryWaiting = 1, |
---|
78 | kDNSServiceDiscoveryNoError = 0, |
---|
79 | // mDNS Error codes are in the range |
---|
80 | // FFFE FF00 (-65792) to FFFE FFFF (-65537) |
---|
81 | kDNSServiceDiscoveryUnknownErr = -65537, // 0xFFFE FFFF |
---|
82 | kDNSServiceDiscoveryNoSuchNameErr = -65538, |
---|
83 | kDNSServiceDiscoveryNoMemoryErr = -65539, |
---|
84 | kDNSServiceDiscoveryBadParamErr = -65540, |
---|
85 | kDNSServiceDiscoveryBadReferenceErr = -65541, |
---|
86 | kDNSServiceDiscoveryBadStateErr = -65542, |
---|
87 | kDNSServiceDiscoveryBadFlagsErr = -65543, |
---|
88 | kDNSServiceDiscoveryUnsupportedErr = -65544, |
---|
89 | kDNSServiceDiscoveryNotInitializedErr = -65545, |
---|
90 | kDNSServiceDiscoveryNoCache = -65546, |
---|
91 | kDNSServiceDiscoveryAlreadyRegistered = -65547, |
---|
92 | kDNSServiceDiscoveryNameConflict = -65548, |
---|
93 | kDNSServiceDiscoveryInvalid = -65549, |
---|
94 | kDNSServiceDiscoveryMemFree = -65792 // 0xFFFE FF00 |
---|
95 | } DNSServiceRegistrationReplyErrorType; |
---|
96 | |
---|
97 | typedef uint32_t DNSRecordReference; |
---|
98 | |
---|
99 | |
---|
100 | /*! |
---|
101 | @function DNSServiceResolver_handleReply |
---|
102 | @discussion This function should be called with the Mach message sent |
---|
103 | to the port returned by the call to DNSServiceResolverResolve. |
---|
104 | The reply message will be interpreted and will result in a |
---|
105 | call to the specified callout function. |
---|
106 | @param replyMsg The Mach message. |
---|
107 | */ |
---|
108 | void DNSServiceDiscovery_handleReply(void *replyMsg); |
---|
109 | |
---|
110 | /* Service Registration */ |
---|
111 | |
---|
112 | typedef void (*DNSServiceRegistrationReply)( |
---|
113 | DNSServiceRegistrationReplyErrorType errorCode, |
---|
114 | void *context |
---|
115 | ); |
---|
116 | |
---|
117 | /*! |
---|
118 | @function DNSServiceRegistrationCreate |
---|
119 | @discussion Register a named service with DNS Service Discovery |
---|
120 | @param name The name of this service instance (e.g. "Steve's Printer") |
---|
121 | @param regtype The service type (e.g. "_printer._tcp." -- see |
---|
122 | RFC 2782 (DNS SRV) and <http://www.iana.org/assignments/port-numbers>) |
---|
123 | @param domain The domain in which to register the service (e.g. "apple.com.") |
---|
124 | @param port The local port on which this service is being offered (in network byte order) |
---|
125 | @param txtRecord Optional protocol-specific additional information |
---|
126 | @param callBack The DNSServiceRegistrationReply function to be called |
---|
127 | @param context A user specified context which will be passed to the callout function. |
---|
128 | @result A dns_registration_t |
---|
129 | */ |
---|
130 | dns_service_discovery_ref DNSServiceRegistrationCreate |
---|
131 | ( |
---|
132 | const char *name, |
---|
133 | const char *regtype, |
---|
134 | const char *domain, |
---|
135 | uint16_t port, |
---|
136 | const char *txtRecord, |
---|
137 | DNSServiceRegistrationReply callBack, |
---|
138 | void *context |
---|
139 | ) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; |
---|
140 | |
---|
141 | /***************************************************************************/ |
---|
142 | /* DNS Domain Enumeration */ |
---|
143 | |
---|
144 | typedef enum |
---|
145 | { |
---|
146 | DNSServiceDomainEnumerationReplyAddDomain, // Domain found |
---|
147 | DNSServiceDomainEnumerationReplyAddDomainDefault, // Domain found (and should be selected by default) |
---|
148 | DNSServiceDomainEnumerationReplyRemoveDomain, // Domain has been removed from network |
---|
149 | } DNSServiceDomainEnumerationReplyResultType; |
---|
150 | |
---|
151 | typedef enum |
---|
152 | { |
---|
153 | DNSServiceDiscoverReplyFlagsFinished, |
---|
154 | DNSServiceDiscoverReplyFlagsMoreComing, |
---|
155 | } DNSServiceDiscoveryReplyFlags; |
---|
156 | |
---|
157 | typedef void (*DNSServiceDomainEnumerationReply)( |
---|
158 | DNSServiceDomainEnumerationReplyResultType resultType, // One of DNSServiceDomainEnumerationReplyResultType |
---|
159 | const char *replyDomain, |
---|
160 | DNSServiceDiscoveryReplyFlags flags, // DNS Service Discovery reply flags information |
---|
161 | void *context |
---|
162 | ); |
---|
163 | |
---|
164 | /*! |
---|
165 | @function DNSServiceDomainEnumerationCreate |
---|
166 | @discussion Asynchronously create a DNS Domain Enumerator |
---|
167 | @param registrationDomains A boolean indicating whether you are looking |
---|
168 | for recommended registration domains |
---|
169 | (e.g. equivalent to the AppleTalk zone list in the AppleTalk Control Panel) |
---|
170 | or recommended browsing domains |
---|
171 | (e.g. equivalent to the AppleTalk zone list in the Chooser). |
---|
172 | @param callBack The function to be called when domains are found or removed |
---|
173 | @param context A user specified context which will be passed to the callout function. |
---|
174 | @result A dns_registration_t |
---|
175 | */ |
---|
176 | dns_service_discovery_ref DNSServiceDomainEnumerationCreate |
---|
177 | ( |
---|
178 | int registrationDomains, |
---|
179 | DNSServiceDomainEnumerationReply callBack, |
---|
180 | void *context |
---|
181 | ) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; |
---|
182 | |
---|
183 | /***************************************************************************/ |
---|
184 | /* DNS Service Browser */ |
---|
185 | |
---|
186 | typedef enum |
---|
187 | { |
---|
188 | DNSServiceBrowserReplyAddInstance, // Instance of service found |
---|
189 | DNSServiceBrowserReplyRemoveInstance // Instance has been removed from network |
---|
190 | } DNSServiceBrowserReplyResultType; |
---|
191 | |
---|
192 | typedef void (*DNSServiceBrowserReply)( |
---|
193 | DNSServiceBrowserReplyResultType resultType, // One of DNSServiceBrowserReplyResultType |
---|
194 | const char *replyName, |
---|
195 | const char *replyType, |
---|
196 | const char *replyDomain, |
---|
197 | DNSServiceDiscoveryReplyFlags flags, // DNS Service Discovery reply flags information |
---|
198 | void *context |
---|
199 | ); |
---|
200 | |
---|
201 | /*! |
---|
202 | @function DNSServiceBrowserCreate |
---|
203 | @discussion Asynchronously create a DNS Service browser |
---|
204 | @param regtype The type of service |
---|
205 | @param domain The domain in which to find the service |
---|
206 | @param callBack The function to be called when service instances are found or removed |
---|
207 | @param context A user specified context which will be passed to the callout function. |
---|
208 | @result A dns_registration_t |
---|
209 | */ |
---|
210 | dns_service_discovery_ref DNSServiceBrowserCreate |
---|
211 | ( |
---|
212 | const char *regtype, |
---|
213 | const char *domain, |
---|
214 | DNSServiceBrowserReply callBack, |
---|
215 | void *context |
---|
216 | ) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; |
---|
217 | |
---|
218 | /***************************************************************************/ |
---|
219 | /* Resolver requests */ |
---|
220 | |
---|
221 | typedef void (*DNSServiceResolverReply)( |
---|
222 | struct sockaddr *interface, // Needed for scoped addresses like link-local |
---|
223 | struct sockaddr *address, |
---|
224 | const char *txtRecord, |
---|
225 | DNSServiceDiscoveryReplyFlags flags, // DNS Service Discovery reply flags information |
---|
226 | void *context |
---|
227 | ); |
---|
228 | |
---|
229 | /*! |
---|
230 | @function DNSServiceResolverResolve |
---|
231 | @discussion Resolved a named instance of a service to its address, port, and |
---|
232 | (optionally) other demultiplexing information contained in the TXT record. |
---|
233 | @param name The name of the service instance |
---|
234 | @param regtype The type of service |
---|
235 | @param domain The domain in which to find the service |
---|
236 | @param callBack The DNSServiceResolverReply function to be called when the specified |
---|
237 | address has been resolved. |
---|
238 | @param context A user specified context which will be passed to the callout function. |
---|
239 | @result A dns_registration_t |
---|
240 | */ |
---|
241 | |
---|
242 | dns_service_discovery_ref DNSServiceResolverResolve |
---|
243 | ( |
---|
244 | const char *name, |
---|
245 | const char *regtype, |
---|
246 | const char *domain, |
---|
247 | DNSServiceResolverReply callBack, |
---|
248 | void *context |
---|
249 | ) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; |
---|
250 | |
---|
251 | /***************************************************************************/ |
---|
252 | /* Mach port accessor and deallocation */ |
---|
253 | |
---|
254 | /*! |
---|
255 | @function DNSServiceDiscoveryMachPort |
---|
256 | @discussion Returns the mach port for a dns_service_discovery_ref |
---|
257 | @param registration A dns_service_discovery_ref as returned from DNSServiceRegistrationCreate |
---|
258 | @result A mach reply port which will be sent messages as appropriate. |
---|
259 | These messages should be passed to the DNSServiceDiscovery_handleReply |
---|
260 | function. A NULL value indicates that no address was |
---|
261 | specified or some other error occurred which prevented the |
---|
262 | resolution from being started. |
---|
263 | */ |
---|
264 | mach_port_t DNSServiceDiscoveryMachPort(dns_service_discovery_ref dnsServiceDiscovery) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; |
---|
265 | |
---|
266 | /*! |
---|
267 | @function DNSServiceDiscoveryDeallocate |
---|
268 | @discussion Deallocates the DNS Service Discovery type / closes the connection to the server |
---|
269 | @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a creation or enumeration call |
---|
270 | @result void |
---|
271 | */ |
---|
272 | void DNSServiceDiscoveryDeallocate(dns_service_discovery_ref dnsServiceDiscovery) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; |
---|
273 | |
---|
274 | /***************************************************************************/ |
---|
275 | /* Registration updating */ |
---|
276 | |
---|
277 | |
---|
278 | /*! |
---|
279 | @function DNSServiceRegistrationAddRecord |
---|
280 | @discussion Request that the mDNS Responder add the DNS Record of a specific type |
---|
281 | @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call |
---|
282 | @param rrtype A standard DNS Resource Record Type, from http://www.iana.org/assignments/dns-parameters |
---|
283 | @param rdlen Length of the data |
---|
284 | @param rdata Opaque binary Resource Record data, up to 64 kB. |
---|
285 | @param ttl time to live for the added record. |
---|
286 | @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 |
---|
287 | */ |
---|
288 | DNSRecordReference DNSServiceRegistrationAddRecord(dns_service_discovery_ref dnsServiceDiscovery, uint16_t rrtype, uint16_t rdlen, const char *rdata, uint32_t ttl) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; |
---|
289 | |
---|
290 | /*! |
---|
291 | @function DNSServiceRegistrationUpdateRecord |
---|
292 | @discussion Request that the mDNS Responder add the DNS Record of a specific type |
---|
293 | @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call |
---|
294 | @param dnsRecordReference A dnsRecordReference as returned from a DNSServiceRegistrationAddRecord call |
---|
295 | @param rdlen Length of the data |
---|
296 | @param rdata Opaque binary Resource Record data, up to 64 kB. |
---|
297 | @param ttl time to live for the updated record. |
---|
298 | @result DNSServiceRegistrationReplyErrorType If an error occurs, this value will be non zero |
---|
299 | */ |
---|
300 | DNSServiceRegistrationReplyErrorType DNSServiceRegistrationUpdateRecord(dns_service_discovery_ref ref, DNSRecordReference reference, uint16_t rdlen, const char *rdata, uint32_t ttl) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; |
---|
301 | |
---|
302 | /*! |
---|
303 | @function DNSServiceRegistrationRemoveRecord |
---|
304 | @discussion Request that the mDNS Responder remove the DNS Record(s) of a specific type |
---|
305 | @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call |
---|
306 | @param dnsRecordReference A dnsRecordReference as returned from a DNSServiceRegistrationAddRecord call |
---|
307 | @result DNSServiceRegistrationReplyErrorType If an error occurs, this value will be non zero |
---|
308 | */ |
---|
309 | DNSServiceRegistrationReplyErrorType DNSServiceRegistrationRemoveRecord(dns_service_discovery_ref ref, DNSRecordReference reference) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; |
---|
310 | |
---|
311 | |
---|
312 | __END_DECLS |
---|
313 | |
---|
314 | #endif /* __DNS_SERVICE_DISCOVERY_H */ |
---|