]> git.saurik.com Git - apple/mdnsresponder.git/blob - mDNSWindows/DNSSD.h
projects / apple / mdnsresponder.git / blob
? search:


11cd6e3291f3ca13f00fb285434226b0cab288a7
[apple/mdnsresponder.git] / mDNSWindows / DNSSD.h
1 /*
2 * Copyright (c) 2003-2004 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * Copyright (c) 1999-2003 Apple Computer, Inc. All Rights Reserved.
7 *
8 * This file contains Original Code and/or Modifications of Original Code
9 * as defined in and that are subject to the Apple Public Source License
10 * Version 2.0 (the 'License'). You may not use this file except in
11 * compliance with the License. Please obtain a copy of the License at
12 * http://www.opensource.apple.com/apsl/ and read it before using this
13 * file.
14 *
15 * The Original Code and all software distributed under the License are
16 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
17 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
18 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
20 * Please see the License for the specific language governing rights and
21 * limitations under the License.
22 *
23 * @APPLE_LICENSE_HEADER_END@
24
25 Change History (most recent first):
26
27 $Log: DNSSD.h,v $
28 Revision 1.7 2004/05/11 03:08:53 bradley
29 Updated TXT Record API based on latest proposal. This still includes dynamic TXT record building for
30 a final CVS snapshot for private libraries before this functionality is removed from the public API.
31
32 Revision 1.6 2004/05/06 18:42:58 ksekar
33 General dns_sd.h API cleanup, including the following radars:
34 <rdar://problem/3592068>: Remove flags with zero value
35 <rdar://problem/3479569>: Passing in NULL causes a crash.
36
37 Revision 1.5 2004/05/03 10:34:24 bradley
38 Implemented preliminary version of the TXTRecord API.
39
40 Revision 1.4 2004/04/15 01:00:05 bradley
41 Removed support for automatically querying for A/AAAA records when resolving names. Platforms
42 without .local name resolving support will need to manually query for A/AAAA records as needed.
43
44 Revision 1.3 2004/04/09 21:03:14 bradley
45 Changed port numbers to use network byte order for consistency with other platforms.
46
47 Revision 1.2 2004/04/08 09:43:42 bradley
48 Changed callback calling conventions to __stdcall so they can be used with C# delegates.
49
50 Revision 1.1 2004/01/30 02:45:21 bradley
51 High-level implementation of the DNS-SD API. Supports both "direct" (compiled-in mDNSCore) and "client"
52 (IPC<->service) usage. Conditionals can exclude either "direct" or "client" to reduce code size.
53
54 */
55
56 //---------------------------------------------------------------------------------------------------------------------------
57 /*! @header DNSSD.h
58
59 @abstract DNS Service Discovery provides registration, domain and service discovery, and name resolving support.
60
61 @discussion
62
63 High-level implementation of the DNS-SD API. This supports both "direct" (compiled-in mDNSCore) and "client" (IPC to
64 service) usage. Conditionals can exclude either "direct" or "client" to reduce code size.
65 */
66
67 #ifndef _DNS_SD_H
68 #define _DNS_SD_H
69
70 #include "CommonServices.h"
71
72 #ifdef __cplusplus
73 extern "C" {
74 #endif
75
76 #if 0
77 #pragma mark == Configuration ==
78 #endif
79
80 //---------------------------------------------------------------------------------------------------------------------------
81 /*! @defined DNS_SD_DIRECT_ENABLED
82
83 @abstract Enables or disables DNS-SD direct.
84 */
85
86 #if( !defined( DNS_SD_DIRECT_ENABLED ) )
87 #define DNS_SD_DIRECT_ENABLED 1
88 #endif
89
90 //---------------------------------------------------------------------------------------------------------------------------
91 /*! @defined DNS_SD_CLIENT_ENABLED
92
93 @abstract Enables or disables DNS-SD client.
94 */
95
96 #if( !defined( DNS_SD_CLIENT_ENABLED ) )
97 #define DNS_SD_CLIENT_ENABLED 1
98 #endif
99
100 #if 0
101 #pragma mark == Types ==
102 #endif
103
104 //---------------------------------------------------------------------------------------------------------------------------
105 /*! @typedef DNSServiceRef
106
107 @abstract Reference to a DNSService object.
108
109 @discussion
110
111 Note: client is responsible for serializing access to these structures if they are shared between concurrent threads.
112 */
113
114 typedef struct _DNSServiceRef_t * DNSServiceRef;
115
116 //---------------------------------------------------------------------------------------------------------------------------
117 /*! @typedef DNSRecordRef
118
119 @abstract Reference to a DNSRecord object.
120
121 @discussion
122
123 Note: client is responsible for serializing access to these structures if they are shared between concurrent threads.
124 */
125
126 typedef struct _DNSRecordRef_t * DNSRecordRef;
127
128 #if 0
129 #pragma mark == Flags ==
130 #endif
131
132 //---------------------------------------------------------------------------------------------------------------------------
133 /*! @typedef DNSServiceFlags
134
135 @abstract General flags used in DNS-SD functions.
136
137 @constant kDNSServiceFlagsNone
138 No flags (makes it clearer to use this symbolic constant rather than using a 0).
139
140 @constant kDNSServiceFlagsMoreComing
141 MoreComing indicates to a callback that at least one more result is queued and will be delivered
142 following immediately after this one. Applications should not update their UI to display browse
143 results when the MoreComing flag is set, because this would result in a great deal of ugly
144 flickering on the screen. Applications should instead wait until until MoreComing is not set
145 (i.e. "Finished", for now), and then update their UI. When MoreComing is not set (i.e.
146 "Finished") that doesn't mean there will be no more answers EVER, just that there are no more
147 answers immediately available right now at this instant. If more answers become available in
148 the future they will be delivered as usual.
149
150 @constant kDNSServiceFlagsAdd
151 Service or domain has been added during browsing/querying or domain enumeration.
152
153 @constant kDNSServiceFlagsDefault
154 Default domain has been added during domain enumeration.
155
156 @constant kDNSServiceFlagsNoAutoRename
157 Auto renaming should not be performed. Only valid if a name is explicitly specified when
158 registering a service (i.e. the default name is not used).
159
160 @constant kDNSServiceFlagsShared
161 Shared flag for registering individual records on a connected DNSServiceRef. Indicates that there
162 may be multiple records with this name on the network (e.g. PTR records).
163
164 @constant kDNSServiceFlagsUnique
165 Shared flag for registering individual records on a connected DNSServiceRef. Indicates that the
166 record's name is to be unique on the network (e.g. SRV records).
167
168 @constant kDNSServiceFlagsBrowseDomains
169 Enumerates domains recommended for browsing.
170
171 @constant kDNSServiceFlagsRegistrationDomains
172 Enumerates domains recommended for registration.
173 */
174
175 typedef uint32_t DNSServiceFlags;
176 enum
177 {
178 kDNSServiceFlagsNone = 0,
179
180 kDNSServiceFlagsMoreComing = ( 1 << 0 ),
181
182 kDNSServiceFlagsAdd = ( 1 << 1 ),
183 kDNSServiceFlagsDefault = ( 1 << 2 ),
184
185 kDNSServiceFlagsNoAutoRename = ( 1 << 3 ),
186
187 kDNSServiceFlagsShared = ( 1 << 4 ),
188 kDNSServiceFlagsUnique = ( 1 << 5 ),
189
190 kDNSServiceFlagsBrowseDomains = ( 1 << 6 ),
191 kDNSServiceFlagsRegistrationDomains = ( 1 << 7 )
192 };
193
194 //---------------------------------------------------------------------------------------------------------------------------
195 /*! @enum DNSServiceInitializeFlags
196
197 @abstract Flags used with DNSServiceInitialize.
198
199 @constant kDNSServiceInitializeFlagsAdvertise
200 Indicates that interfaces should be advertised on the network. Software that only performs searches
201 do not need to set this flag.
202
203 @constant kDNSServiceInitializeFlagsNoServerCheck
204 No check for a valid server should be performed. Only applicable if client support is enabled.
205 */
206
207 typedef uint32_t DNSServiceInitializeFlags;
208
209 #define kDNSServiceInitializeFlagsNone 0
210 #define kDNSServiceInitializeFlagsAdvertise ( 1 << 0 )
211 #define kDNSServiceInitializeFlagsNoServerCheck ( 1 << 1 )
212
213 //---------------------------------------------------------------------------------------------------------------------------
214 /*! @defined kDNSServiceMaxDomainName
215
216 @abstract Maximum length, in bytes, of a domain name represented as an escaped C-String
217 */
218
219 #define kDNSServiceMaxDomainName 1005
220
221 //---------------------------------------------------------------------------------------------------------------------------
222 /*! @defined kDNSServiceInterfaceIndexAny
223
224 @abstract Interface index to indicate any interface.
225 */
226
227 #define kDNSServiceInterfaceIndexAny 0
228
229 //---------------------------------------------------------------------------------------------------------------------------
230 /*! @defined kDNSServiceInterfaceIndexAny
231
232 @abstract Use the local interface only.
233 */
234
235 #define kDNSServiceInterfaceIndexLocalOnly ( (uint32_t) ~0 )
236
237 #if 0
238 #pragma mark == Errors ==
239 #endif
240
241 //---------------------------------------------------------------------------------------------------------------------------
242 /*! @typedef DNSServiceErrorType
243
244 @abstract Possible error code values.
245 */
246
247 typedef int32_t DNSServiceErrorType;
248 enum
249 {
250 // Error codes are in the range FFFE FF00 (-65792) to FFFE FFFF (-65537)
251
252 kDNSServiceErr_NoError = 0,
253 kDNSServiceErr_Unknown = -65537, // 0xFFFE FFFF (first error code)
254 kDNSServiceErr_NoSuchName = -65538,
255 kDNSServiceErr_NoMemory = -65539,
256 kDNSServiceErr_BadParam = -65540,
257 kDNSServiceErr_BadReference = -65541,
258 kDNSServiceErr_BadState = -65542,
259 kDNSServiceErr_BadFlags = -65543,
260 kDNSServiceErr_Unsupported = -65544,
261 kDNSServiceErr_NotInitialized = -65545,
262 kDNSServiceErr_NoCache = -65546,
263 kDNSServiceErr_AlreadyRegistered = -65547,
264 kDNSServiceErr_NameConflict = -65548,
265 kDNSServiceErr_Invalid = -65549,
266 kDNSServiceErr_Incompatible = -65551,
267 kDNSServiceErr_BadInterfaceIndex = -65552,
268 kDNSServiceErr_Refused = -65553,
269 kDNSServiceErr_NoSuchRecord = -65554,
270 kDNSServiceErr_NoAuth = -65555,
271 kDNSServiceErr_NoSuchKey = -65556,
272 kDNSServiceErr_NoValue = -65557,
273 kDNSServiceErr_BufferTooSmall = -65558,
274
275 // TCP Connection Status
276
277 kDNSServiceErr_ConnectionPending = -65570,
278 kDNSServiceErr_ConnectionFailed = -65571,
279 kDNSServiceErr_ConnectionEstablished = -65572,
280
281 // Non-error values
282
283 kDNSServiceErr_GrowCache = -65790,
284 kDNSServiceErr_ConfigChanged = -65791,
285 kDNSServiceErr_MemFree = -65792 // 0xFFFE FF00 (last error code)
286 };
287
288 //---------------------------------------------------------------------------------------------------------------------------
289 /*! @var gDNSSDServer
290
291 @abstract Global controlling the server to communicate with. Set to NULL for local operation.
292 */
293
294 extern const char * gDNSSDServer;
295
296 #if 0
297 #pragma mark == DNS Classes ==
298 #endif
299
300 //---------------------------------------------------------------------------------------------------------------------------
301 /*! @enum DNSServiceDNSClass
302
303 @abstract DNS Class
304 */
305
306 typedef enum // From RFC 1035
307 {
308 kDNSServiceDNSClass_IN = 1, // Internet
309 kDNSServiceDNSClass_CS = 2, // CSNET
310 kDNSServiceDNSClass_CH = 3, // CHAOS
311 kDNSServiceDNSClass_HS = 4, // Hesiod
312 kDNSServiceDNSClass_NONE = 254, // Used in DNS UPDATE [RFC 2136]
313
314 kDNSServiceDNSClass_Mask = 0x7FFF, // Multicast DNS uses the bottom 15 bits to identify the record class...
315 kDNSServiceDNSClass_UniqueRRSet = 0x8000, // ... and the top bit indicates that all other cached records are now invalid
316
317 kDNSServiceDNSQClass_ANY = 255, // Not a DNS class, but a DNS query class, meaning "all classes"
318 kDNSServiceDNSQClass_UnicastResponse = 0x8000 // Top bit set in a question means "unicast response acceptable"
319
320 } DNSServiceDNSClass;
321
322 #if 0
323 #pragma mark == DNS Types ==
324 #endif
325
326 //---------------------------------------------------------------------------------------------------------------------------
327 /*! @enum DNSServiceDNSType
328
329 @abstract DNS Type
330 */
331
332 typedef enum // From RFC 1035
333 {
334 kDNSServiceDNSType_A = 1, // Address
335 kDNSServiceDNSType_NS = 2, // Name Server
336 kDNSServiceDNSType_MD = 3, // Mail Destination
337 kDNSServiceDNSType_MF = 4, // Mail Forwarder
338 kDNSServiceDNSType_CNAME = 5, // Canonical Name
339 kDNSServiceDNSType_SOA = 6, // Start of Authority
340 kDNSServiceDNSType_MB = 7, // Mailbox
341 kDNSServiceDNSType_MG = 8, // Mail Group
342 kDNSServiceDNSType_MR = 9, // Mail Rename
343 kDNSServiceDNSType_NULL = 10, // NULL RR
344 kDNSServiceDNSType_WKS = 11, // Well-known-service
345 kDNSServiceDNSType_PTR = 12, // Domain name pointer
346 kDNSServiceDNSType_HINFO = 13, // Host information
347 kDNSServiceDNSType_MINFO = 14, // Mailbox information
348 kDNSServiceDNSType_MX = 15, // Mail Exchanger
349 kDNSServiceDNSType_TXT = 16, // Arbitrary text string
350 kDNSServiceDNSType_AAAA = 28, // IPv6 address
351 kDNSServiceDNSType_SRV = 33, // Service record
352 kDNSServiceDNSTypeQType_ANY = 255 // Not a DNS type, but a DNS query type, meaning "all types"
353
354 } DNSServiceDNSType;
355
356 #if 0
357 #pragma mark == General ==
358 #endif
359
360 //---------------------------------------------------------------------------------------------------------------------------
361 /*! @function DNSServiceInitialize
362
363 @abstract Initializes DNS-SD.
364
365 @param inFlags Flags to control the initialization process (only applicable for DNS-SD direct).
366 @param inCacheEntryCount Size of the cache (only applicable for DNS-SD direct).
367 */
368
369 DNSServiceErrorType DNSServiceInitialize( DNSServiceInitializeFlags inFlags, int inCacheEntryCount );
370
371 //---------------------------------------------------------------------------------------------------------------------------
372 /*! @function DNSServiceFinalize
373
374 @abstract Finalizes DNS-SD.
375 */
376
377 void DNSServiceFinalize( void );
378
379 //---------------------------------------------------------------------------------------------------------------------------
380 /*! @function DNSServiceCheckVersion
381
382 @abstract Performs a version check. Mainly only needed when client-mode is enabled to verify the server is compatible.
383 */
384
385 DNSServiceErrorType DNSServiceCheckVersion( void );
386
387 #if 0
388 #pragma mark == Properties ==
389 #endif
390
391 //---------------------------------------------------------------------------------------------------------------------------
392 /*! @typedef DNSPropertyCode
393
394 @abstract Identifies a property.
395 */
396
397 typedef uint32_t DNSPropertyCode;
398
399 #define kDNSPropertyCodeVersion 0x76657273 // 'vers'
400 // Field: "version"
401 // Format: <w:serverCurrentVersion> <w:serverOldestClientVersion> <w:serverOldestServerVersion>
402
403 //---------------------------------------------------------------------------------------------------------------------------
404 /*! @struct DNSPropertyData
405
406 @abstract Data for a property.
407 */
408
409 typedef struct DNSPropertyData DNSPropertyData;
410 struct DNSPropertyData
411 {
412 DNSPropertyCode code;
413
414 union
415 {
416 struct // version
417 {
418 uint32_t clientCurrentVersion;
419 uint32_t clientOldestServerVersion;
420 uint32_t serverCurrentVersion;
421 uint32_t serverOldestClientVersion;
422
423 } version;
424
425 } u;
426 };
427
428 //---------------------------------------------------------------------------------------------------------------------------
429 /*! @function DNSServiceCopyProperty
430
431 @abstract Copies a property into a newly allocated buffer.
432
433 @param inCode Property to copy.
434 @param outData Receives the copied property data. Must be release with DNSServiceReleaseProperty.
435 */
436
437 DNSServiceErrorType DNSServiceCopyProperty( DNSPropertyCode inCode, DNSPropertyData *outData );
438
439 //---------------------------------------------------------------------------------------------------------------------------
440 /*! @function DNSServiceReleaseProperty
441
442 @abstract Releases a property copied with a successful call to DNSServiceCopyProperty.
443 */
444
445 DNSServiceErrorType DNSServiceReleaseProperty( DNSPropertyData *inData );
446
447 #if 0
448 #pragma mark == Unix Domain Socket Access ==
449 #endif
450
451 //---------------------------------------------------------------------------------------------------------------------------
452 /*! @function DNSServiceRefSockFD
453
454 @param inRef A DNSServiceRef initialized by any of the DNSService calls.
455
456 @result The DNSServiceRef's underlying socket descriptor, or -1 on error.
457
458 @discussion
459
460 Access underlying Unix domain socket for an initialized DNSServiceRef. The DNS Service Discovery implmementation uses
461 this socket to communicate between the client and the mDNSResponder daemon. The application MUST NOT directly read
462 from or write to this socket. Access to the socket is provided so that it can be used as a run loop source, or in a
463 select() loop: when data is available for reading on the socket, DNSServiceProcessResult() should be called, which will
464 extract the daemon's reply from the socket, and pass it to the appropriate application callback. By using a run loop
465 or select(), results from the daemon can be processed asynchronously. Without using these constructs,
466 DNSServiceProcessResult() will block until the response from the daemon arrives. The client is responsible for ensuring
467 that the data on the socket is processed in a timely fashion - the daemon may terminate its connection with a client
468 that does not clear its socket buffer.
469 */
470
471 int DNSServiceRefSockFD( DNSServiceRef inRef );
472
473 //---------------------------------------------------------------------------------------------------------------------------
474 /*! @function DNSServiceProcessResult
475
476 @param inRef A DNSServiceRef initialized by any of the DNSService calls that take a callback parameter.
477
478 @result Returns kDNSServiceErr_NoError on success, otherwise returns an error code indicating the specific failure
479 that occurred.
480
481 @discussion
482
483 Read a reply from the daemon, calling the appropriate application callback. This call will block until the daemon's
484 response is received. Use DNSServiceRefSockFD() in conjunction with a run loop or select() to determine the presence
485 of a response from the server before calling this function to process the reply without blocking. Call this function
486 at any point if it is acceptable to block until the daemon's response arrives. Note that the client is responsible
487 for ensuring that DNSServiceProcessResult() is called whenever there is a reply from the daemon - the daemon may
488 terminate its connection with a client that does not process the daemon's responses.
489 */
490
491 DNSServiceErrorType DNSServiceProcessResult( DNSServiceRef inRef );
492
493 //---------------------------------------------------------------------------------------------------------------------------
494 /*! @function DNSServiceRefDeallocate
495
496 @param inRef A DNSServiceRef initialized by any of the DNSService calls.
497
498 @discussion
499
500 Terminate a connection with the daemon and free memory associated with the DNSServiceRef. Any services or records
501 registered with this DNSServiceRef will be deregistered. Any Browse, Resolve, or Query operations called with this
502 reference will be terminated.
503
504 Note: If the reference's underlying socket is used in a run loop or select() call, it should be removed BEFORE
505 DNSServiceRefDeallocate() is called, as this function closes the reference's socket.
506
507 Note: If the reference was initialized with DNSServiceCreateConnection(), any DNSRecordRefs created via this reference
508 will be invalidated by this call - the resource records are deregistered, and their DNSRecordRefs may not be used in
509 subsequent functions. Similarly, if the reference was initialized with DNSServiceRegister, and an extra resource record
510 was added to the service via DNSServiceAddRecord(), the DNSRecordRef created by the Add() call is invalidated when this
511 function is called - the DNSRecordRef may not be used in subsequent functions.
512
513 Note: This call is to be used only with the DNSServiceRef defined by this API. It is not compatible with
514 dns_service_discovery_ref objects defined in the legacy Mach-based DNSServiceDiscovery.h API.
515 */
516
517 void DNSServiceRefDeallocate( DNSServiceRef inRef );
518
519 #if 0
520 #pragma mark == Domain Enumeration ==
521 #endif
522
523 //---------------------------------------------------------------------------------------------------------------------------
524 /*! @typedef DNSServiceDomainEnumReply
525
526 @abstract Callback function for DNSServiceEnumerateDomains.
527
528 @param inRef
529 The DNSServiceRef initialized by DNSServiceEnumerateDomains().
530
531 @param inFlags
532 Possible values are:
533 1 (MoreComing)
534 2 (Add/Remove)
535 4 (Add Default)
536
537 @param inInterfaceIndex
538 Specifies the interface on which the domain exists. (The index for a given interface is determined
539 via the if_nametoindex() family of calls).
540
541 @param inErrorCode
542 Will be kDNSServiceErr_NoError (0) on success, otherwise indicates the failure that occurred (other
543 parameters are undefined if errorCode is nonzero).
544
545 @param inDomain
546 The name of the domain.
547
548 @param inContext
549 The context pointer passed to DNSServiceEnumerateDomains.
550 */
551
552 typedef void
553 ( CALLBACK_COMPAT *DNSServiceDomainEnumReply )(
554 DNSServiceRef inRef,
555 DNSServiceFlags inFlags,
556 uint32_t inInterfaceIndex,
557 DNSServiceErrorType inErrorCode,
558 const char * inDomain,
559 void * inContext );
560
561 //---------------------------------------------------------------------------------------------------------------------------
562 /*! @function DNSServiceEnumerateDomains
563
564 @abstract Asynchronously enumerate domains available for browsing and registration.
565
566 @param outRef
567 A pointer to an uninitialized DNSServiceRef. May be passed to DNSServiceRefDeallocate() to cancel the
568 enumeration.
569
570 @param inFlags
571 Possible values are:
572 64 (BrowseDomains) to enumerate domains recommended for browsing.
573 128 (RegistrationDomains) to enumerate domains recommended for registration.
574
575 @param inInterfaceIndex
576 If non-zero, specifies the interface on which to look for domains (the index for a given interface is
577 determined via the if_nametoindex() family of calls). Most applications will pass 0 to enumerate
578 domains on all interfaces.
579
580 @param inCallBack
581 The function to be called when a domain is found or the call asynchronously fails.
582
583 @param inContext
584 An application context pointer which is passed to the callback function (may be NULL).
585
586 @result Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous errors are delivered to the
587 callback), otherwise returns an error code indicating the error that occurred (the callback is not invoked
588 and the DNSServiceRef is not initialized).
589
590 @discussion
591
592 Currently, the only domain returned is "local.", but other domains will be returned in future.
593
594 The enumeration MUST be cancelled via DNSServiceRefDeallocate() when no more domains are to be found.
595 */
596
597 DNSServiceErrorType
598 DNSServiceEnumerateDomains(
599 DNSServiceRef * outRef,
600 const DNSServiceFlags inFlags,
601 const uint32_t inInterfaceIndex,
602 const DNSServiceDomainEnumReply inCallBack,
603 void * inContext ); // may be NULL
604
605 #if 0
606 #pragma mark == Service Registration ==
607 #endif
608
609 //---------------------------------------------------------------------------------------------------------------------------
610 /*! @typedef DNSServiceRegisterReply
611
612 @abstract Callback function for DNSServiceRegister.
613
614 @param inRef
615 The DNSServiceRef initialized by DNSServiceRegister().
616
617 @param inFlags
618 Currently unused, reserved for future use.
619
620 @param inErrorCode
621 Will be kDNSServiceErr_NoError on success, otherwise will indicate the failure that occurred
622 (including name conflicts, if the kDNSServiceFlagsNoAutoRenameOnConflict flag was passed to the
623 callout). Other parameters are undefined if errorCode is nonzero.
624
625 @param inName
626 The service name registered (if the application did not specify a name in DNSServiceRegister(), this
627 indicates what name was automatically chosen).
628
629 @param inType
630 The type of service registered, as it was passed to the callout.
631
632 @param inDomain
633 The domain on which the service was registered (if the application did not specify a domain in
634 DNSServiceRegister(), this indicates the default domain on which the service was registered).
635
636 @param inContext
637 The context pointer that was passed to the callout.
638 */
639
640 typedef void
641 ( CALLBACK_COMPAT *DNSServiceRegisterReply )(
642 DNSServiceRef inRef,
643 DNSServiceFlags inFlags,
644 DNSServiceErrorType inErrorCode,
645 const char * inName,
646 const char * inType,
647 const char * inDomain,
648 void * inContext );
649
650 //---------------------------------------------------------------------------------------------------------------------------
651 /*! @function DNSServiceRegister
652
653 @abstract Register a service that is discovered via Browse() and Resolve() calls.
654
655 @param outRef
656 A pointer to an uninitialized DNSServiceRef. If this call succeeds, the reference may be passed to
657 DNSServiceRefDeallocate() to deregister the service.
658
659 @param inInterfaceIndex
660 If non-zero, specifies the interface on which to register the service (the index for a given interface
661 is determined via the if_nametoindex() family of calls). Most applications will pass 0 to register on
662 all available interfaces. Pass -1 to register a service only on the local machine (service will not be
663 visible to remote hosts).
664
665 @param inFlags
666 Indicates the renaming behavior on name conflict (most applications will pass 0). See flag definitions
667 above for details.
668
669 @param inName
670 If non-NULL, specifies the service name to be registered. Most applications will not specify a name, in
671 which case the computer name is used (this name is communicated to the client via the callback).
672
673 @param inType
674 The service type followed by the protocol, separated by a dot (e.g. "_ftp._tcp"). The transport protocol
675 must be "_tcp" or "_udp".
676
677 @param inDomain
678 If non-NULL, specifies the domain on which to advertise the service. Most applications will not specify
679 a domain, instead automatically registering in the default domain(s).
680
681 @param inHost
682 If non-NULL, specifies the SRV target host name. Most applications will not specify a host, instead
683 automatically using the machine's default host name(s). Note that specifying a non-NULL host does NOT
684 create an address record for that host - the application is responsible for ensuring that the appropriate
685 address record exists, or creating it via DNSServiceRegisterRecord().
686
687 @param inPort
688 The port on which the service accepts connections in network byte order. Pass 0 for a "placeholder"
689 service (i.e. a service that will not be discovered by browsing, but will cause a name conflict if
690 another client tries to register that same name). Most clients will not use placeholder services.
691
692 @param inTXTSize
693 The length of the txtRecord, in bytes. Must be zero if the txtRecord is NULL.
694
695 @param inTXT
696 The txt record rdata. May be NULL. Note that a non-NULL txtRecord MUST be a properly formatted DNS TXT
697 record, i.e. <length byte> <data> <length byte> <data> ...
698
699 @param inCallBack
700 The function to be called when the registration completes or asynchronously fails. The client MAY pass
701 NULL for the callback - The client will NOT be notified of the default values picked on its behalf, and
702 the client will NOT be notified of any asynchronous errors (e.g. out of memory errors, etc). that may
703 prevent the registration of the service. The client may NOT pass the NoAutoRename flag if the callback
704 is NULL. The client may still deregister the service at any time via DNSServiceRefDeallocate().
705
706 @param inContext
707 An application context pointer which is passed to the callback function (may be NULL).
708
709 @result Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous errors are delivered to the
710 callback), otherwise returns an error code indicating the error that occurred (the callback is never invoked
711 and the DNSServiceRef is not initialized).
712 */
713
714 DNSServiceErrorType
715 DNSServiceRegister(
716 DNSServiceRef * outRef,
717 DNSServiceFlags inFlags,
718 uint32_t inInterfaceIndex,
719 const char * inName, // may be NULL
720 const char * inType,
721 const char * inDomain, // may be NULL
722 const char * inHost, // may be NULL
723 uint16_t inPort,
724 uint16_t inTXTSize,
725 const void * inTXT, // may be NULL
726 DNSServiceRegisterReply inCallBack, // may be NULL
727 void * inContext ); // may be NULL
728
729 //---------------------------------------------------------------------------------------------------------------------------
730 /*! @function DNSServiceAddRecord
731
732 @abstract Add a record to a registered service.
733
734 @param inRef
735 A DNSServiceRef initialized by DNSServiceRegister().
736
737 @param inRecordRef
738 A pointer to an uninitialized DNSRecordRef. Upon succesfull completion of this call, this ref may be
739 passed to DNSServiceUpdateRecord() or DNSServiceRemoveRecord(). If the above DNSServiceRef is passed
740 to DNSServiceRefDeallocate(), RecordRef is also invalidated and may not be used further.
741
742 @param inFlags
743 Currently ignored, reserved for future use.
744
745 @param inRRType
746 The type of the record (e.g. TXT, SRV, etc), as defined in nameser.h.
747
748 @param inRDataSize
749 The length, in bytes, of the rdata.
750
751 @param inRData
752 The raw rdata to be contained in the added resource record.
753
754 @param inTTL
755 The time to live of the resource record, in seconds.
756
757 @result Returns kDNSServiceErr_NoError on success, otherwise returns an error code indicating the error that
758 occurred (the RecordRef is not initialized).
759
760 @discussion
761
762 The name of the record will be the same as the registered service's name. The record can later be updated or
763 deregistered by passing the RecordRef initialized by this function to DNSServiceUpdateRecord() or
764 DNSServiceRemoveRecord().
765 */
766
767 DNSServiceErrorType
768 DNSServiceAddRecord(
769 DNSServiceRef inRef,
770 DNSRecordRef * inRecordRef,
771 DNSServiceFlags inFlags,
772 uint16_t inRRType,
773 uint16_t inRDataSize,
774 const void * inRData,
775 uint32_t inTTL );
776
777 //---------------------------------------------------------------------------------------------------------------------------
778 /*! @function DNSServiceUpdateRecord
779
780 @abstract Update a registered resource record.
781
782 @param inRef
783 A DNSServiceRef that was initialized by DNSServiceRegister() or DNSServiceCreateConnection().
784
785 @param inRecordRef
786 A DNSRecordRef initialized by DNSServiceAddRecord, or NULL to update the service's primary txt record.
787
788 @param inFlags
789 Currently ignored, reserved for future use.
790
791 @param inRDataSize
792 The length, in bytes, of the new rdata.
793
794 @param inRData
795 The new rdata to be contained in the updated resource record.
796
797 @param inTTL
798 The time to live of the updated resource record, in seconds.
799
800 @result Returns kDNSServiceErr_NoError on success, otherwise returns an error code indicating the error that occurred.
801
802 @discussion
803
804 The record must either be:
805 - The primary txt record of a service registered via DNSServiceRegister()
806 - A record added to a registered service via DNSServiceAddRecord()
807 - An individual record registered by DNSServiceRegisterRecord()
808 */
809
810 DNSServiceErrorType
811 DNSServiceUpdateRecord(
812 DNSServiceRef inRef,
813 DNSRecordRef inRecordRef, // may be NULL
814 DNSServiceFlags inFlags,
815 uint16_t inRDataSize,
816 const void * inRData,
817 uint32_t inTTL );
818
819 //---------------------------------------------------------------------------------------------------------------------------
820 /*! @function DNSServiceRemoveRecord
821
822 @abstract Remove a record previously added to a service record set via DNSServiceAddRecord(), or deregister
823 an record registered individually via DNSServiceRegisterRecord().
824
825 @param inRef
826 A DNSServiceRef that was initialized by DNSServiceRegister() or DNSServiceCreateConnection().
827
828 @param inRecordRef
829 A DNSRecordRef initialized by a successful call to DNSServiceAddRecord() or DNSServiceRegisterRecord().
830
831 @param inFlags
832 Currently ignored, reserved for future use.
833
834 @result Returns kDNSServiceErr_NoError on success, otherwise returns an error code indicating the error that occurred.
835 */
836
837 DNSServiceErrorType
838 DNSServiceRemoveRecord(
839 DNSServiceRef inRef,
840 DNSRecordRef inRecordRef,
841 DNSServiceFlags inFlags );
842
843 #if 0
844 #pragma mark == Service Discovery ==
845 #endif
846
847 //---------------------------------------------------------------------------------------------------------------------------
848 /*! @typedef DNSServiceBrowseReply
849
850 @abstract Callback function for DNSServiceBrowse.
851
852 @param inRef
853 The DNSServiceRef initialized by DNSServiceBrowse().
854
855 @param inFlags
856 Possible values are MoreComing and Add/Remove. See flag definitions for details.
857
858 @param inInterfaceIndex
859 The interface on which the service is advertised. This index should be passed to DNSServiceResolve()
860 when resolving the service.
861
862 @param inErrorCode
863 Will be kDNSServiceErr_NoError (0) on success, otherwise will indicate the failure that occurred.
864 Other parameters are undefined if the errorCode is nonzero.
865
866 @param inName
867 The service name discovered.
868
869 @param inType
870 The service type, as passed in to DNSServiceBrowse().
871
872 @param inDomain
873 The domain on which the service was discovered (if the application did not specify a domain in
874 DNSServicBrowse(), this indicates the domain on which the service was discovered).
875
876 @param inContext
877 The context pointer that was passed to the callout.
878 */
879
880 typedef void
881 ( CALLBACK_COMPAT *DNSServiceBrowseReply )(
882 DNSServiceRef inRef,
883 DNSServiceFlags inFlags,
884 uint32_t inInterfaceIndex,
885 DNSServiceErrorType inErrorCode,
886 const char * inName,
887 const char * inType,
888 const char * inDomain,
889 void * inContext );
890
891 //---------------------------------------------------------------------------------------------------------------------------
892 /*! @function DNSServiceBrowse
893
894 @abstract Browse for instances of a service.
895
896 @param outRef
897 A pointer to an uninitialized DNSServiceRef. May be passed to DNSServiceRefDeallocate() to terminate
898 the browse.
899
900 @param inFlags
901 Currently ignored, reserved for future use.
902
903 @param inInterfaceIndex
904 If non-zero, specifies the interface on which to browse for services (the index for a given interface
905 is determined via the if_nametoindex() family of calls). Most applications will pass 0 to browse on all
906 available interfaces. Pass -1 to only browse for services provided on the local host.
907
908 @param inType
909 The service type being browsed for followed by the protocol, separated by a dot (e.g. "_ftp._tcp").
910 The transport protocol must be "_tcp" or "_udp".
911
912 @param inDomain
913 If non-NULL, specifies the domain on which to browse for services. Most applications will not specify a
914 domain, instead browsing on the default domain(s).
915
916 @param inCallBack
917 The function to be called when an instance of the service being browsed for is found, or if the call
918 asynchronously fails.
919
920 @param inContext
921 An application context pointer which is passed to the callback function (may be NULL).
922
923 @result Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous errors are delivered to the
924 callback), otherwise returns an error code indicating the error that occurred (the callback is not invoked
925 and the DNSServiceRef is not initialized).
926 */
927
928 DNSServiceErrorType
929 DNSServiceBrowse(
930 DNSServiceRef * outRef,
931 DNSServiceFlags inFlags,
932 uint32_t inInterfaceIndex,
933 const char * inType,
934 const char * inDomain, // may be NULL
935 DNSServiceBrowseReply inCallBack,
936 void * inContext ); // may be NULL
937
938 //---------------------------------------------------------------------------------------------------------------------------
939 /*! @typedef DNSServiceResolveReply
940
941 @abstract Callback function for DNSServiceResolve.
942
943 @param inRef
944 The DNSServiceRef initialized by DNSServiceResolve().
945
946 @param inFlags
947 Currently unused, reserved for future use.
948
949 @param inInterfaceIndex
950 The interface on which the service was resolved.
951
952 @param inErrorCode
953 Will be kDNSServiceErr_NoError (0) on success, otherwise will indicate the failure that occurred.
954 Other parameters are undefined if the errorCode is nonzero.
955
956 @param inFullName
957 The full service domain name, in the form <servicename>.<protocol>.<domain>. (Any literal dots (".")
958 are escaped with a backslash ("\."), and literal backslashes are escaped with a second backslash ("\\"),
959 e.g. a web server named "Dr. Pepper" would have the fullname "Dr\.\032Pepper._http._tcp.local.").
960 This is the appropriate format to pass to standard system DNS APIs such as res_query(), or to the
961 special-purpose functions included in this API that take fullname parameters.
962
963 @param inHostName
964 The target hostname of the machine providing the service. This name can be passed to functions like
965 gethostbyname() to identify the host's IP address.
966
967 @param inPort
968 The port number on which connections are accepted for this service in network byte order.
969
970 @param inTXTSize
971 The length of the txt record, in bytes.
972
973 @param inTXT
974 The service's primary txt record, in standard txt record format.
975
976 @param inContext
977 The context pointer that was passed to the callout.
978 */
979
980 typedef void
981 ( CALLBACK_COMPAT *DNSServiceResolveReply )(
982 DNSServiceRef inRef,
983 DNSServiceFlags inFlags,
984 uint32_t inInterfaceIndex,
985 DNSServiceErrorType inErrorCode,
986 const char * inFullName,
987 const char * inHostName,
988 uint16_t inPort,
989 uint16_t inTXTSize,
990 const char * inTXT,
991 void * inContext );
992
993 //---------------------------------------------------------------------------------------------------------------------------
994 /*! @function DNSServiceResolve
995
996 @abstract Resolve a service name discovered via DNSServiceBrowse() to a target host name, port number, and txt record.
997
998 @param outRef
999 A pointer to an uninitialized DNSServiceRef. May be passed to DNSServiceRefDeallocate() to terminate
1000 the resolve.
1001
1002 @param inFlags
1003 Currently unused, reserved for future use.
1004
1005 @param inInterfaceIndex
1006 The interface on which to resolve the service. The client should pass the interface on which the
1007 servicename was discovered, i.e. the inInterfaceIndex passed to the DNSServiceBrowseReply callback, or 0
1008 to resolve the named service on all available interfaces.
1009
1010 @param inName
1011 The service name to be resolved.
1012
1013 @param inType
1014 The service type being resolved followed by the protocol, separated by a dot (e.g. "_ftp._tcp"). The
1015 transport protocol must be "_tcp" or "_udp".
1016
1017 @param inDomain
1018 The domain on which the service is registered, i.e. the domain passed to the DNSServiceBrowseReply
1019 callback.
1020
1021 @param inCallBack
1022 The function to be called when a result is found, or if the call asynchronously fails.
1023
1024 @param inContext
1025 An application context pointer which is passed to the callback function (may be NULL).
1026
1027 @result Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous errors are delivered to the
1028 callback), otherwise returns an error code indicating the error that occurred (the callback is never
1029 invoked and the DNSServiceRef is not initialized). The context pointer that was passed to the callout.
1030
1031 @discussion
1032
1033 Resolve a service name discovered via DNSServiceBrowse() to a target host name, port number, and txt record.
1034
1035 Note: Applications should NOT use DNSServiceResolve() solely for txt record monitoring - use DNSServiceQueryRecord()
1036 instead, as it is more efficient for this task.
1037
1038 Note: When the desired results have been returned, the client MUST terminate the resolve by calling
1039 DNSServiceRefDeallocate().
1040
1041 Note: DNSServiceResolve() behaves correctly for typical services that have a single SRV record and a single TXT record
1042 (the TXT record may be empty). To resolve non-standard services with multiple SRV or TXT records,
1043 DNSServiceQueryRecord() should be used.
1044 */
1045
1046 DNSServiceErrorType
1047 DNSServiceResolve(
1048 DNSServiceRef * outRef,
1049 DNSServiceFlags inFlags,
1050 uint32_t inInterfaceIndex,
1051 const char * inName,
1052 const char * inType,
1053 const char * inDomain,
1054 DNSServiceResolveReply inCallBack,
1055 void * inContext ); // may be NULL
1056
1057 #if 0
1058 #pragma mark == Special Purpose ==
1059 #endif
1060
1061 //---------------------------------------------------------------------------------------------------------------------------
1062 /*! @function DNSServiceConstructFullName
1063
1064 @abstract Concatenate a three-part domain name (as returned by the above callbacks) into a properly-escaped full
1065 domain name. Note that callbacks in the above functions ALREADY ESCAPE strings where necessary.
1066
1067 @param outFullName
1068 A pointer to a buffer that where the resulting full domain name is to be written. The buffer must be
1069 kDNSServiceDiscoveryMaxDomainName (1005) bytes in length to accommodate the longest legal domain name
1070 without buffer overrun.
1071
1072 @param inName
1073 The service name - any dots or slashes must NOT be escaped. May be NULL (to construct a PTR record
1074 name, e.g. "_ftp._tcp.apple.com").
1075
1076 @param inType
1077 The service type followed by the protocol, separated by a dot (e.g. "_ftp._tcp").
1078
1079 @param inDomain
1080 The domain name, e.g. "apple.com". Any literal dots or backslashes must be escaped.
1081
1082 @result Returns 0 on success, -1 on error.
1083
1084 @discussion
1085
1086 DNS Naming Conventions:
1087
1088 The following functions refer to resource records by their full domain name, unlike the above
1089 functions which divide the name into servicename/regtype/domain fields. In the above functions,
1090 a dot (".") is considered to be a literal dot in the servicename field (e.g. "Dr. Pepper") and
1091 a label separator in the regtype ("_ftp._tcp") or domain ("apple.com") fields. Literal dots in
1092 the domain field would be escaped with a backslash, and literal backslashes would be escaped with
1093 a second backslash (this is generally not an issue, as domain names on the Internet today almost
1094 never use characters other than letters, digits, or hyphens, and the dots are label separators).
1095 Furthermore, this is transparent to the caller, so long as the fields are passed between functions
1096 without manipulation. However, the following, special-purpose calls use a single, full domain name.
1097 As such, all dots are considered to be label separators, unless escaped, and all backslashes are
1098 considered to be escape characters, unless preceded by a second backslash. For example, the name
1099 "Dr. Smith \ Dr. Johnson" could be passed literally as a service name parameter in the above calls,
1100 but in the special purpose call, the dots and backslash would have to be escaped
1101 (e.g. "Dr\. Smith \\ Dr\. Johnson._ftp._tcp.apple.com" for an ftp service on the apple.com domain).
1102 */
1103
1104 int
1105 DNSServiceConstructFullName(
1106 char * outFullName,
1107 const char * inName, // may be NULL
1108 const char * inType,
1109 const char * inDomain );
1110
1111 //---------------------------------------------------------------------------------------------------------------------------
1112 /*! @function DNSServiceCreateConnection
1113
1114 @abstract Create a connection to the daemon allowing efficient registration of multiple individual records.
1115
1116 @param outRef
1117 A pointer to an uninitialized DNSServiceRef. Deallocating the reference (via DNSServiceRefDeallocate())
1118 severs the connection and deregisters all records registered on this connection.
1119
1120 @result Returns kDNSServiceErr_NoError on success, otherwise returns an error code indicating the specific failure
1121 that occurred (in which case the DNSServiceRef is not initialized).
1122
1123 */
1124
1125 DNSServiceErrorType DNSServiceCreateConnection( DNSServiceRef *outRef );
1126
1127 //---------------------------------------------------------------------------------------------------------------------------
1128 /*! @typedef DNSServiceRegisterRecordReply
1129
1130 @abstract Callback function for DNSServiceRegisterRecord.
1131
1132 @param inRef
1133 The connected DNSServiceRef initialized by DNSServiceCreateConnection().
1134
1135 @param inRecordRef
1136 The DNSRecordRef initialized by DNSServiceRegisterRecord(). If the above DNSServiceRef is passed to
1137 DNSServiceRefDeallocate(), this DNSRecordRef is invalidated, and may not be used further.
1138
1139 @param inFlags
1140 Currently unused, reserved for future use.
1141
1142 @param inErrorCode
1143 Will be kDNSServiceErr_NoError on success, otherwise will indicate the failure that occurred (including
1144 name conflicts). Other parameters are undefined if errorCode is nonzero.
1145
1146 @param inContext
1147 The context pointer that was passed to the callout.
1148 */
1149
1150 typedef void
1151 ( CALLBACK_COMPAT *DNSServiceRegisterRecordReply )(
1152 DNSServiceRef inRef,
1153 DNSRecordRef inRecordRef,
1154 DNSServiceFlags inFlags,
1155 DNSServiceErrorType inErrorCode,
1156 void * inContext );
1157
1158 //---------------------------------------------------------------------------------------------------------------------------
1159 /*! @function DNSServiceRegisterRecord
1160
1161 @abstract Register an individual resource record on a connected DNSServiceRef.
1162
1163 @param inRef
1164 A DNSServiceRef initialized by DNSServiceCreateConnection().
1165
1166 @param inRecordRef
1167 A pointer to an uninitialized DNSRecordRef. Upon succesfull completion of this call, this ref may be
1168 passed to DNSServiceUpdateRecord() or DNSServiceRemoveRecord(). (To deregister ALL records registered
1169 on a single connected DNSServiceRef and deallocate each of their corresponding DNSServiceRecordRefs,
1170 call DNSServiceRefDealloocate()).
1171
1172 @param inFlags
1173 Possible values are Shared/Unique (see flag type definitions for details).
1174
1175 @param inInterfaceIndex
1176 If non-zero, specifies the interface on which to register the record (the index for a given interface
1177 is determined via the if_nametoindex() family of calls). Passing 0 causes the record to be registered
1178 on all interfaces. Passing -1 causes the record to only be visible on the local host.
1179
1180 @param inFullName
1181 The full domain name of the resource record.
1182
1183 @param inRRType
1184 The numerical type of the resource record (e.g. PTR, SRV, etc), as defined in nameser.h.
1185
1186 @param inRRClass
1187 The class of the resource record, as defined in nameser.h (usually 1 for the Internet class).
1188
1189 @param inRDataSize
1190 Length, in bytes, of the rdata.
1191
1192 @param inRData
1193 A pointer to the raw rdata, as it is to appear in the DNS record.
1194
1195 @param inTTL
1196 The time to live of the resource record, in seconds.
1197
1198 @param inCallBack
1199 The function to be called when a result is found, or if the call asynchronously fails (e.g. because
1200 of a name conflict).
1201
1202 @param inContext
1203 An application context pointer which is passed to the callback function (may be NULL).
1204
1205 @result Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous errors are delivered to the
1206 callback), otherwise returns an error code indicating the error that occurred (the callback is never
1207 invoked and the DNSRecordRef is not initialized).
1208
1209 @discussion
1210
1211 Note that name conflicts occurring for records registered via this call must be handled by the client in the callback.
1212 */
1213
1214 DNSServiceErrorType
1215 DNSServiceRegisterRecord(
1216 DNSServiceRef inRef,
1217 DNSRecordRef * inRecordRef,
1218 DNSServiceFlags inFlags,
1219 uint32_t inInterfaceIndex,
1220 const char * inFullName,
1221 uint16_t inRRType,
1222 uint16_t inRRClass,
1223 uint16_t inRDataSize,
1224 const void * inRData,
1225 uint32_t inTTL,
1226 DNSServiceRegisterRecordReply inCallBack,
1227 void * inContext );
1228
1229 //---------------------------------------------------------------------------------------------------------------------------
1230 /*! @typedef DNSServiceQueryRecordReply
1231
1232 @abstract Callback function for DNSServiceQueryRecord.
1233
1234 @param inRef
1235 The DNSServiceRef initialized by DNSServiceQueryRecord().
1236
1237 @param inFlags
1238 Possible values are Finished/MoreComing and Add/Remove. The Remove flag is set for PTR records with
1239 a TTL of 0.
1240
1241 @param inInterfaceIndex
1242 The interface on which the query was resolved (the index for a given interface is determined via the
1243 if_nametoindex() family of calls).
1244
1245 @param inErrorCode
1246 Will be kDNSServiceErr_NoError on success, otherwise will indicate the failure that occurred. Other
1247 parameters are undefined if errorCode is nonzero.
1248
1249 @param inFullName
1250 The resource record's full domain name.
1251
1252 @param inRRType
1253 The resource record's type (e.g. PTR, SRV, etc) as defined in nameser.h.
1254
1255 @param inRRClass
1256 The class of the resource record, as defined in nameser.h (usually 1).
1257
1258 @param inRDataSize
1259 The length, in bytes, of the resource record rdata.
1260
1261 @param inRData
1262 The raw rdata of the resource record.
1263
1264 @param inTTL
1265 The resource record's time to live, in seconds.
1266
1267 @param inContext
1268 The context pointer that was passed to the callout.
1269 */
1270
1271 typedef void
1272 ( CALLBACK_COMPAT *DNSServiceQueryRecordReply )(
1273 DNSServiceRef inRef,
1274 DNSServiceFlags inFlags,
1275 uint32_t inInterfaceIndex,
1276 DNSServiceErrorType inErrorCode,
1277 const char * inFullName,
1278 uint16_t inRRType,
1279 uint16_t inRRClass,
1280 uint16_t inRDataSize,
1281 const void * inRData,
1282 uint32_t inTTL,
1283 void * inContext );
1284
1285 //---------------------------------------------------------------------------------------------------------------------------
1286 /*! @function DNSServiceQueryRecord
1287
1288 @abstract Query for an arbitrary DNS record.
1289
1290 @param outRef
1291 A pointer to an uninitialized DNSServiceRef.
1292
1293 @param inFlags
1294 Currently unused, reserved for future use.
1295
1296 @param inInterfaceIndex
1297 If non-zero, specifies the interface on which to issue the query (the index for a given interface is
1298 determined via the if_nametoindex() family of calls). Passing 0 causes the name to be queried for on all
1299 interfaces. Passing -1 causes the name to be queried for only on the local host.
1300
1301 @param inName
1302 The full domain name of the resource record to be queried for.
1303
1304 @param inRRType
1305 The numerical type of the resource record to be queried for (e.g. PTR, SRV, etc) as defined in nameser.h.
1306
1307 @param inRRClass
1308 The class of the resource record, as defined in nameser.h (usually 1 for the Internet class).
1309
1310 @param inCallBack
1311 The function to be called when a result is found, or if the call asynchronously fails.
1312
1313 @param inContext
1314 An application context pointer which is passed to the callback function (may be NULL).
1315
1316 @result Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous errors are delivered to the
1317 callback), otherwise returns an error code indicating the error that occurred (the callback is never
1318 invoked and the DNSServiceRef is not initialized).
1319
1320 @discussion
1321
1322 Note that name conflicts occurring for records registered via this call must be handled by the client in the callback.
1323 */
1324
1325 DNSServiceErrorType
1326 DNSServiceQueryRecord(
1327 DNSServiceRef * outRef,
1328 DNSServiceFlags inFlags,
1329 uint32_t inInterfaceIndex,
1330 const char * inName,
1331 uint16_t inRRType,
1332 uint16_t inRRClass,
1333 DNSServiceQueryRecordReply inCallBack,
1334 void * inContext ); // may be NULL
1335
1336 //---------------------------------------------------------------------------------------------------------------------------
1337 /*! @function DNSServiceReconfirmRecord
1338
1339 @abstract Instruct the daemon to verify the validity of a resource record that appears to be out of date (e.g.
1340 because tcp connection to a service's target failed). Causes the record to be flushed from the daemon's
1341 cache (as well as all other daemons' caches on the network) if the record is determined to be invalid.
1342
1343 @param inFlags
1344 Currently unused, reserved for future use.
1345
1346 @param inName
1347 The resource record's full domain name.
1348
1349 @param inRRType
1350 The resource record's type (e.g. PTR, SRV, etc) as defined in nameser.h.
1351
1352 @param inRRClass
1353 The class of the resource record, as defined in nameser.h (usually 1).
1354
1355 @param inRDataSize
1356 The length, in bytes, of the resource record rdata.
1357
1358 @param inRData
1359 The raw rdata of the resource record.
1360 */
1361
1362 void
1363 DNSServiceReconfirmRecord(
1364 DNSServiceFlags inFlags,
1365 uint32_t inInterfaceIndex,
1366 const char * inName,
1367 uint16_t inRRType,
1368 uint16_t inRRClass,
1369 uint16_t inRDataSize,
1370 const void * inRData );
1371
1372 #if 0
1373 #pragma mark == TXT Record Building ==
1374 #endif
1375
1376 //---------------------------------------------------------------------------------------------------------------------------
1377 /*! @typedef TXTRecordRef
1378
1379 @abstract Reference to a TXTRecord object representing a DNS-SD TXT record.
1380
1381 @discussion
1382
1383 Note: client is responsible for serializing access to these structures if they are shared between concurrent threads.
1384 */
1385
1386 typedef struct _TXTRecordRef_t * TXTRecordRef;
1387
1388 //---------------------------------------------------------------------------------------------------------------------------
1389 /*! @function TXTRecordCreate
1390
1391 @abstract Creates an empty TXTRecordRef.
1392
1393 @param outRef
1394 A pointer to an uninitialized TXTRecordRef. Filled in on success.
1395
1396 @result Returns kDNSServiceErr_NoError on success.
1397 Returns kDNSServiceErr_BadParam if the reference pointer is NULL.
1398 Returns kDNSServiceErr_NoMemory if there is not enough memory to create the TXTRecord.
1399
1400 @discussion
1401
1402 Once you've created a TXTRecordRef, you can pass it to TXTRecordSetValue and other functions to add "key=value"
1403 pairs to it. Finally, you can extract the raw bytes again to pass to DNSServiceRegister() or DNSServiceUpdateRecord().
1404
1405 A typical calling sequence for TXT record construction is something like:
1406
1407 TXTRecordCreate();
1408 TXTRecordSetValue();
1409 TXTRecordSetValue();
1410 TXTRecordSetValue();
1411 ...
1412 DNSServiceRegister( ... TXTRecordGetLength(), TXTRecordGetBytesPtr() ... );
1413 TXTRecordDeallocate();
1414 */
1415
1416 DNSServiceErrorType TXTRecordCreate( TXTRecordRef *outRef );
1417
1418 //---------------------------------------------------------------------------------------------------------------------------
1419 /*! @function TXTRecordDeallocate
1420
1421 @abstract Releases the memory associated with a TXTRecordRef.
1422
1423 @param inRef
1424 A TXTRecordRef initialized by calling TXTRecordCreate.
1425 */
1426
1427 void TXTRecordDeallocate( TXTRecordRef inRef );
1428
1429 //---------------------------------------------------------------------------------------------------------------------------
1430 /*! @function TXTRecordSetValue
1431
1432 @abstract Adds a key (optionally with a value) to a TXTRecordRef.
1433
1434 @param inRef
1435 A TXTRecordRef initialized by TXTRecordCreate.
1436
1437 @param inKey
1438 Null-terminated key of the value to add. Must be at least 1 character and consist of only printable
1439 US-ASCII characters (0x20-0x7E), excluding '=' (0x3D). Should be 14 characters or less (not counting
1440 the terminating null). Keys are case insensitive (i.e. key "test" replaces key "TEST").
1441
1442 @param inValue
1443 Pointer to value to add. For values that represent textual data, UTF-8 is STRONGLY recommended.
1444 If NULL, then the key will be added with no value.
1445 If non-NULL but valueSize is zero, then "key=" will be added with an empty value.
1446
1447 @param inValueSize
1448 Number of bytes in the value. Must be 0 if inValue is NULL.
1449
1450 @result Returns kDNSServiceErr_NoError on success.
1451 Returns kDNSServiceErr_BadParam if the parameters are illegal or not supported.
1452 Returns kDNSServiceErr_Invalid if the key string contains illegal characters.
1453 Returns kDNSServiceErr_NoMemory if there is not enough memory to set the value.
1454
1455 @discussion
1456
1457 If the key is already present in the TXTRecordRef, then the current value will be replaced with the new value.
1458 Keys may be in four states with respect to a given TXT record:
1459
1460 - Absent (key does not appear at all).
1461 - Present with no value ("key" appears alone).
1462 - Present with empty value ("key=" appears in the TXT record).
1463 - Present with non-empty value ("key=value" appears in the TXT record).
1464
1465 For more details refer to "Data Syntax for DNS-SD TXT Records" in
1466 <http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt>
1467 */
1468
1469 DNSServiceErrorType
1470 TXTRecordSetValue(
1471 TXTRecordRef inRef,
1472 const char * inKey,
1473 uint8_t inValueSize, // may be zero
1474 const void * inValue ); // may be NULL
1475
1476 //---------------------------------------------------------------------------------------------------------------------------
1477 /*! @function TXTRecordRemoveValue
1478
1479 @abstract Removes a key from a TXTRecordRef.
1480
1481 @param inRef
1482 A TXTRecordRef initialized by TXTRecordCreate.
1483
1484 @param inKey
1485 Null-terminated key to remove. Note: keys are case insensitive.
1486
1487 @result Returns kDNSServiceErr_NoError on success.
1488 Returns kDNSServiceErr_NoSuchKey if the key is not present in the TXTRecordRef.
1489 Returns kDNSServiceErr_BadParam if the parameters are illegal or not supported.
1490 */
1491
1492 DNSServiceErrorType TXTRecordRemoveValue( TXTRecordRef inRef, const char *inKey );
1493
1494 //---------------------------------------------------------------------------------------------------------------------------
1495 /*! @function TXTRecordGetLength
1496
1497 @abstract Returns the number of raw bytes inside a TXTRecordRef.
1498
1499 @param inRef
1500 A TXTRecordRef initialized by TXTRecordCreate.
1501
1502 @result Returns the number of raw bytes inside a TXTRecordRef which you can pass directly to DNSServiceRegister()
1503 or to DNSServiceUpdateRecord(). Returns 0 if the TXTRecordRef is empty.
1504
1505 @discussion
1506
1507 The length may become invalid if you subsequently make changes to the TXTRecordRef by calling TXTRecordSetValue()
1508 or TXTRecordRemoveValue().
1509 */
1510
1511 uint16_t TXTRecordGetLength( TXTRecordRef inRef );
1512
1513 //---------------------------------------------------------------------------------------------------------------------------
1514 /*! @function TXTRecordGetBytesPtr
1515
1516 @abstract Returns a pointer to the raw bytes inside the TXTRecordRef.
1517
1518 @param inRef
1519 A TXTRecordRef initialized by TXTRecordCreate.
1520
1521 @result Returns a pointer to the raw bytes inside the TXTRecordRef which you can pass directly to
1522 DNSServiceRegister() or to DNSServiceUpdateRecord(). Returns NULL if the TXTRecordRef is empty.
1523
1524 @discussion
1525
1526 The pointer may become invalid if you subsequently make changes to the TXTRecordRef by calling TXTRecordSetValue()
1527 or TXTRecordRemoveValue().
1528 */
1529
1530 const void * TXTRecordGetBytesPtr( TXTRecordRef inRef );
1531
1532 #if 0
1533 #pragma mark == TXT Record Parsing ==
1534 #endif
1535
1536 /*---------------------------------------------------------------------------------------------------------------------------
1537 A typical calling sequence for TXT record parsing is something like:
1538 Receive TXT record data in the DNSServiceResolve() callback then:
1539
1540 cosnt void * value1Ptr;
1541 uint8_t value1Size;
1542
1543 err = TXTRecordGetValuePtr( txtSize, txtRecord, "key1", &value1Ptr, &value1Size );
1544 if( err == kDNSServiceErr_NoError )
1545 {
1546 // "key1" found. Do work with "value1Ptr" data if needed.
1547 }
1548 ...
1549 return;
1550
1551 If you wish to retain the values after returning from the DNSServiceResolve() callback, then you need to copy the data
1552 to your own storage using memcpy() or something similar so it does not go out of scope until you're done with it.
1553
1554 If for some reason you need to parse a TXT record you built yourself using the TXT record construction functions above,
1555 then you can do that using TXTRecordGetLength and TXTRecordGetBytesPtr functions:
1556
1557 TXTRecordGetValue( TXTRecordGetLength( x ), TXTRecordGetBytesPtr( x ), "key1", &value1Ptr, &value1Size );
1558
1559 Most applications only fetch keys they know about from a TXT record and ignore the rest.
1560 However, some debugging tools wish to fetch and display all keys. To do that, use the TXTRecordGetCount() and
1561 TXTRecordGetItemAtIndex() functions.
1562 */
1563
1564 //---------------------------------------------------------------------------------------------------------------------------
1565 /*! @function TXTRecordGetValuePtr
1566
1567 @abstract Allows you to retrieve the value for a given key from a TXT Record.
1568
1569 @param inTXTSize
1570 Number of bytes in the TXT record.
1571
1572 @param inTXTBytes
1573 Pointer to the raw TXT record bytes.
1574
1575 @param inKey
1576 A null-terminated key to search for. Note: keys are case insensitive.
1577
1578 @param outValue
1579 Pointer to be filled in with a pointer to the value within the TXT record bytes.
1580 Resulting pointer will be NULL if the key is present, but has no value.
1581 Resulting pointer will be non-NULL and size zero if the key is present, but has an empty value.
1582 Resulting pointer will be non-NULL and size non-zero if key is present and has a non-empty value.
1583 May be NULL if only interested in the value size or if the key is present.
1584
1585 @param outValueSize
1586 Pointer to receive the size of the value.
1587 Size will be 0 if there is no value or the value is empty.
1588 May be NULL if not interested in getting the size.
1589
1590 @result Returns kDNSServiceErr_NoError if a key with the specified name is found.
1591 Returns kDNSServiceErr_NoSuchKey if the key does not exist in the TXTRecordRef.
1592 Returns kDNSServiceErr_BadParam if the parameters are illegal or not supported.
1593 Returns kDNSServiceErr_Invalid if the TXT record is malformed.
1594
1595 @discussion
1596
1597 The pointer may become invalid if you subsequently make changes to the TXT record by calling TXTRecordSetValue()
1598 or TXTRecordRemoveValue().
1599 */
1600
1601 DNSServiceErrorType
1602 TXTRecordGetValuePtr(
1603 uint16_t inTXTSize,
1604 const void * inTXTBytes,
1605 const char * inKey,
1606 const void ** outValue, // may be NULL
1607 uint8_t * outValueSize ); // may be NULL
1608
1609 //---------------------------------------------------------------------------------------------------------------------------
1610 /*! @function TXTRecordGetCount
1611
1612 @abstract Returns the total number of keys in the TXT Record.
1613
1614 @param inTXTSize
1615 Number of bytes in the TXT record.
1616
1617 @param inTXTBytes
1618 Pointer to the raw TXT record bytes.
1619
1620 @result Returns the total number of keys in the TXT Record.
1621
1622 @discussion
1623
1624 The count can be used with TXTRecordGetItemAtIndex() to iterate through the keys.
1625 The count may become invalid if you subsequently make changes to the TXT record by calling TXTRecordSetValue()
1626 or TXTRecordRemoveValue().
1627 */
1628
1629 uint16_t TXTRecordGetCount( uint16_t inTXTSize, const void *inTXTBytes );
1630
1631 //---------------------------------------------------------------------------------------------------------------------------
1632 /*! @function TXTRecordGetItemAtIndex
1633
1634 @abstract Allows you to retrieve a key name, given an index into a TXT Record.
1635
1636 @param inTXTSize
1637 Number of bytes in the TXT record.
1638
1639 @param inTXTBytes
1640 Pointer to the raw TXT record bytes.
1641
1642 @param inIndex
1643 Index of item to get. The index is 0-based (0 is the first item).
1644 Legal index values range from 0 to TXTRecordGetCount() - 1.
1645
1646 @param inKeyBuffer
1647 A string buffer used to store the null-terminated key name. The buffer must be at least 256 bytes
1648 in order to hold the maximum possible key name.
1649 May be NULL if not interested in the key name.
1650
1651 @param outValue
1652 Pointer to be filled in with a pointer to the value within the TXT record bytes.
1653 Resulting pointer will be NULL if the key is present, but has no value.
1654 Resulting pointer will be non-NULL and size zero if the key is present, but has an empty value.
1655 Resulting pointer will be non-NULL and size non-zero if key is present and has a non-empty value.
1656 May be NULL if only interested in the value size or if the key is present.
1657
1658 @param outValueSize
1659 Pointer to receive the size of the value.
1660 Size will be 0 if there is no value or the value is empty.
1661 May be NULL if not interested in getting the size.
1662
1663 @result Returns kDNSServiceErr_NoError if a key with the specified name is found.
1664 Returns kDNSServiceErr_Invalid if the index is greater than TXTRecordGetCount() - 1 or the TXT record is malformed.
1665 Returns kDNSServiceErr_BadParam if the parameters are illegal or not supported.
1666
1667 @discussion
1668
1669 It also possible to iterate through keys in a TXT record by simply calling TXTRecordGetItemAtIndex() repeatedly,
1670 beginning with index zero and increasing until TXTRecordGetItemAtIndex() returns an non-zero error code.
1671
1672 The pointer may become invalid if you subsequently make changes to the TXTRecordRef by calling TXTRecordSetValue()
1673 or TXTRecordRemoveValue().
1674 */
1675
1676 DNSServiceErrorType
1677 TXTRecordGetItemAtIndex(
1678 uint16_t inTXTSize,
1679 const void * inTXTBytes,
1680 uint16_t inIndex,
1681 char * inKeyBuffer, // may be NULL
1682 const void ** outValue, // may be NULL
1683 uint8_t * outValueSize ); // may be NULL
1684
1685 #ifdef __cplusplus
1686 }
1687 #endif
1688
1689 #endif // _DNS_SD_H
mirror of mDNSResponder