2 * Copyright (c) 2003-2004, Apple Computer, Inc. All rights reserved.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
7 * 1. Redistributions of source code must retain the above copyright notice,
8 * this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright notice,
10 * this list of conditions and the following disclaimer in the documentation
11 * and/or other materials provided with the distribution.
12 * 3. Neither the name of Apple Computer, Inc. ("Apple") nor the names of its
13 * contributors may be used to endorse or promote products derived from this
14 * software without specific prior written permission.
16 * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY
17 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19 * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY
20 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35 /* standard calling convention under Win32 is __stdcall */
37 #define DNSSD_API __stdcall
42 #if defined(__FreeBSD_version) && (__FreeBSD_version < 500000)
43 /* stdint.h does not exist on FreeBSD 4.x; its types are defined in sys/types.h instead */
44 #include <sys/types.h>
45 #elif defined(__sun__)
46 #include <sys/types.h>
50 #define bzero(a, b) memset(a, 0, b)
51 typedef UINT8
uint8_t;
53 typedef UINT16
uint16_t;
54 typedef INT16
int16_t;
55 typedef UINT32
uint32_t;
56 typedef INT32
int32_t;
61 /* DNSServiceRef, DNSRecordRef
63 * Opaque internal data types.
64 * Note: client is responsible for serializing access to these structures if
65 * they are shared between concurrent threads.
68 typedef struct _DNSServiceRef_t
*DNSServiceRef
;
69 typedef struct _DNSRecordRef_t
*DNSRecordRef
;
71 /* General flags used in functions defined below */
74 kDNSServiceFlagsMoreComing
= 0x1,
75 /* MoreComing indicates to a callback that at least one more result is
76 * queued and will be delivered following immediately after this one.
77 * Applications should not update their UI to display browse
78 * results when the MoreComing flag is set, because this would
79 * result in a great deal of ugly flickering on the screen.
80 * Applications should instead wait until until MoreComing is not set,
81 * and then update their UI.
82 * When MoreComing is not set, that doesn't mean there will be no more
83 * answers EVER, just that there are no more answers immediately
84 * available right now at this instant. If more answers become available
85 * in the future they will be delivered as usual.
88 kDNSServiceFlagsAdd
= 0x2,
89 kDNSServiceFlagsDefault
= 0x4,
90 /* Flags for domain enumeration and browse/query reply callbacks.
91 * "Default" applies only to enumeration and is only valid in
92 * conjuction with "Add". An enumeration callback with the "Add"
93 * flag NOT set indicates a "Remove", i.e. the domain is no longer
97 kDNSServiceFlagsNoAutoRename
= 0x8,
98 /* Flag for specifying renaming behavior on name conflict when registering
99 * non-shared records. By default, name conflicts are automatically handled
100 * by renaming the service. NoAutoRename overrides this behavior - with this
101 * flag set, name conflicts will result in a callback. The NoAutorename flag
102 * is only valid if a name is explicitly specified when registering a service
103 * (i.e. the default name is not used.)
106 kDNSServiceFlagsShared
= 0x10,
107 kDNSServiceFlagsUnique
= 0x20,
108 /* Flag for registering individual records on a connected
109 * DNSServiceRef. Shared indicates that there may be multiple records
110 * with this name on the network (e.g. PTR records). Unique indicates that the
111 * record's name is to be unique on the network (e.g. SRV records).
114 kDNSServiceFlagsBrowseDomains
= 0x40,
115 kDNSServiceFlagsRegistrationDomains
= 0x80,
116 /* Flags for specifying domain enumeration type in DNSServiceEnumerateDomains.
117 * BrowseDomains enumerates domains recommended for browsing, RegistrationDomains
118 * enumerates domains recommended for registration.
121 kDNSServiceFlagsLongLivedQuery
= 0x100,
122 /* Flag for creating a long-lived unicast query for the DNSServiceQueryRecord call. */
124 kDNSServiceFlagsAllowRemoteQuery
= 0x200,
125 /* Flag for creating a record for which we will answer remote queries
126 * (queries from hosts more than one hop away; hosts not directly connected to the local link).
129 kDNSServiceFlagsForceMulticast
= 0x400
130 /* Flag for signifying that a query or registration should be performed exclusively via multicast DNS,
131 * even for a name in a domain (e.g. foo.apple.com.) that would normally imply unicast DNS.
136 * The values for DNS Classes and Types are listed in RFC 1035, and are available
137 * on every OS in its DNS header file. Unfortunately every OS does not have the
138 * same header file containing DNS Class and Type constants, and the names of
139 * the constants are not consistent. For example, BIND 8 uses "T_A",
140 * BIND 9 uses "ns_t_a", Windows uses "DNS_TYPE_A", etc.
141 * For this reason, these constants are also listed here, so that code using
142 * the DNS-SD programming APIs can use these constants, so that the same code
143 * can compile on all our supported platforms.
148 kDNSServiceClass_IN
= 1 /* Internet */
153 kDNSServiceType_A
= 1, /* Host address. */
154 kDNSServiceType_NS
= 2, /* Authoritative server. */
155 kDNSServiceType_MD
= 3, /* Mail destination. */
156 kDNSServiceType_MF
= 4, /* Mail forwarder. */
157 kDNSServiceType_CNAME
= 5, /* Canonical name. */
158 kDNSServiceType_SOA
= 6, /* Start of authority zone. */
159 kDNSServiceType_MB
= 7, /* Mailbox domain name. */
160 kDNSServiceType_MG
= 8, /* Mail group member. */
161 kDNSServiceType_MR
= 9, /* Mail rename name. */
162 kDNSServiceType_NULL
= 10, /* Null resource record. */
163 kDNSServiceType_WKS
= 11, /* Well known service. */
164 kDNSServiceType_PTR
= 12, /* Domain name pointer. */
165 kDNSServiceType_HINFO
= 13, /* Host information. */
166 kDNSServiceType_MINFO
= 14, /* Mailbox information. */
167 kDNSServiceType_MX
= 15, /* Mail routing information. */
168 kDNSServiceType_TXT
= 16, /* One or more text strings. */
169 kDNSServiceType_RP
= 17, /* Responsible person. */
170 kDNSServiceType_AFSDB
= 18, /* AFS cell database. */
171 kDNSServiceType_X25
= 19, /* X_25 calling address. */
172 kDNSServiceType_ISDN
= 20, /* ISDN calling address. */
173 kDNSServiceType_RT
= 21, /* Router. */
174 kDNSServiceType_NSAP
= 22, /* NSAP address. */
175 kDNSServiceType_NSAP_PTR
= 23, /* Reverse NSAP lookup (deprecated). */
176 kDNSServiceType_SIG
= 24, /* Security signature. */
177 kDNSServiceType_KEY
= 25, /* Security key. */
178 kDNSServiceType_PX
= 26, /* X.400 mail mapping. */
179 kDNSServiceType_GPOS
= 27, /* Geographical position (withdrawn). */
180 kDNSServiceType_AAAA
= 28, /* Ip6 Address. */
181 kDNSServiceType_LOC
= 29, /* Location Information. */
182 kDNSServiceType_NXT
= 30, /* Next domain (security). */
183 kDNSServiceType_EID
= 31, /* Endpoint identifier. */
184 kDNSServiceType_NIMLOC
= 32, /* Nimrod Locator. */
185 kDNSServiceType_SRV
= 33, /* Server Selection. */
186 kDNSServiceType_ATMA
= 34, /* ATM Address */
187 kDNSServiceType_NAPTR
= 35, /* Naming Authority PoinTeR */
188 kDNSServiceType_KX
= 36, /* Key Exchange */
189 kDNSServiceType_CERT
= 37, /* Certification record */
190 kDNSServiceType_A6
= 38, /* IPv6 address (deprecates AAAA) */
191 kDNSServiceType_DNAME
= 39, /* Non-terminal DNAME (for IPv6) */
192 kDNSServiceType_SINK
= 40, /* Kitchen sink (experimentatl) */
193 kDNSServiceType_OPT
= 41, /* EDNS0 option (meta-RR) */
194 kDNSServiceType_TKEY
= 249, /* Transaction key */
195 kDNSServiceType_TSIG
= 250, /* Transaction signature. */
196 kDNSServiceType_IXFR
= 251, /* Incremental zone transfer. */
197 kDNSServiceType_AXFR
= 252, /* Transfer zone of authority. */
198 kDNSServiceType_MAILB
= 253, /* Transfer mailbox records. */
199 kDNSServiceType_MAILA
= 254, /* Transfer mail agent records. */
200 kDNSServiceType_ANY
= 255 /* Wildcard match. */
204 /* possible error code values */
207 kDNSServiceErr_NoError
= 0,
208 kDNSServiceErr_Unknown
= -65537, /* 0xFFFE FFFF */
209 kDNSServiceErr_NoSuchName
= -65538,
210 kDNSServiceErr_NoMemory
= -65539,
211 kDNSServiceErr_BadParam
= -65540,
212 kDNSServiceErr_BadReference
= -65541,
213 kDNSServiceErr_BadState
= -65542,
214 kDNSServiceErr_BadFlags
= -65543,
215 kDNSServiceErr_Unsupported
= -65544,
216 kDNSServiceErr_NotInitialized
= -65545,
217 kDNSServiceErr_AlreadyRegistered
= -65547,
218 kDNSServiceErr_NameConflict
= -65548,
219 kDNSServiceErr_Invalid
= -65549,
220 kDNSServiceErr_Firewall
= -65550,
221 kDNSServiceErr_Incompatible
= -65551, /* client library incompatible with daemon */
222 kDNSServiceErr_BadInterfaceIndex
= -65552,
223 kDNSServiceErr_Refused
= -65553,
224 kDNSServiceErr_NoSuchRecord
= -65554,
225 kDNSServiceErr_NoAuth
= -65555,
226 kDNSServiceErr_NoSuchKey
= -65556,
227 kDNSServiceErr_NATTraversal
= -65557,
228 kDNSServiceErr_DoubleNAT
= -65558,
229 kDNSServiceErr_BadTime
= -65559
230 /* mDNS Error codes are in the range
231 * FFFE FF00 (-65792) to FFFE FFFF (-65537) */
235 /* Maximum length, in bytes, of a service name represented as a */
236 /* literal C-String, including the terminating NULL at the end. */
238 #define kDNSServiceMaxServiceName 64
240 /* Maximum length, in bytes, of a domain name represented as an *escaped* C-String */
241 /* including the final trailing dot, and the C-String terminating NULL at the end. */
243 #define kDNSServiceMaxDomainName 1005
246 * Notes on DNS Name Escaping
248 * "Why is kDNSServiceMaxDomainName 1005, when the maximum legal domain name is 255 bytes?"
250 * All strings used in DNS-SD are UTF-8 strings.
251 * With few exceptions, most are also escaped using standard DNS escaping rules:
253 * '\\' represents a single literal '\' in the name
254 * '\.' represents a single literal '.' in the name
255 * '\ddd', where ddd is a three-digit decimal value from 000 to 255,
256 * represents a single literal byte with that value.
257 * A bare unescaped '.' is a label separator, marking a boundary between domain and subdomain.
259 * The exceptions, that do not use escaping, are the routines where the full
260 * DNS name of a resource is broken, for convenience, into servicename/regtype/domain.
261 * In these routines, the "servicename" is NOT escaped. It does not need to be, since
262 * it is, by definition, just a single literal string. Any characters in that string
263 * represent exactly what they are. The "regtype" portion is, technically speaking,
264 * escaped, but since legal regtypes are only allowed to contain letters, digits,
265 * and hyphens, there is nothing to escape, so the issue is moot. The "domain"
266 * portion is also escaped, though most domains in use on the public Internet
267 * today, like regtypes, don't contain any characters that need to be escaped.
268 * As DNS-SD becomes more popular, rich-text domains for service discovery will
269 * become common, so software should be written to cope with domains with escaping.
271 * The servicename may be up to 63 bytes of UTF-8 text (not counting the C-String
272 * terminating NULL at the end). The regtype is of the form _service._tcp or
273 * _service._udp, where the "service" part is 1-14 characters, which may be
274 * letters, digits, or hyphens. The domain part of the three-part name may be
275 * any legal domain, providing that the resulting servicename+regtype+domain
276 * name does not exceed 255 bytes.
278 * For most software, these issues are transparent. When browsing, the discovered
279 * servicenames should simply be displayed as-is. When resolving, the discovered
280 * servicename/regtype/domain are simply passed unchanged to DNSServiceResolve().
281 * When a DNSServiceResolve() succeeds, the returned fullname is already in
282 * the correct format to pass to standard system DNS APIs such as res_query().
283 * For converting from servicename/regtype/domain to a single properly-escaped
284 * full DNS name, the helper function DNSServiceConstructFullName() is provided.
286 * The following (highly contrived) example illustrates the escaping process.
287 * Suppose you have an service called "Dr. Smith\Dr. Johnson", of type "_ftp._tcp"
288 * in subdomain "4th. Floor" of subdomain "Building 2" of domain "apple.com."
289 * The full (escaped) DNS name of this service's SRV record would be:
290 * Dr\.\032Smith\\Dr\.\032Johnson._ftp._tcp.4th\.\032Floor.Building\0322.apple.com.
295 * Constants for specifying an interface index
297 * Specific interface indexes are identified via a 32-bit unsigned integer returned
298 * by the if_nametoindex() family of calls.
300 * If the client passes 0 for interface index, that means "do the right thing",
301 * which (at present) means, "if the name is in an mDNS local multicast domain
302 * (e.g. 'local.', '254.169.in-addr.arpa.', '0.8.E.F.ip6.arpa.') then multicast
303 * on all applicable interfaces, otherwise send via unicast to the appropriate
304 * DNS server." Normally, most clients will use 0 for interface index to
305 * automatically get the default sensible behaviour.
307 * If the client passes a positive interface index, then for multicast names that
308 * indicates to do the operation only on that one interface. For unicast names the
309 * interface index is ignored unless kDNSServiceFlagsForceMulticast is also set.
311 * If the client passes kDNSServiceInterfaceIndexLocalOnly when registering
312 * a service, then that service will be found *only* by other local clients
313 * on the same machine that are browsing using kDNSServiceInterfaceIndexLocalOnly
314 * or kDNSServiceInterfaceIndexAny.
315 * If a client has a 'private' service, accessible only to other processes
316 * running on the same machine, this allows the client to advertise that service
317 * in a way such that it does not inadvertently appear in service lists on
318 * all the other machines on the network.
320 * If the client passes kDNSServiceInterfaceIndexLocalOnly when browsing
321 * then it will find *all* records registered on that same local machine.
322 * Clients explicitly wishing to discover *only* LocalOnly services can
323 * accomplish this by inspecting the interfaceIndex of each service reported
324 * to their DNSServiceBrowseReply() callback function, and discarding those
325 * where the interface index is not kDNSServiceInterfaceIndexLocalOnly.
328 #define kDNSServiceInterfaceIndexAny 0
329 #define kDNSServiceInterfaceIndexLocalOnly ( (uint32_t) -1 )
332 typedef uint32_t DNSServiceFlags
;
333 typedef int32_t DNSServiceErrorType
;
336 /*********************************************************************************************
338 * Unix Domain Socket access, DNSServiceRef deallocation, and data processing functions
340 *********************************************************************************************/
343 /* DNSServiceRefSockFD()
345 * Access underlying Unix domain socket for an initialized DNSServiceRef.
346 * The DNS Service Discovery implmementation uses this socket to communicate between
347 * the client and the mDNSResponder daemon. The application MUST NOT directly read from
348 * or write to this socket. Access to the socket is provided so that it can be used as a
349 * run loop source, or in a select() loop: when data is available for reading on the socket,
350 * DNSServiceProcessResult() should be called, which will extract the daemon's reply from
351 * the socket, and pass it to the appropriate application callback. By using a run loop or
352 * select(), results from the daemon can be processed asynchronously. Without using these
353 * constructs, DNSServiceProcessResult() will block until the response from the daemon arrives.
354 * The client is responsible for ensuring that the data on the socket is processed in a timely
355 * fashion - the daemon may terminate its connection with a client that does not clear its
358 * sdRef: A DNSServiceRef initialized by any of the DNSService calls.
360 * return value: The DNSServiceRef's underlying socket descriptor, or -1 on
364 int DNSSD_API
DNSServiceRefSockFD(DNSServiceRef sdRef
);
367 /* DNSServiceProcessResult()
369 * Read a reply from the daemon, calling the appropriate application callback. This call will
370 * block until the daemon's response is received. Use DNSServiceRefSockFD() in
371 * conjunction with a run loop or select() to determine the presence of a response from the
372 * server before calling this function to process the reply without blocking. Call this function
373 * at any point if it is acceptable to block until the daemon's response arrives. Note that the
374 * client is responsible for ensuring that DNSServiceProcessResult() is called whenever there is
375 * a reply from the daemon - the daemon may terminate its connection with a client that does not
376 * process the daemon's responses.
378 * sdRef: A DNSServiceRef initialized by any of the DNSService calls
379 * that take a callback parameter.
381 * return value: Returns kDNSServiceErr_NoError on success, otherwise returns
382 * an error code indicating the specific failure that occurred.
385 DNSServiceErrorType DNSSD_API
DNSServiceProcessResult(DNSServiceRef sdRef
);
388 /* DNSServiceRefDeallocate()
390 * Terminate a connection with the daemon and free memory associated with the DNSServiceRef.
391 * Any services or records registered with this DNSServiceRef will be deregistered. Any
392 * Browse, Resolve, or Query operations called with this reference will be terminated.
394 * Note: If the reference's underlying socket is used in a run loop or select() call, it should
395 * be removed BEFORE DNSServiceRefDeallocate() is called, as this function closes the reference's
398 * Note: If the reference was initialized with DNSServiceCreateConnection(), any DNSRecordRefs
399 * created via this reference will be invalidated by this call - the resource records are
400 * deregistered, and their DNSRecordRefs may not be used in subsequent functions. Similarly,
401 * if the reference was initialized with DNSServiceRegister, and an extra resource record was
402 * added to the service via DNSServiceAddRecord(), the DNSRecordRef created by the Add() call
403 * is invalidated when this function is called - the DNSRecordRef may not be used in subsequent
406 * Note: This call is to be used only with the DNSServiceRef defined by this API. It is
407 * not compatible with dns_service_discovery_ref objects defined in the legacy Mach-based
408 * DNSServiceDiscovery.h API.
410 * sdRef: A DNSServiceRef initialized by any of the DNSService calls.
414 void DNSSD_API
DNSServiceRefDeallocate(DNSServiceRef sdRef
);
417 /*********************************************************************************************
421 *********************************************************************************************/
423 /* DNSServiceEnumerateDomains()
425 * Asynchronously enumerate domains available for browsing and registration.
427 * The enumeration MUST be cancelled via DNSServiceRefDeallocate() when no more domains
430 * Note that the names returned are (like all of DNS-SD) UTF-8 strings,
431 * and are escaped using standard DNS escaping rules.
432 * (See "Notes on DNS Name Escaping" earlier in this file for more details.)
433 * A graphical browser displaying a hierarchical tree-structured view should cut
434 * the names at the bare dots to yield individual labels, then de-escape each
435 * label according to the escaping rules, and then display the resulting UTF-8 text.
437 * DNSServiceDomainEnumReply Callback Parameters:
439 * sdRef: The DNSServiceRef initialized by DNSServiceEnumerateDomains().
441 * flags: Possible values are:
442 * kDNSServiceFlagsMoreComing
443 * kDNSServiceFlagsAdd
444 * kDNSServiceFlagsDefault
446 * interfaceIndex: Specifies the interface on which the domain exists. (The index for a given
447 * interface is determined via the if_nametoindex() family of calls.)
449 * errorCode: Will be kDNSServiceErr_NoError (0) on success, otherwise indicates
450 * the failure that occurred (other parameters are undefined if errorCode is nonzero).
452 * replyDomain: The name of the domain.
454 * context: The context pointer passed to DNSServiceEnumerateDomains.
458 typedef void (DNSSD_API
*DNSServiceDomainEnumReply
)
461 DNSServiceFlags flags
,
462 uint32_t interfaceIndex
,
463 DNSServiceErrorType errorCode
,
464 const char *replyDomain
,
469 /* DNSServiceEnumerateDomains() Parameters:
472 * sdRef: A pointer to an uninitialized DNSServiceRef. If the call succeeds
473 * then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError,
474 * and the enumeration operation will run indefinitely until the client
475 * terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate().
477 * flags: Possible values are:
478 * kDNSServiceFlagsBrowseDomains to enumerate domains recommended for browsing.
479 * kDNSServiceFlagsRegistrationDomains to enumerate domains recommended
482 * interfaceIndex: If non-zero, specifies the interface on which to look for domains.
483 * (the index for a given interface is determined via the if_nametoindex()
484 * family of calls.) Most applications will pass 0 to enumerate domains on
485 * all interfaces. See "Constants for specifying an interface index" for more details.
487 * callBack: The function to be called when a domain is found or the call asynchronously
490 * context: An application context pointer which is passed to the callback function
493 * return value: Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
494 * errors are delivered to the callback), otherwise returns an error code indicating
495 * the error that occurred (the callback is not invoked and the DNSServiceRef
496 * is not initialized.)
499 DNSServiceErrorType DNSSD_API DNSServiceEnumerateDomains
501 DNSServiceRef
*sdRef
,
502 DNSServiceFlags flags
,
503 uint32_t interfaceIndex
,
504 DNSServiceDomainEnumReply callBack
,
505 void *context
/* may be NULL */
509 /*********************************************************************************************
511 * Service Registration
513 *********************************************************************************************/
515 /* Register a service that is discovered via Browse() and Resolve() calls.
518 * DNSServiceRegisterReply() Callback Parameters:
520 * sdRef: The DNSServiceRef initialized by DNSServiceRegister().
522 * flags: Currently unused, reserved for future use.
524 * errorCode: Will be kDNSServiceErr_NoError on success, otherwise will
525 * indicate the failure that occurred (including name conflicts,
526 * if the kDNSServiceFlagsNoAutoRename flag was used when registering.)
527 * Other parameters are undefined if errorCode is nonzero.
529 * name: The service name registered (if the application did not specify a name in
530 * DNSServiceRegister(), this indicates what name was automatically chosen).
532 * regtype: The type of service registered, as it was passed to the callout.
534 * domain: The domain on which the service was registered (if the application did not
535 * specify a domain in DNSServiceRegister(), this indicates the default domain
536 * on which the service was registered).
538 * context: The context pointer that was passed to the callout.
542 typedef void (DNSSD_API
*DNSServiceRegisterReply
)
545 DNSServiceFlags flags
,
546 DNSServiceErrorType errorCode
,
554 /* DNSServiceRegister() Parameters:
556 * sdRef: A pointer to an uninitialized DNSServiceRef. If the call succeeds
557 * then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError,
558 * and the registration will remain active indefinitely until the client
559 * terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate().
561 * interfaceIndex: If non-zero, specifies the interface on which to register the service
562 * (the index for a given interface is determined via the if_nametoindex()
563 * family of calls.) Most applications will pass 0 to register on all
564 * available interfaces. See "Constants for specifying an interface index" for more details.
566 * flags: Indicates the renaming behavior on name conflict (most applications
567 * will pass 0). See flag definitions above for details.
569 * name: If non-NULL, specifies the service name to be registered.
570 * Most applications will not specify a name, in which case the computer
571 * name is used (this name is communicated to the client via the callback).
572 * If a name is specified, it must be 1-63 bytes of UTF-8 text.
573 * If the name is longer than 63 bytes it will be automatically truncated
574 * to a legal length, unless the NoAutoRename flag is set,
575 * in which case kDNSServiceErr_BadParam will be returned.
577 * regtype: The service type followed by the protocol, separated by a dot
578 * (e.g. "_ftp._tcp"). The service type must be an underscore, followed
579 * by 1-14 characters, which may be letters, digits, or hyphens.
580 * The transport protocol must be "_tcp" or "_udp". New service types
581 * should be registered at <http://www.dns-sd.org/ServiceTypes.html>.
583 * domain: If non-NULL, specifies the domain on which to advertise the service.
584 * Most applications will not specify a domain, instead automatically
585 * registering in the default domain(s).
587 * host: If non-NULL, specifies the SRV target host name. Most applications
588 * will not specify a host, instead automatically using the machine's
589 * default host name(s). Note that specifying a non-NULL host does NOT
590 * create an address record for that host - the application is responsible
591 * for ensuring that the appropriate address record exists, or creating it
592 * via DNSServiceRegisterRecord().
594 * port: The port, in network byte order, on which the service accepts connections.
595 * Pass 0 for a "placeholder" service (i.e. a service that will not be discovered
596 * by browsing, but will cause a name conflict if another client tries to
597 * register that same name). Most clients will not use placeholder services.
599 * txtLen: The length of the txtRecord, in bytes. Must be zero if the txtRecord is NULL.
601 * txtRecord: The TXT record rdata. A non-NULL txtRecord MUST be a properly formatted DNS
602 * TXT record, i.e. <length byte> <data> <length byte> <data> ...
603 * Passing NULL for the txtRecord is allowed as a synonym for txtLen=1, txtRecord="",
604 * i.e. it creates a TXT record of length one containing a single empty string.
605 * RFC 1035 doesn't allow a TXT record to contain *zero* strings, so a single empty
606 * string is the smallest legal DNS TXT record.
608 * callBack: The function to be called when the registration completes or asynchronously
609 * fails. The client MAY pass NULL for the callback - The client will NOT be notified
610 * of the default values picked on its behalf, and the client will NOT be notified of any
611 * asynchronous errors (e.g. out of memory errors, etc.) that may prevent the registration
612 * of the service. The client may NOT pass the NoAutoRename flag if the callback is NULL.
613 * The client may still deregister the service at any time via DNSServiceRefDeallocate().
615 * context: An application context pointer which is passed to the callback function
618 * return value: Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
619 * errors are delivered to the callback), otherwise returns an error code indicating
620 * the error that occurred (the callback is never invoked and the DNSServiceRef
621 * is not initialized.)
625 DNSServiceErrorType DNSSD_API DNSServiceRegister
627 DNSServiceRef
*sdRef
,
628 DNSServiceFlags flags
,
629 uint32_t interfaceIndex
,
630 const char *name
, /* may be NULL */
632 const char *domain
, /* may be NULL */
633 const char *host
, /* may be NULL */
636 const void *txtRecord
, /* may be NULL */
637 DNSServiceRegisterReply callBack
, /* may be NULL */
638 void *context
/* may be NULL */
642 /* DNSServiceAddRecord()
644 * Add a record to a registered service. The name of the record will be the same as the
645 * registered service's name.
646 * The record can later be updated or deregistered by passing the RecordRef initialized
647 * by this function to DNSServiceUpdateRecord() or DNSServiceRemoveRecord().
652 * sdRef: A DNSServiceRef initialized by DNSServiceRegister().
654 * RecordRef: A pointer to an uninitialized DNSRecordRef. Upon succesfull completion of this
655 * call, this ref may be passed to DNSServiceUpdateRecord() or DNSServiceRemoveRecord().
656 * If the above DNSServiceRef is passed to DNSServiceRefDeallocate(), RecordRef is also
657 * invalidated and may not be used further.
659 * flags: Currently ignored, reserved for future use.
661 * rrtype: The type of the record (e.g. kDNSServiceType_TXT, kDNSServiceType_SRV, etc)
663 * rdlen: The length, in bytes, of the rdata.
665 * rdata: The raw rdata to be contained in the added resource record.
667 * ttl: The time to live of the resource record, in seconds. Pass 0 to use a default value.
669 * return value: Returns kDNSServiceErr_NoError on success, otherwise returns an
670 * error code indicating the error that occurred (the RecordRef is not initialized).
673 DNSServiceErrorType DNSSD_API DNSServiceAddRecord
676 DNSRecordRef
*RecordRef
,
677 DNSServiceFlags flags
,
685 /* DNSServiceUpdateRecord
687 * Update a registered resource record. The record must either be:
688 * - The primary txt record of a service registered via DNSServiceRegister()
689 * - A record added to a registered service via DNSServiceAddRecord()
690 * - An individual record registered by DNSServiceRegisterRecord()
695 * sdRef: A DNSServiceRef that was initialized by DNSServiceRegister()
696 * or DNSServiceCreateConnection().
698 * RecordRef: A DNSRecordRef initialized by DNSServiceAddRecord, or NULL to update the
699 * service's primary txt record.
701 * flags: Currently ignored, reserved for future use.
703 * rdlen: The length, in bytes, of the new rdata.
705 * rdata: The new rdata to be contained in the updated resource record.
707 * ttl: The time to live of the updated resource record, in seconds.
709 * return value: Returns kDNSServiceErr_NoError on success, otherwise returns an
710 * error code indicating the error that occurred.
713 DNSServiceErrorType DNSSD_API DNSServiceUpdateRecord
716 DNSRecordRef RecordRef
, /* may be NULL */
717 DNSServiceFlags flags
,
724 /* DNSServiceRemoveRecord
726 * Remove a record previously added to a service record set via DNSServiceAddRecord(), or deregister
727 * an record registered individually via DNSServiceRegisterRecord().
731 * sdRef: A DNSServiceRef initialized by DNSServiceRegister() (if the
732 * record being removed was registered via DNSServiceAddRecord()) or by
733 * DNSServiceCreateConnection() (if the record being removed was registered via
734 * DNSServiceRegisterRecord()).
736 * recordRef: A DNSRecordRef initialized by a successful call to DNSServiceAddRecord()
737 * or DNSServiceRegisterRecord().
739 * flags: Currently ignored, reserved for future use.
741 * return value: Returns kDNSServiceErr_NoError on success, otherwise returns an
742 * error code indicating the error that occurred.
745 DNSServiceErrorType DNSSD_API DNSServiceRemoveRecord
748 DNSRecordRef RecordRef
,
749 DNSServiceFlags flags
753 /*********************************************************************************************
757 *********************************************************************************************/
759 /* Browse for instances of a service.
762 * DNSServiceBrowseReply() Parameters:
764 * sdRef: The DNSServiceRef initialized by DNSServiceBrowse().
766 * flags: Possible values are kDNSServiceFlagsMoreComing and kDNSServiceFlagsAdd.
767 * See flag definitions for details.
769 * interfaceIndex: The interface on which the service is advertised. This index should
770 * be passed to DNSServiceResolve() when resolving the service.
772 * errorCode: Will be kDNSServiceErr_NoError (0) on success, otherwise will
773 * indicate the failure that occurred. Other parameters are undefined if
774 * the errorCode is nonzero.
776 * serviceName: The discovered service name. This name should be displayed to the user,
777 * and stored for subsequent use in the DNSServiceResolve() call.
779 * regtype: The service type, which is usually (but not always) the same as was passed
780 * to DNSServiceBrowse(). One case where the discovered service type may
781 * not be the same as the requested service type is when using subtypes:
782 * The client may want to browse for only those ftp servers that allow
783 * anonymous connections. The client will pass the string "_ftp._tcp,_anon"
784 * to DNSServiceBrowse(), but the type of the service that's discovered
785 * is simply "_ftp._tcp". The regtype for each discovered service instance
786 * should be stored along with the name, so that it can be passed to
787 * DNSServiceResolve() when the service is later resolved.
789 * domain: The domain of the discovered service instance. This may or may not be the
790 * same as the domain that was passed to DNSServiceBrowse(). The domain for each
791 * discovered service instance should be stored along with the name, so that
792 * it can be passed to DNSServiceResolve() when the service is later resolved.
794 * context: The context pointer that was passed to the callout.
798 typedef void (DNSSD_API
*DNSServiceBrowseReply
)
801 DNSServiceFlags flags
,
802 uint32_t interfaceIndex
,
803 DNSServiceErrorType errorCode
,
804 const char *serviceName
,
806 const char *replyDomain
,
811 /* DNSServiceBrowse() Parameters:
813 * sdRef: A pointer to an uninitialized DNSServiceRef. If the call succeeds
814 * then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError,
815 * and the browse operation will run indefinitely until the client
816 * terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate().
818 * flags: Currently ignored, reserved for future use.
820 * interfaceIndex: If non-zero, specifies the interface on which to browse for services
821 * (the index for a given interface is determined via the if_nametoindex()
822 * family of calls.) Most applications will pass 0 to browse on all available
823 * interfaces. See "Constants for specifying an interface index" for more details.
825 * regtype: The service type being browsed for followed by the protocol, separated by a
826 * dot (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp".
828 * domain: If non-NULL, specifies the domain on which to browse for services.
829 * Most applications will not specify a domain, instead browsing on the
832 * callBack: The function to be called when an instance of the service being browsed for
833 * is found, or if the call asynchronously fails.
835 * context: An application context pointer which is passed to the callback function
838 * return value: Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
839 * errors are delivered to the callback), otherwise returns an error code indicating
840 * the error that occurred (the callback is not invoked and the DNSServiceRef
841 * is not initialized.)
844 DNSServiceErrorType DNSSD_API DNSServiceBrowse
846 DNSServiceRef
*sdRef
,
847 DNSServiceFlags flags
,
848 uint32_t interfaceIndex
,
850 const char *domain
, /* may be NULL */
851 DNSServiceBrowseReply callBack
,
852 void *context
/* may be NULL */
856 /* DNSServiceResolve()
858 * Resolve a service name discovered via DNSServiceBrowse() to a target host name, port number, and
861 * Note: Applications should NOT use DNSServiceResolve() solely for txt record monitoring - use
862 * DNSServiceQueryRecord() instead, as it is more efficient for this task.
864 * Note: When the desired results have been returned, the client MUST terminate the resolve by calling
865 * DNSServiceRefDeallocate().
867 * Note: DNSServiceResolve() behaves correctly for typical services that have a single SRV record
868 * and a single TXT record. To resolve non-standard services with multiple SRV or TXT records,
869 * DNSServiceQueryRecord() should be used.
871 * DNSServiceResolveReply Callback Parameters:
873 * sdRef: The DNSServiceRef initialized by DNSServiceResolve().
875 * flags: Currently unused, reserved for future use.
877 * interfaceIndex: The interface on which the service was resolved.
879 * errorCode: Will be kDNSServiceErr_NoError (0) on success, otherwise will
880 * indicate the failure that occurred. Other parameters are undefined if
881 * the errorCode is nonzero.
883 * fullname: The full service domain name, in the form <servicename>.<protocol>.<domain>.
884 * (This name is escaped following standard DNS rules, making it suitable for
885 * passing to standard system DNS APIs such as res_query(), or to the
886 * special-purpose functions included in this API that take fullname parameters.
887 * See "Notes on DNS Name Escaping" earlier in this file for more details.)
889 * hosttarget: The target hostname of the machine providing the service. This name can
890 * be passed to functions like gethostbyname() to identify the host's IP address.
892 * port: The port, in network byte order, on which connections are accepted for this service.
894 * txtLen: The length of the txt record, in bytes.
896 * txtRecord: The service's primary txt record, in standard txt record format.
899 * context: The context pointer that was passed to the callout.
903 typedef void (DNSSD_API
*DNSServiceResolveReply
)
906 DNSServiceFlags flags
,
907 uint32_t interfaceIndex
,
908 DNSServiceErrorType errorCode
,
909 const char *fullname
,
910 const char *hosttarget
,
913 const char *txtRecord
,
918 /* DNSServiceResolve() Parameters
920 * sdRef: A pointer to an uninitialized DNSServiceRef. If the call succeeds
921 * then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError,
922 * and the resolve operation will run indefinitely until the client
923 * terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate().
925 * flags: Currently ignored, reserved for future use.
927 * interfaceIndex: The interface on which to resolve the service. If this resolve call is
928 * as a result of a currently active DNSServiceBrowse() operation, then the
929 * interfaceIndex should be the index reported in the DNSServiceBrowseReply
930 * callback. If this resolve call is using information previously saved
931 * (e.g. in a preference file) for later use, then use interfaceIndex 0, because
932 * the desired service may now be reachable via a different physical interface.
933 * See "Constants for specifying an interface index" for more details.
935 * name: The name of the service instance to be resolved, as reported to the
936 * DNSServiceBrowseReply() callback.
938 * regtype: The type of the service instance to be resolved, as reported to the
939 * DNSServiceBrowseReply() callback.
941 * domain: The domain of the service instance to be resolved, as reported to the
942 * DNSServiceBrowseReply() callback.
944 * callBack: The function to be called when a result is found, or if the call
945 * asynchronously fails.
947 * context: An application context pointer which is passed to the callback function
950 * return value: Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
951 * errors are delivered to the callback), otherwise returns an error code indicating
952 * the error that occurred (the callback is never invoked and the DNSServiceRef
953 * is not initialized.)
956 DNSServiceErrorType DNSSD_API DNSServiceResolve
958 DNSServiceRef
*sdRef
,
959 DNSServiceFlags flags
,
960 uint32_t interfaceIndex
,
964 DNSServiceResolveReply callBack
,
965 void *context
/* may be NULL */
969 /*********************************************************************************************
971 * Special Purpose Calls (most applications will not use these)
973 *********************************************************************************************/
975 /* DNSServiceCreateConnection()
977 * Create a connection to the daemon allowing efficient registration of
978 * multiple individual records.
983 * sdRef: A pointer to an uninitialized DNSServiceRef. Deallocating
984 * the reference (via DNSServiceRefDeallocate()) severs the
985 * connection and deregisters all records registered on this connection.
987 * return value: Returns kDNSServiceErr_NoError on success, otherwise returns
988 * an error code indicating the specific failure that occurred (in which
989 * case the DNSServiceRef is not initialized).
992 DNSServiceErrorType DNSSD_API
DNSServiceCreateConnection(DNSServiceRef
*sdRef
);
995 /* DNSServiceRegisterRecord
997 * Register an individual resource record on a connected DNSServiceRef.
999 * Note that name conflicts occurring for records registered via this call must be handled
1000 * by the client in the callback.
1003 * DNSServiceRegisterRecordReply() parameters:
1005 * sdRef: The connected DNSServiceRef initialized by
1006 * DNSServiceDiscoveryConnect().
1008 * RecordRef: The DNSRecordRef initialized by DNSServiceRegisterRecord(). If the above
1009 * DNSServiceRef is passed to DNSServiceRefDeallocate(), this DNSRecordRef is
1010 * invalidated, and may not be used further.
1012 * flags: Currently unused, reserved for future use.
1014 * errorCode: Will be kDNSServiceErr_NoError on success, otherwise will
1015 * indicate the failure that occurred (including name conflicts.)
1016 * Other parameters are undefined if errorCode is nonzero.
1018 * context: The context pointer that was passed to the callout.
1022 typedef void (DNSSD_API
*DNSServiceRegisterRecordReply
)
1024 DNSServiceRef sdRef
,
1025 DNSRecordRef RecordRef
,
1026 DNSServiceFlags flags
,
1027 DNSServiceErrorType errorCode
,
1032 /* DNSServiceRegisterRecord() Parameters:
1034 * sdRef: A DNSServiceRef initialized by DNSServiceCreateConnection().
1036 * RecordRef: A pointer to an uninitialized DNSRecordRef. Upon succesfull completion of this
1037 * call, this ref may be passed to DNSServiceUpdateRecord() or DNSServiceRemoveRecord().
1038 * (To deregister ALL records registered on a single connected DNSServiceRef
1039 * and deallocate each of their corresponding DNSServiceRecordRefs, call
1040 * DNSServiceRefDealloocate()).
1042 * flags: Possible values are kDNSServiceFlagsShared or kDNSServiceFlagsUnique
1043 * (see flag type definitions for details).
1045 * interfaceIndex: If non-zero, specifies the interface on which to register the record
1046 * (the index for a given interface is determined via the if_nametoindex()
1047 * family of calls.) Passing 0 causes the record to be registered on all interfaces.
1048 * See "Constants for specifying an interface index" for more details.
1050 * fullname: The full domain name of the resource record.
1052 * rrtype: The numerical type of the resource record (e.g. kDNSServiceType_PTR, kDNSServiceType_SRV, etc)
1054 * rrclass: The class of the resource record (usually kDNSServiceClass_IN)
1056 * rdlen: Length, in bytes, of the rdata.
1058 * rdata: A pointer to the raw rdata, as it is to appear in the DNS record.
1060 * ttl: The time to live of the resource record, in seconds. Pass 0 to use a default value.
1062 * callBack: The function to be called when a result is found, or if the call
1063 * asynchronously fails (e.g. because of a name conflict.)
1065 * context: An application context pointer which is passed to the callback function
1068 * return value: Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
1069 * errors are delivered to the callback), otherwise returns an error code indicating
1070 * the error that occurred (the callback is never invoked and the DNSRecordRef is
1074 DNSServiceErrorType DNSSD_API DNSServiceRegisterRecord
1076 DNSServiceRef sdRef
,
1077 DNSRecordRef
*RecordRef
,
1078 DNSServiceFlags flags
,
1079 uint32_t interfaceIndex
,
1080 const char *fullname
,
1086 DNSServiceRegisterRecordReply callBack
,
1087 void *context
/* may be NULL */
1091 /* DNSServiceQueryRecord
1093 * Query for an arbitrary DNS record.
1096 * DNSServiceQueryRecordReply() Callback Parameters:
1098 * sdRef: The DNSServiceRef initialized by DNSServiceQueryRecord().
1100 * flags: Possible values are kDNSServiceFlagsMoreComing and
1101 * kDNSServiceFlagsAdd. The Add flag is NOT set for PTR records
1102 * with a ttl of 0, i.e. "Remove" events.
1104 * interfaceIndex: The interface on which the query was resolved (the index for a given
1105 * interface is determined via the if_nametoindex() family of calls).
1106 * See "Constants for specifying an interface index" for more details.
1108 * errorCode: Will be kDNSServiceErr_NoError on success, otherwise will
1109 * indicate the failure that occurred. Other parameters are undefined if
1110 * errorCode is nonzero.
1112 * fullname: The resource record's full domain name.
1114 * rrtype: The resource record's type (e.g. kDNSServiceType_PTR, kDNSServiceType_SRV, etc)
1116 * rrclass: The class of the resource record (usually kDNSServiceClass_IN).
1118 * rdlen: The length, in bytes, of the resource record rdata.
1120 * rdata: The raw rdata of the resource record.
1122 * ttl: The resource record's time to live, in seconds.
1124 * context: The context pointer that was passed to the callout.
1128 typedef void (DNSSD_API
*DNSServiceQueryRecordReply
)
1130 DNSServiceRef DNSServiceRef
,
1131 DNSServiceFlags flags
,
1132 uint32_t interfaceIndex
,
1133 DNSServiceErrorType errorCode
,
1134 const char *fullname
,
1144 /* DNSServiceQueryRecord() Parameters:
1146 * sdRef: A pointer to an uninitialized DNSServiceRef. If the call succeeds
1147 * then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError,
1148 * and the query operation will run indefinitely until the client
1149 * terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate().
1151 * flags: Pass kDNSServiceFlagsLongLivedQuery to create a "long-lived" unicast
1152 * query in a non-local domain. Without setting this flag, unicast queries
1153 * will be one-shot - that is, only answers available at the time of the call
1154 * will be returned. By setting this flag, answers (including Add and Remove
1155 * events) that become available after the initial call is made will generate
1156 * callbacks. This flag has no effect on link-local multicast queries.
1158 * interfaceIndex: If non-zero, specifies the interface on which to issue the query
1159 * (the index for a given interface is determined via the if_nametoindex()
1160 * family of calls.) Passing 0 causes the name to be queried for on all
1161 * interfaces. See "Constants for specifying an interface index" for more details.
1163 * fullname: The full domain name of the resource record to be queried for.
1165 * rrtype: The numerical type of the resource record to be queried for
1166 * (e.g. kDNSServiceType_PTR, kDNSServiceType_SRV, etc)
1168 * rrclass: The class of the resource record (usually kDNSServiceClass_IN).
1170 * callBack: The function to be called when a result is found, or if the call
1171 * asynchronously fails.
1173 * context: An application context pointer which is passed to the callback function
1176 * return value: Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
1177 * errors are delivered to the callback), otherwise returns an error code indicating
1178 * the error that occurred (the callback is never invoked and the DNSServiceRef
1179 * is not initialized.)
1182 DNSServiceErrorType DNSSD_API DNSServiceQueryRecord
1184 DNSServiceRef
*sdRef
,
1185 DNSServiceFlags flags
,
1186 uint32_t interfaceIndex
,
1187 const char *fullname
,
1190 DNSServiceQueryRecordReply callBack
,
1191 void *context
/* may be NULL */
1195 /* DNSServiceReconfirmRecord
1197 * Instruct the daemon to verify the validity of a resource record that appears to
1198 * be out of date (e.g. because tcp connection to a service's target failed.)
1199 * Causes the record to be flushed from the daemon's cache (as well as all other
1200 * daemons' caches on the network) if the record is determined to be invalid.
1204 * flags: Currently unused, reserved for future use.
1206 * interfaceIndex: If non-zero, specifies the interface of the record in question.
1207 * Passing 0 causes all instances of this record to be reconfirmed.
1209 * fullname: The resource record's full domain name.
1211 * rrtype: The resource record's type (e.g. kDNSServiceType_PTR, kDNSServiceType_SRV, etc)
1213 * rrclass: The class of the resource record (usually kDNSServiceClass_IN).
1215 * rdlen: The length, in bytes, of the resource record rdata.
1217 * rdata: The raw rdata of the resource record.
1221 void DNSSD_API DNSServiceReconfirmRecord
1223 DNSServiceFlags flags
,
1224 uint32_t interfaceIndex
,
1225 const char *fullname
,
1233 /*********************************************************************************************
1235 * General Utility Functions
1237 *********************************************************************************************/
1239 /* DNSServiceConstructFullName()
1241 * Concatenate a three-part domain name (as returned by the above callbacks) into a
1242 * properly-escaped full domain name. Note that callbacks in the above functions ALREADY ESCAPE
1243 * strings where necessary.
1247 * fullName: A pointer to a buffer that where the resulting full domain name is to be written.
1248 * The buffer must be kDNSServiceMaxDomainName (1005) bytes in length to
1249 * accommodate the longest legal domain name without buffer overrun.
1251 * service: The service name - any dots or backslashes must NOT be escaped.
1252 * May be NULL (to construct a PTR record name, e.g.
1253 * "_ftp._tcp.apple.com.").
1255 * regtype: The service type followed by the protocol, separated by a dot
1256 * (e.g. "_ftp._tcp").
1258 * domain: The domain name, e.g. "apple.com.". Literal dots or backslashes,
1259 * if any, must be escaped, e.g. "1st\. Floor.apple.com."
1261 * return value: Returns 0 on success, -1 on error.
1265 int DNSSD_API DNSServiceConstructFullName
1268 const char *service
, /* may be NULL */
1269 const char *regtype
,
1274 /*********************************************************************************************
1276 * TXT Record Construction Functions
1278 *********************************************************************************************/
1281 * A typical calling sequence for TXT record construction is something like:
1283 * Client allocates storage for TXTRecord data (e.g. declare buffer on the stack)
1284 * TXTRecordCreate();
1285 * TXTRecordSetValue();
1286 * TXTRecordSetValue();
1287 * TXTRecordSetValue();
1289 * DNSServiceRegister( ... TXTRecordGetLength(), TXTRecordGetBytesPtr() ... );
1290 * TXTRecordDeallocate();
1291 * Explicitly deallocate storage for TXTRecord data (if not allocated on the stack)
1297 * Opaque internal data type.
1298 * Note: Represents a DNS-SD TXT record.
1301 typedef struct _TXTRecordRef_t
{ char privatedata
[16]; } TXTRecordRef
;
1304 /* TXTRecordCreate()
1306 * Creates a new empty TXTRecordRef referencing the specified storage.
1308 * If the buffer parameter is NULL, or the specified storage size is not
1309 * large enough to hold a key subsequently added using TXTRecordSetValue(),
1310 * then additional memory will be added as needed using malloc().
1312 * On some platforms, when memory is low, malloc() may fail. In this
1313 * case, TXTRecordSetValue() will return kDNSServiceErr_NoMemory, and this
1314 * error condition will need to be handled as appropriate by the caller.
1316 * You can avoid the need to handle this error condition if you ensure
1317 * that the storage you initially provide is large enough to hold all
1318 * the key/value pairs that are to be added to the record.
1319 * The caller can precompute the exact length required for all of the
1320 * key/value pairs to be added, or simply provide a fixed-sized buffer
1321 * known in advance to be large enough.
1322 * A no-value (key-only) key requires (1 + key length) bytes.
1323 * A key with empty value requires (1 + key length + 1) bytes.
1324 * A key with non-empty value requires (1 + key length + 1 + value length).
1325 * For most applications, DNS-SD TXT records are generally
1326 * less than 100 bytes, so in most cases a simple fixed-sized
1327 * 256-byte buffer will be more than sufficient.
1328 * Recommended size limits for DNS-SD TXT Records are discussed in
1329 * <http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt>
1331 * Note: When passing parameters to and from these TXT record APIs,
1332 * the key name does not include the '=' character. The '=' character
1333 * is the separator between the key and value in the on-the-wire
1334 * packet format; it is not part of either the key or the value.
1336 * txtRecord: A pointer to an uninitialized TXTRecordRef.
1338 * bufferLen: The size of the storage provided in the "buffer" parameter.
1340 * buffer: Optional caller-supplied storage used to hold the TXTRecord data.
1341 * This storage must remain valid for as long as
1345 void DNSSD_API TXTRecordCreate
1347 TXTRecordRef
*txtRecord
,
1353 /* TXTRecordDeallocate()
1355 * Releases any resources allocated in the course of preparing a TXT Record
1356 * using TXTRecordCreate()/TXTRecordSetValue()/TXTRecordRemoveValue().
1357 * Ownership of the buffer provided in TXTRecordCreate() returns to the client.
1359 * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate().
1363 void DNSSD_API TXTRecordDeallocate
1365 TXTRecordRef
*txtRecord
1369 /* TXTRecordSetValue()
1371 * Adds a key (optionally with value) to a TXTRecordRef. If the "key" already
1372 * exists in the TXTRecordRef, then the current value will be replaced with
1374 * Keys may exist in four states with respect to a given TXT record:
1375 * - Absent (key does not appear at all)
1376 * - Present with no value ("key" appears alone)
1377 * - Present with empty value ("key=" appears in TXT record)
1378 * - Present with non-empty value ("key=value" appears in TXT record)
1379 * For more details refer to "Data Syntax for DNS-SD TXT Records" in
1380 * <http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt>
1382 * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate().
1384 * key: A null-terminated string which only contains printable ASCII
1385 * values (0x20-0x7E), excluding '=' (0x3D). Keys should be
1386 * 8 characters or less (not counting the terminating null).
1388 * valueSize: The size of the value.
1390 * value: Any binary value. For values that represent
1391 * textual data, UTF-8 is STRONGLY recommended.
1392 * For values that represent textual data, valueSize
1393 * should NOT include the terminating null (if any)
1394 * at the end of the string.
1395 * If NULL, then "key" will be added with no value.
1396 * If non-NULL but valueSize is zero, then "key=" will be
1397 * added with empty value.
1399 * return value: Returns kDNSServiceErr_NoError on success.
1400 * Returns kDNSServiceErr_Invalid if the "key" string contains
1401 * illegal characters.
1402 * Returns kDNSServiceErr_NoMemory if adding this key would
1403 * exceed the available storage.
1406 DNSServiceErrorType DNSSD_API TXTRecordSetValue
1408 TXTRecordRef
*txtRecord
,
1410 uint8_t valueSize
, /* may be zero */
1411 const void *value
/* may be NULL */
1415 /* TXTRecordRemoveValue()
1417 * Removes a key from a TXTRecordRef. The "key" must be an
1418 * ASCII string which exists in the TXTRecordRef.
1420 * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate().
1422 * key: A key name which exists in the TXTRecordRef.
1424 * return value: Returns kDNSServiceErr_NoError on success.
1425 * Returns kDNSServiceErr_NoSuchKey if the "key" does not
1426 * exist in the TXTRecordRef.
1430 DNSServiceErrorType DNSSD_API TXTRecordRemoveValue
1432 TXTRecordRef
*txtRecord
,
1437 /* TXTRecordGetLength()
1439 * Allows you to determine the length of the raw bytes within a TXTRecordRef.
1441 * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate().
1443 * return value: Returns the size of the raw bytes inside a TXTRecordRef
1444 * which you can pass directly to DNSServiceRegister() or
1445 * to DNSServiceUpdateRecord().
1446 * Returns 0 if the TXTRecordRef is empty.
1450 uint16_t DNSSD_API TXTRecordGetLength
1452 const TXTRecordRef
*txtRecord
1456 /* TXTRecordGetBytesPtr()
1458 * Allows you to retrieve a pointer to the raw bytes within a TXTRecordRef.
1460 * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate().
1462 * return value: Returns a pointer to the raw bytes inside the TXTRecordRef
1463 * which you can pass directly to DNSServiceRegister() or
1464 * to DNSServiceUpdateRecord().
1468 const void * DNSSD_API TXTRecordGetBytesPtr
1470 const TXTRecordRef
*txtRecord
1474 /*********************************************************************************************
1476 * TXT Record Parsing Functions
1478 *********************************************************************************************/
1481 * A typical calling sequence for TXT record parsing is something like:
1483 * Receive TXT record data in DNSServiceResolve() callback
1484 * if (TXTRecordContainsKey(txtLen, txtRecord, "key")) then do something
1485 * val1ptr = TXTRecordGetValuePtr(txtLen, txtRecord, "key1", &len1);
1486 * val2ptr = TXTRecordGetValuePtr(txtLen, txtRecord, "key2", &len2);
1488 * bcopy(val1ptr, myval1, len1);
1489 * bcopy(val2ptr, myval2, len2);
1493 * If you wish to retain the values after return from the DNSServiceResolve()
1494 * callback, then you need to copy the data to your own storage using bcopy()
1495 * or similar, as shown in the example above.
1497 * If for some reason you need to parse a TXT record you built yourself
1498 * using the TXT record construction functions above, then you can do
1499 * that using TXTRecordGetLength and TXTRecordGetBytesPtr calls:
1500 * TXTRecordGetValue(TXTRecordGetLength(x), TXTRecordGetBytesPtr(x), key, &len);
1502 * Most applications only fetch keys they know about from a TXT record and
1504 * However, some debugging tools wish to fetch and display all keys.
1505 * To do that, use the TXTRecordGetCount() and TXTRecordGetItemAtIndex() calls.
1508 /* TXTRecordContainsKey()
1510 * Allows you to determine if a given TXT Record contains a specified key.
1512 * txtLen: The size of the received TXT Record.
1514 * txtRecord: Pointer to the received TXT Record bytes.
1516 * key: A null-terminated ASCII string containing the key name.
1518 * return value: Returns 1 if the TXT Record contains the specified key.
1519 * Otherwise, it returns 0.
1523 int DNSSD_API TXTRecordContainsKey
1526 const void *txtRecord
,
1531 /* TXTRecordGetValuePtr()
1533 * Allows you to retrieve the value for a given key from a TXT Record.
1535 * txtLen: The size of the received TXT Record
1537 * txtRecord: Pointer to the received TXT Record bytes.
1539 * key: A null-terminated ASCII string containing the key name.
1541 * valueLen: On output, will be set to the size of the "value" data.
1543 * return value: Returns NULL if the key does not exist in this TXT record,
1544 * or exists with no value (to differentiate between
1545 * these two cases use TXTRecordContainsKey()).
1546 * Returns pointer to location within TXT Record bytes
1547 * if the key exists with empty or non-empty value.
1548 * For empty value, valueLen will be zero.
1549 * For non-empty value, valueLen will be length of value data.
1552 const void * DNSSD_API TXTRecordGetValuePtr
1555 const void *txtRecord
,
1561 /* TXTRecordGetCount()
1563 * Returns the number of keys stored in the TXT Record. The count
1564 * can be used with TXTRecordGetItemAtIndex() to iterate through the keys.
1566 * txtLen: The size of the received TXT Record.
1568 * txtRecord: Pointer to the received TXT Record bytes.
1570 * return value: Returns the total number of keys in the TXT Record.
1574 uint16_t DNSSD_API TXTRecordGetCount
1577 const void *txtRecord
1581 /* TXTRecordGetItemAtIndex()
1583 * Allows you to retrieve a key name and value pointer, given an index into
1584 * a TXT Record. Legal index values range from zero to TXTRecordGetCount()-1.
1585 * It's also possible to iterate through keys in a TXT record by simply
1586 * calling TXTRecordGetItemAtIndex() repeatedly, beginning with index zero
1587 * and increasing until TXTRecordGetItemAtIndex() returns kDNSServiceErr_Invalid.
1590 * For keys with no value, *value is set to NULL and *valueLen is zero.
1591 * For keys with empty value, *value is non-NULL and *valueLen is zero.
1592 * For keys with non-empty value, *value is non-NULL and *valueLen is non-zero.
1594 * txtLen: The size of the received TXT Record.
1596 * txtRecord: Pointer to the received TXT Record bytes.
1598 * index: An index into the TXT Record.
1600 * keyBufLen: The size of the string buffer being supplied.
1602 * key: A string buffer used to store the key name.
1603 * On return, the buffer contains a null-terminated C string
1604 * giving the key name. DNS-SD TXT keys are usually
1605 * 8 characters or less. To hold the maximum possible
1606 * key name, the buffer should be 256 bytes long.
1608 * valueLen: On output, will be set to the size of the "value" data.
1610 * value: On output, *value is set to point to location within TXT
1611 * Record bytes that holds the value data.
1613 * return value: Returns kDNSServiceErr_NoError on success.
1614 * Returns kDNSServiceErr_NoMemory if keyBufLen is too short.
1615 * Returns kDNSServiceErr_Invalid if index is greater than
1616 * TXTRecordGetCount()-1.
1619 DNSServiceErrorType DNSSD_API TXTRecordGetItemAtIndex
1622 const void *txtRecord
,
1630 #ifdef __APPLE_API_PRIVATE
1633 * Mac OS X specific functionality
1634 * 3rd party clients of this API should not depend on future support or availability of this routine
1637 /* DNSServiceSetDefaultDomainForUser()
1639 * Set the default domain for the caller's UID. Future browse and registration
1640 * calls by this user that do not specify an explicit domain will browse and
1641 * register in this wide-area domain in addition to .local. In addition, this
1642 * domain will be returned as a Browse domain via domain enumeration calls.
1647 * flags: Pass kDNSServiceFlagsAdd to add a domain for a user. Call without
1648 * this flag set to clear a previously added domain.
1650 * domain: The domain to be used for the caller's UID.
1652 * return value: Returns kDNSServiceErr_NoError on succeses, otherwise returns
1653 * an error code indicating the error that occurred
1656 DNSServiceErrorType DNSSD_API DNSServiceSetDefaultDomainForUser
1658 DNSServiceFlags flags
,
1662 #endif //__APPLE_API_PRIVATE
1668 #endif /* _DNS_SD_H */