]> git.saurik.com Git - apple/libinfo.git/blob - mdns.subproj/DNSServiceDiscovery.h
Libinfo-221.tar.gz
[apple/libinfo.git] / mdns.subproj / DNSServiceDiscovery.h
1 /*
2 * Copyright (c) 2002 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
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.
11 *
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
18 * under the License.
19 *
20 * @APPLE_LICENSE_HEADER_END@
21 */
22
23 #ifndef __DNS_SERVICE_DISCOVERY_H
24 #define __DNS_SERVICE_DISCOVERY_H
25
26 #include <mach/mach_types.h>
27
28 #include <sys/types.h>
29 #include <sys/socket.h>
30 #include <sys/cdefs.h>
31
32 #include <netinet/in.h>
33
34 #include <AvailabilityMacros.h>
35
36 __BEGIN_DECLS
37
38 /* Opaque internal data type */
39 typedef struct _dns_service_discovery_t * dns_service_discovery_ref;
40
41 /* possible reply flags values */
42
43 enum {
44 kDNSServiceDiscoveryNoFlags = 0,
45 kDNSServiceDiscoveryMoreRepliesImmediately = 1 << 0,
46 };
47
48
49 /* possible error code values */
50 typedef enum
51 {
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;
71
72 typedef uint32_t DNSRecordReference;
73
74
75 /*!
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.
82 */
83 void DNSServiceDiscovery_handleReply(void *replyMsg);
84
85 /* Service Registration */
86
87 typedef void (*DNSServiceRegistrationReply) (
88 DNSServiceRegistrationReplyErrorType errorCode,
89 void *context
90 );
91
92 /*!
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
104 */
105 dns_service_discovery_ref DNSServiceRegistrationCreate
106 (
107 const char *name,
108 const char *regtype,
109 const char *domain,
110 uint16_t port,
111 const char *txtRecord,
112 DNSServiceRegistrationReply callBack,
113 void *context
114 ) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED;
115
116 /***************************************************************************/
117 /* DNS Domain Enumeration */
118
119 typedef enum
120 {
121 DNSServiceDomainEnumerationReplyAddDomain, // Domain found
122 DNSServiceDomainEnumerationReplyAddDomainDefault, // Domain found (and should be selected by default)
123 DNSServiceDomainEnumerationReplyRemoveDomain, // Domain has been removed from network
124 } DNSServiceDomainEnumerationReplyResultType;
125
126 typedef enum
127 {
128 DNSServiceDiscoverReplyFlagsFinished,
129 DNSServiceDiscoverReplyFlagsMoreComing,
130 } DNSServiceDiscoveryReplyFlags;
131
132 typedef void (*DNSServiceDomainEnumerationReply) (
133 DNSServiceDomainEnumerationReplyResultType resultType, // One of DNSServiceDomainEnumerationReplyResultType
134 const char *replyDomain,
135 DNSServiceDiscoveryReplyFlags flags, // DNS Service Discovery reply flags information
136 void *context
137 );
138
139 /*!
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
150 */
151 dns_service_discovery_ref DNSServiceDomainEnumerationCreate
152 (
153 int registrationDomains,
154 DNSServiceDomainEnumerationReply callBack,
155 void *context
156 ) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED;
157
158 /***************************************************************************/
159 /* DNS Service Browser */
160
161 typedef enum
162 {
163 DNSServiceBrowserReplyAddInstance, // Instance of service found
164 DNSServiceBrowserReplyRemoveInstance // Instance has been removed from network
165 } DNSServiceBrowserReplyResultType;
166
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
173 void *context
174 );
175
176 /*!
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
184 */
185 dns_service_discovery_ref DNSServiceBrowserCreate
186 (
187 const char *regtype,
188 const char *domain,
189 DNSServiceBrowserReply callBack,
190 void *context
191 ) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED;
192
193 /***************************************************************************/
194 /* Resolver requests */
195
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
201 void *context
202 );
203
204 /*!
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
215 */
216
217 dns_service_discovery_ref DNSServiceResolverResolve
218 (
219 const char *name,
220 const char *regtype,
221 const char *domain,
222 DNSServiceResolverReply callBack,
223 void *context
224 ) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED;
225
226 /***************************************************************************/
227 /* Mach port accessor and deallocation */
228
229 /*!
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.
238 */
239 mach_port_t DNSServiceDiscoveryMachPort(dns_service_discovery_ref dnsServiceDiscovery) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED;
240
241 /*!
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
245 @result void
246 */
247 void DNSServiceDiscoveryDeallocate(dns_service_discovery_ref dnsServiceDiscovery) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED;
248
249 /***************************************************************************/
250 /* Registration updating */
251
252
253 /*!
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
262 */
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;
265
266 /*!
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
275 */
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;
278
279 /*!
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
285 */
286 DNSServiceRegistrationReplyErrorType DNSServiceRegistrationRemoveRecord(dns_service_discovery_ref ref, DNSRecordReference reference)
287 AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED;
288
289
290 __END_DECLS
291
292 #endif /* __DNS_SERVICE_DISCOVERY_H */