]> git.saurik.com Git - apple/mdnsresponder.git/blob - mDNSWindows/DNSServices/DNSServices.h
projects / apple / mdnsresponder.git / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
blame | history | raw | HEAD
mDNSResponder-107.1.tar.gz
[apple/mdnsresponder.git] / mDNSWindows / DNSServices / DNSServices.h
1 /*
2 * Copyright (c) 2002-2004 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22
23 Change History (most recent first):
24
25 $Log: DNSServices.h,v $
26 Revision 1.11 2004/07/13 21:24:28 rpantos
27 Fix for <rdar://problem/3701120>.
28
29 Revision 1.10 2004/01/30 02:56:34 bradley
30 Updated to support full Unicode display. Added support for all services on www.dns-sd.org.
31
32 Revision 1.9 2003/10/31 12:16:03 bradley
33 Added support for providing the resolved host name to the callback.
34
35 Revision 1.8 2003/08/20 06:44:24 bradley
36 Updated to latest internal version of the mDNSCore code: Added support for interface
37 specific registrations; Added support for no-such-service registrations; Added support for host
38 name registrations; Added support for host proxy and service proxy registrations; Added support for
39 registration record updates (e.g. TXT record updates); Added support for using either a single C
40 string TXT record, a raw, pre-formatted TXT record potentially containing multiple character string
41 entries, or a C-string containing a Mac OS X-style \001-delimited set of TXT record character
42 strings; Added support in resolve callbacks for providing both a simplified C-string for TXT records
43 and a ptr/size for the raw TXT record data; Added utility routines for dynamically building TXT
44 records from a variety of sources (\001-delimited, individual strings, etc.) and converting TXT
45 records to various formats for use in apps; Added utility routines to validate DNS names, DNS
46 service types, and TXT records; Moved to portable address representation unions (byte-stream vs host
47 order integer) for consistency, to avoid swapping between host and network byte order, and for IPv6
48 support; Removed dependence on modified mDNSCore: define structures and prototypes locally; Added
49 support for automatically renaming services on name conflicts; Detect and correct TXT records from
50 old versions of mDNS that treated a TXT record as an arbitrary block of data, but prevent other
51 malformed TXT records from being accepted; Added many more error codes; Added complete HeaderDoc for
52 all constants, structures, typedefs, macros, and functions. Various other minor cleanup and fixes.
53
54 Revision 1.7 2003/08/12 19:56:29 cheshire
55 Update to APSL 2.0
56
57 Revision 1.6 2003/07/02 21:20:10 cheshire
58 <rdar://problem/3313413> Update copyright notices, etc., in source code comments
59
60 Revision 1.5 2003/03/22 02:57:45 cheshire
61 Updated mDNSWindows to use new "mDNS_Execute" model (see "mDNSCore/Implementer Notes.txt")
62
63 Revision 1.4 2003/02/20 00:59:05 cheshire
64 Brought Windows code up to date so it complies with
65 Josh Graessley's interface changes for IPv6 support.
66 (Actual support for IPv6 on Windows will come later.)
67
68 Revision 1.3 2002/09/21 20:44:57 zarzycki
69 Added APSL info
70
71 Revision 1.2 2002/09/20 05:58:02 bradley
72 DNS Services for Windows
73
74 */
75
76 //---------------------------------------------------------------------------------------------------------------------------
77 /*! @header DNSServices
78
79 @abstract DNS Services interfaces.
80
81 @discussion
82
83 DNS Services provides DNS service registration, domain and service discovery, and name resolving services.
84 */
85
86 #ifndef __DNS_SERVICES__
87 #define __DNS_SERVICES__
88
89 #include <stddef.h>
90
91 #ifdef __cplusplus
92 extern "C" {
93 #endif
94
95 #if 0
96 #pragma mark == General ==
97 #endif
98
99 //---------------------------------------------------------------------------------------------------------------------------
100 /*! @defined dns_check_compile_time
101
102 @abstract Performs a compile-time check of something such as the size of an int.
103
104 @discussion
105
106 This declares a unique array with a size that is determined by dividing 1 by the result of the compile-time expression
107 passed to the macro. If the expression evaluates to 0, this expression results in a divide by zero, which is illegal
108 and generates a compile-time error.
109
110 For example:
111
112 dns_check_compile_time( sizeof( int ) == 4 );
113
114 Note: This only works with compile-time expressions.
115 Note: This only works in places where extern declarations are allowed (e.g. global scope).
116
117 References:
118
119 <http://www.jaggersoft.com/pubs/CVu11_3.html>
120 <http://www.jaggersoft.com/pubs/CVu11_5.html>
121
122 Note: The following macros differ from the macros on the www.jaggersoft.com web site because those versions do not
123 work with GCC due to GCC allow a zero-length array. Using a divide-by-zero condition turned out to be more portable.
124 */
125
126 #define dns_check_compile_time( X ) extern int dns_unique_name[ 1 / (int)( ( X ) ) ]
127
128 #define dns_unique_name dns_make_name_wrapper( __LINE__ )
129 #define dns_make_name_wrapper( X ) dns_make_name( X )
130 #define dns_make_name( X ) dns_check_compile_time_ ## X
131
132 //---------------------------------------------------------------------------------------------------------------------------
133 /*! @defined dns_check_compile_time_code
134
135 @abstract Perform a compile-time check, suitable for placement in code, of something such as the size of an int.
136
137 @discussion
138
139 This creates a switch statement with an existing case for 0 and an additional case using the result of a
140 compile-time expression. A switch statement cannot have two case labels with the same constant so if the
141 compile-time expression evaluates to 0, it is illegal and generates a compile-time error. If the compile-time
142 expression does not evaluate to 0, the resulting value is used as the case label and it compiles without error.
143
144 For example:
145
146 dns_check_compile_time_code( sizeof( int ) == 4 );
147
148 Note: This only works with compile-time expressions.
149 Note: This does not work in a global scope so it must be inside a function.
150
151 References:
152
153 <http://www.jaggersoft.com/pubs/CVu11_3.html>
154 <http://www.jaggersoft.com/pubs/CVu11_5.html>
155 */
156
157 #define dns_check_compile_time_code( X ) switch( 0 ) { case 0: case X:; }
158
159 //---------------------------------------------------------------------------------------------------------------------------
160 /*! @defined DNS_LOCAL
161
162 @abstract Macro to make variables and functions static when debugging is off, but exported when debugging is on.
163
164 @discussion
165
166 Rather than using "static" directly, using this macros allows you to access these variables external while
167 debugging without being penalized for production builds.
168 */
169
170 #if( DEBUG )
171 #define DNS_LOCAL
172 #else
173 #define DNS_LOCAL static
174 #endif
175
176 //---------------------------------------------------------------------------------------------------------------------------
177 /*! @defined DNS_EXPORT
178
179 @abstract Macro to provide a visual clue that a variable or function is globally visible.
180 */
181
182 #define DNS_EXPORT
183
184 //---------------------------------------------------------------------------------------------------------------------------
185 /*! @defined DNS_DEBUG_USE_ONLY
186 @abstract Macro to mark a variable as unused when debugging is turned off.
187 @discussion
188
189 Variables are sometimes needed only for debugging. When debugging is turned off, these debug-only variables
190 generate compiler warnings about unused variables. To eliminate these warnings, use the DNS_DEBUG_USE_ONLY macro
191 to indicate the variables are for debugging only.
192 */
193
194 #if( DEBUG )
195 #define DNS_DEBUG_USE_ONLY( X )
196 #else
197 #define DNS_DEBUG_USE_ONLY( X ) (void)( X )
198 #endif
199
200 //---------------------------------------------------------------------------------------------------------------------------
201 /*! @defined DNS_UNUSED
202 @abstract Macro to mark a variable as unused.
203 @discussion
204
205 There is no universally supported pragma/attribute for indicating a variable is unused. DNS_UNUSED lets
206 indicate a variable is unused in a manner that is supported by most compilers.
207 */
208
209 #define DNS_UNUSED( X ) (void)( X )
210
211 //---------------------------------------------------------------------------------------------------------------------------
212 /*! @typedef DNSUInt8
213
214 @abstract 8-bit unsigned data type.
215 */
216
217 typedef unsigned char DNSUInt8;
218
219 dns_check_compile_time( sizeof( DNSUInt8 ) == 1 );
220
221 //---------------------------------------------------------------------------------------------------------------------------
222 /*! @typedef DNSUInt16
223
224 @abstract 16-bit unsigned data type.
225 */
226
227 typedef unsigned short DNSUInt16;
228
229 dns_check_compile_time( sizeof( DNSUInt16 ) == 2 );
230
231 //---------------------------------------------------------------------------------------------------------------------------
232 /*! @typedef DNSUInt32
233
234 @abstract 32-bit unsigned data type.
235 */
236
237 typedef unsigned long DNSUInt32;
238
239 dns_check_compile_time( sizeof( DNSUInt32 ) == 4 );
240
241 //---------------------------------------------------------------------------------------------------------------------------
242 /*! @typedef DNSSInt32
243
244 @abstract 32-bit signed data type.
245 */
246
247 typedef signed long DNSSInt32;
248
249 dns_check_compile_time( sizeof( DNSSInt32 ) == 4 );
250
251
252 //---------------------------------------------------------------------------------------------------------------------------
253 /*! @typedef DNSOpaque16
254
255 @abstract 16-bit opaque data type with 8-bit and 16-bit accessors.
256 */
257
258 typedef union DNSOpaque16 DNSOpaque16;
259 union DNSOpaque16
260 {
261 DNSUInt8 v8[ 2 ];
262 DNSUInt16 v16;
263 };
264
265 //---------------------------------------------------------------------------------------------------------------------------
266 /*! @typedef DNSOpaque32
267
268 @abstract 32-bit opaque data type with 8-bit, 16-bit, and 32-bit accessors.
269 */
270
271 typedef union DNSOpaque32 DNSOpaque32;
272 union DNSOpaque32
273 {
274 DNSUInt8 v8[ 4 ];
275 DNSUInt16 v16[ 2 ];
276 DNSUInt32 v32;
277 };
278
279 //---------------------------------------------------------------------------------------------------------------------------
280 /*! @typedef DNSOpaque128
281
282 @abstract 128-bit opaque data type with 8-bit, 16-bit, and 32-bit accessors.
283 */
284
285 typedef union DNSOpaque128 DNSOpaque128;
286 union DNSOpaque128
287 {
288 DNSUInt8 v8[ 16 ];
289 DNSUInt16 v16[ 8 ];
290 DNSUInt32 v32[ 4 ];
291 };
292
293 //---------------------------------------------------------------------------------------------------------------------------
294 /*! @typedef DNSCount
295
296 @abstract Count of at least 32-bits.
297 */
298
299 typedef DNSUInt32 DNSCount;
300
301 #if 0
302 #pragma mark == Errors ==
303 #endif
304
305 //---------------------------------------------------------------------------------------------------------------------------
306 /*! @enum DNSStatus
307
308 @abstract DNS Service status code.
309
310 @constant kDNSNoErr (0) Success. No error occurred.
311 @constant kDNSUnknownErr (-65537) An unknown error occurred.
312 @constant kDNSNoSuchNameErr (-65538) The name could not be found on the network.
313 @constant kDNSNoMemoryErr (-65539) Not enough memory was available.
314 @constant kDNSBadParamErr (-65540) A invalid or inappropriate parameter was specified.
315 @constant kDNSBadReferenceErr (-65541) A invalid or inappropriate reference was specified.
316 @constant kDNSBadStateErr (-65542) The current state does not allow the specified operation.
317 @constant kDNSBadFlagsErr (-65543) An invalid, inappropriate, or unsupported flag was specified.
318 @constant kDNSUnsupportedErr (-65544) The specified feature is not currently supported.
319 @constant kDNSNotInitializedErr (-65545) DNS Service has not been initialized.
320 @constant kDNSNoCacheErr (-65546) No cache was specified.
321 @constant kDNSAlreadyRegisteredErr (-65547) Service or host name is already registered.
322 @constant kDNSNameConflictErr (-65548) Name conflicts with another on the network.
323 @constant kDNSInvalidErr (-65549) A general error to indicate something is invalid.
324 @constant kDNSGrowCache (-65550) Cache needs to be grown (not used).
325 @constant kDNSIncompatibleErr (-65551) Version is incompatible.
326
327 @constant kDNSSizeErr (-65600) Size was too small or too big.
328 @constant kDNSMismatchErr (-65601) A data, version, etc. mismatch occurred.
329 @constant kDNSReadErr (-65602) Read failed.
330 @constant kDNSWriteErr (-65603) Write failed.
331 @constant kDNSCanceledErr (-65604) Operation was canceled.
332 @constant kDNSTimeoutErr (-65605) Operation timed out.
333 @constant kDNSConnectionErr (-65606) A disconnect or other connection error occurred.
334 @constant kDNSInUseErr (-65607) Object is in use (e.g. cannot reuse active param blocks).
335 @constant kDNSNoResourcesErr (-65608) Resources unavailable to perform the operation.
336 @constant kDNSEndingErr (-65609) Connection, session, or something is ending.
337
338 @constant kDNSConfigChanged (-65791) Configuration changed (not used).
339 @constant kDNSMemFree (-65792) Memory can be freed.
340 */
341
342 typedef DNSSInt32 DNSStatus;
343 enum
344 {
345 kDNSNoErr = 0,
346
347 // DNS Services error codes are in the range FFFE FF00 (-65792) to FFFE FFFF (-65537).
348
349 kDNSStartErr = -65537, // 0xFFFE FFFF
350
351 kDNSUnknownErr = -65537,
352 kDNSNoSuchNameErr = -65538,
353 kDNSNoMemoryErr = -65539,
354 kDNSBadParamErr = -65540,
355 kDNSBadReferenceErr = -65541,
356 kDNSBadStateErr = -65542,
357 kDNSBadFlagsErr = -65543,
358 kDNSUnsupportedErr = -65544,
359 kDNSNotInitializedErr = -65545,
360 kDNSNoCacheErr = -65546,
361 kDNSAlreadyRegisteredErr = -65547,
362 kDNSNameConflictErr = -65548,
363 kDNSInvalidErr = -65549,
364 kDNSGrowCache = -65550, // Reserved for mDNSCore
365 kDNSIncompatibleErr = -65551,
366
367 kDNSSizeErr = -65600,
368 kDNSMismatchErr = -65601,
369 kDNSReadErr = -65602,
370 kDNSWriteErr = -65603,
371 kDNSCanceledErr = -65604,
372 kDNSTimeoutErr = -65605,
373 kDNSConnectionErr = -65606,
374 kDNSInUseErr = -65607,
375 kDNSNoResourcesErr = -65608,
376 kDNSEndingErr = -65609,
377
378 kDNSConfigChanged = -65791, // Reserved for mDNSCore
379 kDNSMemFree = -65792, // Reserved for mDNSCore
380
381 kDNSEndErr = -65792 // 0xFFFE FF00
382 };
383
384 //---------------------------------------------------------------------------------------------------------------------------
385 /*! @enum DNSFlags
386
387 @abstract Flags used control DNS Services.
388
389 @constant kDNSFlagAdvertise
390 Indicates that interfaces should be advertised on the network. Software that only performs searches
391 do not need to set this flag.
392 */
393
394 typedef DNSUInt32 DNSFlags;
395 enum
396 {
397 kDNSFlagAdvertise = ( 1 << 0 )
398 };
399
400 //---------------------------------------------------------------------------------------------------------------------------
401 /*! @enum DNSPort
402
403 @abstract UDP/TCP port for DNS services.
404
405 @constant kDNSPortInvalid
406 Invalid port.
407
408 @constant kDNSPortUnicastDNS
409 TCP/UDP port for normal unicast DNS (see RFC 1035).
410
411 @constant kDNSPortMulticastDNS
412 TCP/UDP port for Multicast DNS (see <http://www.multicastdns.org/>).
413 */
414
415 typedef DNSUInt16 DNSPort;
416 enum
417 {
418 kDNSPortInvalid = 0,
419 kDNSPortUnicastDNS = 53,
420 kDNSPortMulticastDNS = 5353
421 };
422
423 //---------------------------------------------------------------------------------------------------------------------------
424 /*! @enum DNSNetworkAddressType
425
426 @abstract Type of address data within a DNSNetworkAddress.
427
428 @constant kDNSNetworkAddressTypeInvalid
429 Invalid type.
430
431 @constant kDNSNetworkAddressTypeIPv4
432 IPv4 address data.
433
434 @constant kDNSNetworkAddressTypeIPv6
435 IPv6 address data.
436 */
437
438 typedef DNSUInt32 DNSNetworkAddressType;
439
440 #define kDNSNetworkAddressTypeInvalid 0
441 #define kDNSNetworkAddressTypeIPv4 4
442 #define kDNSNetworkAddressTypeIPv6 6
443 #define kDNSNetworkAddressTypeAny 0xFFFFFFFF
444
445 //---------------------------------------------------------------------------------------------------------------------------
446 /*! @struct DNSNetworkAddressIPv4
447
448 @field addr
449 32-bit IPv4 address in network byte order.
450
451 @field port
452 16-bit port number in network byte order.
453 */
454
455 typedef struct DNSNetworkAddressIPv4 DNSNetworkAddressIPv4;
456 struct DNSNetworkAddressIPv4
457 {
458 DNSOpaque32 addr;
459 DNSOpaque16 port;
460 };
461
462 //---------------------------------------------------------------------------------------------------------------------------
463 /*! @struct DNSNetworkAddressIPv6
464
465 @field addr
466 128-bit IPv6 address in network byte order.
467
468 @field port
469 16-bit port number in network byte order.
470 */
471
472 typedef struct DNSNetworkAddressIPv6 DNSNetworkAddressIPv6;
473 struct DNSNetworkAddressIPv6
474 {
475 DNSOpaque128 addr;
476 DNSOpaque16 port;
477 };
478
479 //---------------------------------------------------------------------------------------------------------------------------
480 /*! @struct DNSNetworkAddress
481
482 @field addressType
483 Type of data contained within the address structure.
484
485 @field ipv4
486 IPv4 address data.
487
488 @field reserved
489 Reserved data (pads structure to allow for future growth). Unused portions must be zero.
490 */
491
492 typedef struct DNSNetworkAddress DNSNetworkAddress;
493 struct DNSNetworkAddress
494 {
495 DNSNetworkAddressType addressType;
496 union
497 {
498 DNSNetworkAddressIPv4 ipv4;
499 DNSNetworkAddressIPv6 ipv6;
500 } u;
501 };
502
503 //---------------------------------------------------------------------------------------------------------------------------
504 /*! @defined kDNSLocalDomain
505
506 @abstract Local DNS domain name (local.).
507 */
508
509 #define kDNSLocalDomain "local."
510
511 //---------------------------------------------------------------------------------------------------------------------------
512 /*! @function DNSServicesInitialize
513
514 @abstract Initializes DNS Services. This must be called before DNS Services functions can be used.
515
516 @param inFlags
517 Flags to control DNS Services.
518
519 @param inCacheEntryCount
520 Number of entries in the DNS record cache. Specify 0 to use the default.
521
522 @result Error code indicating failure reason or kDNSNoErr if successful.
523 */
524
525 DNSStatus DNSServicesInitialize( DNSFlags inFlags, DNSCount inCacheEntryCount );
526
527 //---------------------------------------------------------------------------------------------------------------------------
528 /*! @function DNSServicesFinalize
529
530 @abstract Finalizes DNS Services. No DNS Services functions may be called after this function is called.
531 */
532
533 void DNSServicesFinalize( void );
534
535 #if 0
536 #pragma mark == Resolving ==
537 #endif
538
539 //===========================================================================================================================
540 // Resolving
541 //===========================================================================================================================
542
543 //---------------------------------------------------------------------------------------------------------------------------
544 /*! @typedef DNSBrowserRef
545
546 @abstract Reference to a DNS browser object.
547
548 @discussion
549
550 A browser object is typically used by a graphical user application in a manner similar to the Macintosh "Chooser"
551 application. The application creates a browser object then starts domain and/or service searches to begin browsing.
552 When domains and/or services are found, added, or removed, the application is notified via a callback routine.
553 */
554
555 typedef struct DNSBrowser * DNSBrowserRef;
556
557 //---------------------------------------------------------------------------------------------------------------------------
558 /*! @typedef DNSResolverRef
559
560 @abstract Reference to a DNS resolver object.
561
562 @discussion
563
564 A resolver object is used to resolve service names to IP addresses.
565 */
566
567 typedef struct DNSResolver * DNSResolverRef;
568
569 //---------------------------------------------------------------------------------------------------------------------------
570 /*! @enum DNSResolverFlags
571
572 @abstract Flags used to control resolve operations.
573
574 @constant kDNSResolverFlagOneShot
575 Used to indicate the resolver object should be automatically released after the first resolve.
576
577 @constant kDNSResolverFlagOnlyIfUnique
578 Used to indicate the resolver object should only be created if it is unique. This makes it easy for
579 resolver management to be handled automatically. For example, some software needs to keep active
580 resolving operations open constantly to detect things like the IP address changing (e.g. if
581 displaying it to the user), but when a service goes away then comes back, a new resolver object
582 will often be created, leaving two resolvers for the same name.
583
584 @constant kDNSResolverFlagAutoReleaseByName
585 Used to indicate the resolver object should be automatically released when the service name
586 that is associated with it is no longer on the network. When a service is added to the network,
587 a resolver object may be created and kept around to detect things like IP address changes. When
588 the service goes off the network, this option causes the resolver associated with that service
589 name to be automatically released.
590 */
591
592 typedef DNSUInt32 DNSResolverFlags;
593 enum
594 {
595 kDNSResolverFlagOneShot = ( 1 << 0 ),
596 kDNSResolverFlagOnlyIfUnique = ( 1 << 1 ),
597 kDNSResolverFlagAutoReleaseByName = ( 1 << 2 )
598 };
599
600 //---------------------------------------------------------------------------------------------------------------------------
601 /*! @enum DNSResolverEventType
602
603 @abstract Type of resolver event being delivered.
604
605 @constant kDNSResolverEventTypeInvalid
606 Invalid event type. Here for completeness.
607
608 @constant kDNSResolverEventTypeRelease
609 Object is being released. No additional data is associated with this event.
610
611 @constant kDNSResolverEventTypeResolved
612 Name resolved.
613 */
614
615 typedef long DNSResolverEventType;
616 enum
617 {
618 kDNSResolverEventTypeInvalid = 0,
619 kDNSResolverEventTypeRelease = 1,
620 kDNSResolverEventTypeResolved = 10
621 };
622
623 //---------------------------------------------------------------------------------------------------------------------------
624 /*! @struct DNSResolverEventResolveData
625
626 @abstract Data structure passed to callback routine when a resolve-related event occurs.
627
628 @field name
629 Ptr to UTF-8 string containing the resolved name of the service.
630
631 @field type
632 Ptr to UTF-8 string containing the resolved type of the service.
633
634 @field domain
635 Ptr to UTF-8 string containing the resolved domain of the service.
636
637 @field interfaceID
638 Network interface that received the event.
639
640 @field interfaceName
641 Network interface that received the event. May be empty if interface is no longer available.
642
643 @field interfaceIP
644 IP of network interface that received the event. May be invalid if interface is no longer available.
645
646 @field address
647 Network address of the service. Used to communicate with the service.
648
649 @field textRecord
650 Ptr to UTF-8 string containing any additional text information supplied by the service provider.
651
652 @field flags
653 Flags used to augment the event data.
654
655 @field textRecordRaw
656 Ptr to raw TXT record data. May be needed if a custom TXT record format is used.
657
658 @field textRecordRawSize
659 Number of bytes in raw TXT record. May be needed if a custom TXT record format is used.
660
661 @field hostName
662 Host name of the resolved service.
663 */
664
665 typedef struct DNSResolverEventResolveData DNSResolverEventResolveData;
666 struct DNSResolverEventResolveData
667 {
668 const char * name;
669 const char * type;
670 const char * domain;
671 void * interfaceID;
672 const char * interfaceName;
673 DNSNetworkAddress interfaceIP;
674 DNSNetworkAddress address;
675 const char * textRecord;
676 DNSResolverFlags flags;
677 const void * textRecordRaw;
678 DNSCount textRecordRawSize;
679 const char * hostName;
680 };
681
682 //---------------------------------------------------------------------------------------------------------------------------
683 /*! @struct DNSResolverEvent
684
685 @abstract Data structure passed to callback routines when a resolver event occurs.
686
687 @field type
688 Type of event. The type determines which portion of the data union to use. Types and data union
689 fields are named such as the data union field is the same as the event type. For example, a
690 "resolved" event type (kDNSResolverEventTypeResolved) would refer to data union field "resolved".
691
692 @field resolved
693 Data associated with kDNSResolverEventTypeResolved event.
694 */
695
696 typedef struct DNSResolverEvent DNSResolverEvent;
697 struct DNSResolverEvent
698 {
699 DNSResolverEventType type;
700
701 union
702 {
703 DNSResolverEventResolveData resolved;
704
705 } data;
706 };
707
708 //---------------------------------------------------------------------------------------------------------------------------
709 /*! @function DNSResolverCallBack
710
711 @abstract CallBack routine used to indicate a resolver event.
712
713 @param inContext
714 User-supplied context for callback (specified when browser is created).
715
716 @param inRef
717 Reference to resolver object generating the event.
718
719 @param inStatusCode
720 Status of the event.
721
722 @param inEvent
723 Data associated with the event.
724 */
725
726 typedef void
727 ( *DNSResolverCallBack )(
728 void * inContext,
729 DNSResolverRef inRef,
730 DNSStatus inStatusCode,
731 const DNSResolverEvent * inEvent );
732
733 //---------------------------------------------------------------------------------------------------------------------------
734 /*! @function DNSResolverCreate
735
736 @abstract Creates a resolver object and start resolving a service name.
737
738 @param inFlags
739 Flags to control the resolving process.
740
741 @param inName
742 Ptr to UTF-8 string containing the service name to resolve (e.g. "My Printer").
743
744 @param inType
745 Ptr to UTF-8 string containing the service type of the service to resolve (e.g. "_printer._tcp").
746
747 @param inDomain
748 Ptr to UTF-8 string containing the domain of the service to resolve (e.g. "apple.com"). Use NULL
749 to indicate the local domain.
750
751 @param inCallBack
752 CallBack routine to call when a resolver event occurs.
753
754 @param inCallBackContext
755 Context pointer to pass to CallBack routine when an event occurs. Not inspected by DNS Services.
756
757 @param inOwner
758 Reference to browser object related to this resolver. If a browser object is specified and is
759 later released, this resolver object will automatically be released too. May be null.
760
761 @param outRef
762 Ptr to receive reference to resolver object. If the kDNSResolverFlagOnlyIfUnique flag is specified
763 and there is already a resolver for the name, a NULL reference is returned in this parameter to let
764 the caller know that no resolver was created. May be null.
765
766 @result Error code indicating failure reason or kDNSNoErr if successful.
767 */
768
769 DNSStatus
770 DNSResolverCreate(
771 DNSResolverFlags inFlags,
772 const char * inName,
773 const char * inType,
774 const char * inDomain,
775 DNSResolverCallBack inCallBack,
776 void * inCallBackContext,
777 DNSBrowserRef inOwner,
778 DNSResolverRef * outRef );
779
780 //---------------------------------------------------------------------------------------------------------------------------
781 /*! @function DNSResolverRelease
782
783 @abstract Releases a resolver object.
784
785 @param inRef
786 Reference to the resolver object to release.
787
788 @param inFlags
789 Flags to control the release process.
790
791 @result Error code indicating failure reason or kDNSNoErr if successful.
792 */
793
794 DNSStatus DNSResolverRelease( DNSResolverRef inRef, DNSResolverFlags inFlags );
795
796 #if 0
797 #pragma mark == Browsing ==
798 #endif
799
800 //===========================================================================================================================
801 // Browsing
802 //===========================================================================================================================
803
804 //---------------------------------------------------------------------------------------------------------------------------
805 /*! @enum DNSBrowserFlags
806
807 @abstract Flags used to control browser operations.
808
809 @constant kDNSBrowserFlagRegistrationDomainsOnly
810 Used to indicate the client is browsing only for domains to publish services. When the client wishes
811 to publish a service, a domain browse operation would be started, with this flag specified, to find
812 the domain used to register the service. Only valid when passed to DNSBrowserStartDomainSearch.
813
814 @constant kDNSBrowserFlagAutoResolve
815 Used to indicate discovered names should be automatically resolved. This eliminates the need to
816 manually create a resolver to get the IP address and other information. Only valid when passed to
817 DNSBrowserStartServiceSearch. When this option is used, it is important to avoid manually resolving
818 names because this option causes DNS Services to automatically resolve and multiple resolvers for
819 the same name will lead to unnecessary network bandwidth usage. It is also important to note that
820 the notification behavior of the browser is otherwise not affected by this option so browser callback
821 will still receive the same add/remove domain/service events it normally would.
822 */
823
824 typedef DNSUInt32 DNSBrowserFlags;
825 enum
826 {
827 kDNSBrowserFlagRegistrationDomainsOnly = ( 1 << 0 ),
828 kDNSBrowserFlagAutoResolve = ( 1 << 1 )
829 };
830
831 //---------------------------------------------------------------------------------------------------------------------------
832 /*! @enum DNSBrowserEventType
833
834 @abstract Type of browser event being delivered.
835
836 @constant kDNSBrowserEventTypeInvalid
837 Invalid event type. Here for completeness.
838
839 @constant kDNSBrowserEventTypeRelease
840 Object is being released. No additional data is associated with this event.
841
842 @constant kDNSBrowserEventTypeAddDomain
843 Domain added/found.
844
845 @constant kDNSBrowserEventTypeAddDefaultDomain
846 Default domain added/found. This domain should be selected as the default.
847
848 @constant kDNSBrowserEventTypeRemoveDomain
849 Domain removed.
850
851 @constant kDNSBrowserEventTypeAddService
852 Service added/found.
853
854 @constant kDNSBrowserEventTypeRemoveService
855 Service removed.
856
857 @constant kDNSBrowserEventTypeResolved
858 Name resolved. This is only delivered if the kDNSBrowserFlagAutoResolve option is used with
859 DNSBrowserStartServiceSearch.
860 */
861
862 typedef long DNSBrowserEventType;
863 enum
864 {
865 kDNSBrowserEventTypeInvalid = 0,
866 kDNSBrowserEventTypeRelease = 1,
867 kDNSBrowserEventTypeAddDomain = 10,
868 kDNSBrowserEventTypeAddDefaultDomain = 11,
869 kDNSBrowserEventTypeRemoveDomain = 12,
870 kDNSBrowserEventTypeAddService = 20,
871 kDNSBrowserEventTypeRemoveService = 21,
872 kDNSBrowserEventTypeResolved = 30
873 };
874
875 //---------------------------------------------------------------------------------------------------------------------------
876 /*! @struct DNSBrowserEventDomainData
877
878 @abstract Data structure referenced by callback routines when a domain-related event occurs.
879
880 @field interfaceID
881 Network interface that received the event.
882
883 @field interfaceName
884 Network interface that received the event. May be empty if interface is no longer available.
885
886 @field interfaceIP
887 IP of network interface that received the event. May be invalid if interface is no longer available.
888
889 @field domain
890 Ptr to UTF-8 string containing the domain name. NULL if no domain name is available or applicable.
891
892 @field flags
893 Flags used to augment the event data.
894 */
895
896 typedef struct DNSBrowserEventDomainData DNSBrowserEventDomainData;
897 struct DNSBrowserEventDomainData
898 {
899 void * interfaceID;
900 const char * interfaceName;
901 DNSNetworkAddress interfaceIP;
902 const char * domain;
903 DNSBrowserFlags flags;
904 };
905
906 //---------------------------------------------------------------------------------------------------------------------------
907 /*! @struct DNSBrowserEventServiceData
908
909 @abstract Data structure passed to callback routines when a service-related event occurs.
910
911 @field interfaceID
912 Network interface that received the event.
913
914 @field interfaceName
915 Network interface that received the event. May be empty if interface is no longer available.
916
917 @field interfaceIP
918 IP of network interface that received the event. May be invalid if interface is no longer available.
919
920 @field name
921 Ptr to UTF-8 string containing the service name. NULL if no service name is available or applicable.
922
923 @field type
924 Ptr to UTF-8 string containing the service type. NULL if no service type is available or applicable.
925
926 @field domain
927 Ptr to UTF-8 string containing the domain name. NULL if no domain name is available or applicable.
928
929 @field flags
930 Flags used to augment the event data.
931 */
932
933 typedef struct DNSBrowserEventServiceData DNSBrowserEventServiceData;
934 struct DNSBrowserEventServiceData
935 {
936 void * interfaceID;
937 const char * interfaceName;
938 DNSNetworkAddress interfaceIP;
939 const char * name;
940 const char * type;
941 const char * domain;
942 DNSBrowserFlags flags;
943 };
944
945 //---------------------------------------------------------------------------------------------------------------------------
946 /*! @struct DNSBrowserEvent
947
948 @abstract Data structure passed to callback routines when a browser event occurs.
949
950 @field type
951 Type of event. The type determines which portion of the data union to use. Types and data union
952 fields are named such as the data union field is the same as the event type. For example, an
953 "add domain" event type (kDNSBrowserEventTypeAddDomain) would refer to data union field "addDomain".
954
955 @field addDomain
956 Data associated with kDNSBrowserEventTypeAddDomain event.
957
958 @field addDefaultDomain
959 Data associated with kDNSBrowserEventTypeAddDefaultDomain event.
960
961 @field removeDomain
962 Data associated with kDNSBrowserEventTypeRemoveDomain event.
963
964 @field addService
965 Data associated with kDNSBrowserEventTypeAddService event.
966
967 @field removeService
968 Data associated with kDNSBrowserEventTypeRemoveService event.
969
970 @field resolved
971 Data associated with kDNSBrowserEventTypeResolved event.
972 */
973
974 typedef struct DNSBrowserEvent DNSBrowserEvent;
975 struct DNSBrowserEvent
976 {
977 DNSBrowserEventType type;
978
979 union
980 {
981 DNSBrowserEventDomainData addDomain;
982 DNSBrowserEventDomainData addDefaultDomain;
983 DNSBrowserEventDomainData removeDomain;
984 DNSBrowserEventServiceData addService;
985 DNSBrowserEventServiceData removeService;
986 const DNSResolverEventResolveData * resolved;
987
988 } data;
989 };
990
991 //---------------------------------------------------------------------------------------------------------------------------
992 /*! @function DNSBrowserCallBack
993
994 @abstract CallBack routine used to indicate a browser event.
995
996 @param inContext
997 User-supplied context for callback (specified when browser is created).
998
999 @param inRef
1000 Reference to browser object generating the event.
1001
1002 @param inStatusCode
1003 Status of the event.
1004
1005 @param inEvent
1006 Data associated with the event.
1007 */
1008
1009 typedef void
1010 ( *DNSBrowserCallBack )(
1011 void * inContext,
1012 DNSBrowserRef inRef,
1013 DNSStatus inStatusCode,
1014 const DNSBrowserEvent * inEvent );
1015
1016 //---------------------------------------------------------------------------------------------------------------------------
1017 /*! @function DNSBrowserCreate
1018
1019 @abstract Creates a browser object.
1020
1021 @param inFlags
1022 Flags to control the creation process.
1023
1024 @param inCallBack
1025 CallBack routine to call when a browser event occurs.
1026
1027 @param inCallBackContext
1028 Context pointer to pass to CallBack routine when an event occurs. Not inspected by DNS Services.
1029
1030 @param outRef
1031 Ptr to receive reference to the created browser object. May be null.
1032
1033 @result Error code indicating failure reason or kDNSNoErr if successful.
1034 */
1035
1036 DNSStatus
1037 DNSBrowserCreate(
1038 DNSBrowserFlags inFlags,
1039 DNSBrowserCallBack inCallBack,
1040 void * inCallBackContext,
1041 DNSBrowserRef * outRef );
1042
1043 //---------------------------------------------------------------------------------------------------------------------------
1044 /*! @function DNSBrowserRelease
1045
1046 @abstract Releases a browser object.
1047
1048 @param inRef
1049 Reference to the browser object to release.
1050
1051 @param inFlags
1052 Flags to control the release process.
1053
1054 @result Error code indicating failure reason or kDNSNoErr if successful.
1055 */
1056
1057 DNSStatus DNSBrowserRelease( DNSBrowserRef inRef, DNSBrowserFlags inFlags );
1058
1059 //---------------------------------------------------------------------------------------------------------------------------
1060 /*! @function DNSBrowserStartDomainSearch
1061
1062 @abstract Starts a domain name search.
1063
1064 @param inRef
1065 Reference to browser object to start the search on.
1066
1067 @param inFlags
1068 Flags to control the search process.
1069
1070 @result Error code indicating failure reason or kDNSNoErr if successful.
1071 */
1072
1073 DNSStatus DNSBrowserStartDomainSearch( DNSBrowserRef inRef, DNSBrowserFlags inFlags );
1074
1075 //---------------------------------------------------------------------------------------------------------------------------
1076 /*! @function DNSBrowserStopDomainSearch
1077
1078 @abstract Stops a domain name search.
1079
1080 @param inRef
1081 Reference to browser object to stop the search on.
1082
1083 @param inFlags
1084 Flags to control the stopping process.
1085
1086 @result Error code indicating failure reason or kDNSNoErr if successful.
1087 */
1088
1089 DNSStatus DNSBrowserStopDomainSearch( DNSBrowserRef inRef, DNSBrowserFlags inFlags );
1090
1091 //---------------------------------------------------------------------------------------------------------------------------
1092 /*! @function DNSBrowserStartServiceSearch
1093
1094 @abstract Starts a service search.
1095
1096 @param inRef
1097 Reference to browser object to start the search on.
1098
1099 @param inFlags
1100 Flags to control the search process.
1101
1102 @param inType
1103 Ptr to UTF-8 string containing the service type to search for (e.g. "_printer._tcp").
1104
1105 @param inDomain
1106 Ptr to UTF-8 string containing the domain to search in (e.g. "apple.com"). Use NULL to indicate
1107 the local domain.
1108
1109 @result Error code indicating failure reason or kDNSNoErr if successful.
1110 */
1111
1112 DNSStatus
1113 DNSBrowserStartServiceSearch(
1114 DNSBrowserRef inRef,
1115 DNSBrowserFlags inFlags,
1116 const char * inType,
1117 const char * inDomain );
1118
1119 //---------------------------------------------------------------------------------------------------------------------------
1120 /*! @function DNSBrowserStopServiceSearch
1121
1122 @abstract Stops a service search.
1123
1124 @param inRef
1125 Reference to browser object to stop the search on.
1126
1127 @param inFlags
1128 Flags to control the stopping process.
1129
1130 @result Error code indicating failure reason or kDNSNoErr if successful.
1131 */
1132
1133 DNSStatus DNSBrowserStopServiceSearch( DNSBrowserRef inRef, DNSBrowserFlags inFlags );
1134
1135 #if 0
1136 #pragma mark == Registration ==
1137 #endif
1138
1139 //===========================================================================================================================
1140 // Registration
1141 //===========================================================================================================================
1142
1143 //---------------------------------------------------------------------------------------------------------------------------
1144 /*! @typedef DNSRegistrationRef
1145
1146 @abstract Reference to a DNS registration object.
1147 */
1148
1149 typedef struct DNSRegistration * DNSRegistrationRef;
1150
1151 //---------------------------------------------------------------------------------------------------------------------------
1152 /*! @typedef DNSRegistrationRecordRef
1153
1154 @abstract Reference to a DNS record object.
1155 */
1156
1157 typedef struct DNSRegistrationRecord * DNSRegistrationRecordRef;
1158
1159 //---------------------------------------------------------------------------------------------------------------------------
1160 /*! @enum DNSRegistrationFlags
1161
1162 @abstract Flags used to control registration operations.
1163
1164 @constant kDNSRegistrationFlagPreFormattedTextRecord
1165 Text record is pre-formatted and should be used directly without interpretation.
1166
1167 @constant kDNSRegistrationFlagAutoRenameOnConflict
1168 Automatically uniquely rename and re-register the service when a name conflict occurs.
1169 */
1170
1171 typedef DNSUInt32 DNSRegistrationFlags;
1172 enum
1173 {
1174 kDNSRegistrationFlagPreFormattedTextRecord = ( 1 << 0 ),
1175 kDNSRegistrationFlagAutoRenameOnConflict = ( 1 << 1 )
1176 };
1177
1178 //---------------------------------------------------------------------------------------------------------------------------
1179 /*! @enum DNSRecordFlags
1180
1181 @abstract Flags used to control record operations.
1182 */
1183
1184 typedef DNSUInt32 DNSRecordFlags;
1185
1186 //---------------------------------------------------------------------------------------------------------------------------
1187 /*! @enum DNSRegistrationEventType
1188
1189 @abstract Type of registration event being delivered.
1190
1191 @constant kDNSResolverEventTypeInvalid
1192 Invalid event type. Here for completeness.
1193
1194 @constant kDNSRegistrationEventTypeRelease
1195 Object is being released. No additional data is associated with this event.
1196
1197 @constant kDNSRegistrationEventTypeRegistered
1198 Name has been successfully registered.
1199
1200 @constant kDNSRegistrationEventTypeNameCollision
1201 Name collision. The registration is no longer valid. A new registration must be created if needed.
1202 */
1203
1204 typedef long DNSRegistrationEventType;
1205 enum
1206 {
1207 kDNSRegistrationEventTypeInvalid = 0,
1208 kDNSRegistrationEventTypeRelease = 1,
1209 kDNSRegistrationEventTypeRegistered = 10,
1210 kDNSRegistrationEventTypeNameCollision = 11
1211 };
1212
1213 //---------------------------------------------------------------------------------------------------------------------------
1214 /*! @struct DNSRegistrationEvent
1215
1216 @abstract Data structure passed to callback routines when a registration event occurs.
1217
1218 @field type
1219 Type of event. The type determines which portion of the data union to use. Types and data union
1220 fields are named such as the data union field is the same as the event type.
1221
1222 @field reserved
1223 Reserved for future use.
1224 */
1225
1226 typedef struct DNSRegistrationEvent DNSRegistrationEvent;
1227 struct DNSRegistrationEvent
1228 {
1229 DNSRegistrationEventType type;
1230
1231 union
1232 {
1233 DNSUInt32 reserved;
1234
1235 } data;
1236 };
1237
1238 //---------------------------------------------------------------------------------------------------------------------------
1239 /*! @function DNSRegistrationCallBack
1240
1241 @abstract CallBack routine used to indicate a registration event.
1242
1243 @param inContext
1244 User-supplied context for callback (specified when registration is created).
1245
1246 @param inRef
1247 Reference to registration object generating the event.
1248
1249 @param inStatusCode
1250 Status of the event.
1251
1252 @param inEvent
1253 Data associated with the event.
1254 */
1255
1256 typedef void
1257 ( *DNSRegistrationCallBack )(
1258 void * inContext,
1259 DNSRegistrationRef inRef,
1260 DNSStatus inStatusCode,
1261 const DNSRegistrationEvent * inEvent );
1262
1263 //---------------------------------------------------------------------------------------------------------------------------
1264 /*! @function DNSRegistrationCreate
1265
1266 @abstract Creates a registration object and publish the registration.
1267
1268 @param inFlags
1269 Flags to control the registration process.
1270
1271 @param inName
1272 Ptr to UTF-8 string containing the service name to register (e.g. "My Printer").
1273
1274 @param inType
1275 Ptr to UTF-8 string containing the service type of the service to registration (e.g. "_printer._tcp").
1276
1277 @param inDomain
1278 Ptr to UTF-8 string containing the domain of the service to register (e.g. "apple.com"). Use NULL
1279 to indicate the local domain.
1280
1281 @param inPort
1282 TCP/UDP port where the service is being offered (e.g. 80 for an HTTP service).
1283
1284 @param inTextRecord
1285 Ptr to UTF-8 string containing any additional text to provide when the service is resolved.
1286
1287 @param inTextRecordSize
1288 Size to text record.
1289
1290 @param inHost
1291 Name of the host to associate with the registration. Use NULL to use the default host name.
1292
1293 @field inInterfaceName
1294 Name of an interface to restrict service registration to. Use NULL to register service on all interfaces.
1295
1296 @param inCallBack
1297 CallBack routine to call when a registration event occurs.
1298
1299 @param inCallBackContext
1300 Context pointer to pass to CallBack routine when an event occurs. Not inspected by DNS Services.
1301
1302 @param outRef
1303 Ptr to receive reference to registration object. May be null.
1304
1305 @result Error code indicating failure reason or kDNSNoErr if successful.
1306 */
1307
1308 DNSStatus
1309 DNSRegistrationCreate(
1310 DNSRegistrationFlags inFlags,
1311 const char * inName,
1312 const char * inType,
1313 const char * inDomain,
1314 DNSPort inPort,
1315 const void * inTextRecord,
1316 DNSCount inTextRecordSize,
1317 const char * inHost,
1318 const char * inInterfaceName,
1319 DNSRegistrationCallBack inCallBack,
1320 void * inCallBackContext,
1321 DNSRegistrationRef * outRef );
1322
1323 //---------------------------------------------------------------------------------------------------------------------------
1324 /*! @function DNSNoSuchServiceRegistrationCreate
1325
1326 @abstract Creates a registration object and publish the registration to assert non-existence of a particular service.
1327
1328 @param inFlags
1329 Flags to control the registration process.
1330
1331 @param inName
1332 Ptr to UTF-8 string containing the service name to register (e.g. "My Printer").
1333
1334 @param inType
1335 Ptr to UTF-8 string containing the service type of the service to registration (e.g. "_printer._tcp").
1336
1337 @param inDomain
1338 Ptr to UTF-8 string containing the domain of the service to register (e.g. "apple.com"). Use NULL
1339 to indicate the local domain.
1340
1341 @field inInterfaceName
1342 Name of an interface to restrict service registration to. Use NULL to register service on all interfaces.
1343
1344 @param inCallBack
1345 CallBack routine to call when a registration event occurs.
1346
1347 @param inCallBackContext
1348 Context pointer to pass to CallBack routine when an event occurs. Not inspected by DNS Services.
1349
1350 @param outRef
1351 Ptr to receive reference to registration object. May be null.
1352
1353 @result Error code indicating failure reason or kDNSNoErr if successful.
1354 */
1355
1356 DNSStatus
1357 DNSNoSuchServiceRegistrationCreate(
1358 DNSRegistrationFlags inFlags,
1359 const char * inName,
1360 const char * inType,
1361 const char * inDomain,
1362 const char * inInterfaceName,
1363 DNSRegistrationCallBack inCallBack,
1364 void * inCallBackContext,
1365 DNSRegistrationRef * outRef );
1366
1367 //---------------------------------------------------------------------------------------------------------------------------
1368 /*! @function DNSRegistrationRelease
1369
1370 @abstract Releases a registration object.
1371
1372 @param inRef
1373 Reference to the registration object to release.
1374
1375 @param inFlags
1376 Flags to control the release process.
1377
1378 @result Error code indicating failure reason or kDNSNoErr if successful.
1379 */
1380
1381 DNSStatus DNSRegistrationRelease( DNSRegistrationRef inRef, DNSRegistrationFlags inFlags );
1382
1383 //---------------------------------------------------------------------------------------------------------------------------
1384 /*! @function DNSRegistrationUpdate
1385
1386 @abstract Updates an individual record for a registration.
1387
1388 @param inRef
1389 Reference to the registration object to update.
1390
1391 @param inRecord
1392 Record to update. Use NULL for the standard TXT record.
1393
1394 @param inData
1395 New record data.
1396
1397 @param inSize
1398 Size of new record data.
1399
1400 @param inNewTTL
1401 New time-to-live (TTL) in seconds for the updated data (e.g. 120 for 2 minutes).
1402
1403 @result Error code indicating failure reason or kDNSNoErr if successful.
1404 */
1405
1406 DNSStatus
1407 DNSRegistrationUpdate(
1408 DNSRegistrationRef inRef,
1409 DNSRecordFlags inFlags,
1410 DNSRegistrationRecordRef inRecord,
1411 const void * inData,
1412 DNSCount inSize,
1413 DNSUInt32 inNewTTL );
1414
1415 #if 0
1416 #pragma mark == Domain Registration ==
1417 #endif
1418
1419 //===========================================================================================================================
1420 // Domain Registration
1421 //===========================================================================================================================
1422
1423 //---------------------------------------------------------------------------------------------------------------------------
1424 /*! @typedef DNSDomainRegistrationRef
1425
1426 @abstract Reference to a DNS registration object.
1427 */
1428
1429 typedef struct DNSDomainRegistration * DNSDomainRegistrationRef;
1430
1431 //---------------------------------------------------------------------------------------------------------------------------
1432 /*! @enum DNSDomainRegistrationFlags
1433
1434 @abstract Flags used to control registration operations.
1435 */
1436
1437 typedef DNSUInt32 DNSDomainRegistrationFlags;
1438 enum
1439 {
1440 kDNSDomainRegistrationFlagNone = 0
1441 };
1442
1443 //---------------------------------------------------------------------------------------------------------------------------
1444 /*! @enum DNSDomainRegistrationType
1445
1446 @abstract Type of domain registration.
1447
1448 @constant kDNSDomainRegistrationTypeBrowse
1449 Registration for domain browsing.
1450
1451 @constant kDNSDomainRegistrationTypeBrowseDefault
1452 Registration for the domain browsing domain.
1453
1454 @constant kDNSDomainRegistrationTypeRegistration
1455 Registration for domain registration.
1456
1457 @constant kDNSDomainRegistrationTypeRegistrationDefault
1458 Registration for the domain registration domain.
1459 */
1460
1461 typedef DNSUInt32 DNSDomainRegistrationType;
1462 enum
1463 {
1464 kDNSDomainRegistrationTypeBrowse = 0,
1465 kDNSDomainRegistrationTypeBrowseDefault = 1,
1466 kDNSDomainRegistrationTypeRegistration = 2,
1467 kDNSDomainRegistrationTypeRegistrationDefault = 3,
1468
1469 kDNSDomainRegistrationTypeMax = 4
1470 };
1471
1472 //---------------------------------------------------------------------------------------------------------------------------
1473 /*! @function DNSDomainRegistrationCreate
1474
1475 @abstract Creates a domain registration object and publish the domain.
1476
1477 @param inFlags
1478 Flags to control the registration process.
1479
1480 @param inName
1481 Ptr to string containing the domain name to register (e.g. "apple.com").
1482
1483 @param inType
1484 Type of domain registration.
1485
1486 @param outRef
1487 Ptr to receive reference to domain registration object. May be null.
1488
1489 @result Error code indicating failure reason or kDNSNoErr if successful.
1490 */
1491
1492 DNSStatus
1493 DNSDomainRegistrationCreate(
1494 DNSDomainRegistrationFlags inFlags,
1495 const char * inName,
1496 DNSDomainRegistrationType inType,
1497 DNSDomainRegistrationRef * outRef );
1498
1499 //---------------------------------------------------------------------------------------------------------------------------
1500 /*! @function DNSDomainRegistrationRelease
1501
1502 @abstract Releases a domain registration object.
1503
1504 @param inRef
1505 Reference to the domain registration object to release.
1506
1507 @param inFlags
1508 Flags to control the release process.
1509
1510 @result Error code indicating failure reason or kDNSNoErr if successful.
1511 */
1512
1513 DNSStatus DNSDomainRegistrationRelease( DNSDomainRegistrationRef inRef, DNSDomainRegistrationFlags inFlags );
1514
1515 #if 0
1516 #pragma mark == Host Registration ==
1517 #endif
1518
1519 //===========================================================================================================================
1520 // Host Registration
1521 //===========================================================================================================================
1522
1523 //---------------------------------------------------------------------------------------------------------------------------
1524 /*! @typedef DNSHostRegistrationRef
1525
1526 @abstract Reference to a DNS host registration object.
1527 */
1528
1529 typedef struct DNSHostRegistration * DNSHostRegistrationRef;
1530
1531 //---------------------------------------------------------------------------------------------------------------------------
1532 /*! @enum DNSHostRegistrationFlags
1533
1534 @abstract Flags used to control registration operations.
1535
1536 @constant kDNSHostRegistrationFlagOnlyIfNotFound
1537 Only creates the object and registers the host if it was not already found in the list.
1538
1539 @constant kDNSHostRegistrationFlagAutoRenameOnConflict
1540 Automatically uniquely rename and re-register the host when a name conflict occurs.
1541
1542 */
1543
1544 typedef DNSUInt32 DNSHostRegistrationFlags;
1545 enum
1546 {
1547 kDNSHostRegistrationFlagNone = 0,
1548 kDNSHostRegistrationFlagOnlyIfNotFound = ( 1 << 0 ),
1549 kDNSHostRegistrationFlagAutoRenameOnConflict = ( 1 << 1 )
1550 };
1551
1552 //---------------------------------------------------------------------------------------------------------------------------
1553 /*! @function DNSHostRegistrationCallBack
1554
1555 @abstract CallBack routine used to indicate a host registration event.
1556
1557 @param inContext
1558 User-supplied context for callback (specified when browser is created).
1559
1560 @param inRef
1561 Reference to resolver object generating the event.
1562
1563 @param inStatusCode
1564 Status of the event.
1565
1566 @param inData
1567 Data associated with the event.
1568 */
1569
1570 typedef void
1571 ( *DNSHostRegistrationCallBack )(
1572 void * inContext,
1573 DNSHostRegistrationRef inRef,
1574 DNSStatus inStatusCode,
1575 void * inData );
1576
1577 //---------------------------------------------------------------------------------------------------------------------------
1578 /*! @function DNSHostRegistrationCreate
1579
1580 @abstract Creates a host registration object and publishes the host.
1581
1582 @param inFlags
1583 Flags to control the registration process.
1584
1585 @param inName
1586 Name of the host to register (e.g. "My Web Server").
1587
1588 @param inDomain
1589 Domain of the host to register (e.g. "apple.com"). Use NULL to indicate the local domain.
1590
1591 @param inAddr
1592 IP address of host to register.
1593
1594 @field inInterfaceName
1595 Name of an interface to restrict registration to. Use NULL to register on all interfaces.
1596
1597 @param inCallBack
1598 CallBack routine to call when an event occurs.
1599
1600 @param inCallBackContext
1601 Context pointer to pass to callback routine when an event occurs. Not inspected by DNS Services.
1602
1603 @param outRef
1604 Ptr to receive reference to host registration object. May be null.
1605
1606 @result Error code indicating failure reason or kDNSNoErr if successful.
1607 */
1608
1609 DNSStatus
1610 DNSHostRegistrationCreate(
1611 DNSHostRegistrationFlags inFlags,
1612 const char * inName,
1613 const char * inDomain,
1614 const DNSNetworkAddress * inAddr,
1615 const char * inInterfaceName,
1616 DNSHostRegistrationCallBack inCallBack,
1617 void * inCallBackContext,
1618 DNSHostRegistrationRef * outRef );
1619
1620 //---------------------------------------------------------------------------------------------------------------------------
1621 /*! @function DNSHostRegistrationRelease
1622
1623 @abstract Releases a host registration object.
1624
1625 @param inRef
1626 Reference to the host registration object to release.
1627
1628 @param inFlags
1629 Flags to control the release process.
1630
1631 @result Error code indicating failure reason or kDNSNoErr if successful.
1632 */
1633
1634 DNSStatus DNSHostRegistrationRelease( DNSHostRegistrationRef inRef, DNSHostRegistrationFlags inFlags );
1635
1636 #if 0
1637 #pragma mark == Utilities ==
1638 #endif
1639
1640 //---------------------------------------------------------------------------------------------------------------------------
1641 /*! @defined kDNSTextRecordNoValue
1642
1643 @abstract Value to use when no value is desired for a name/value pair (e.g. "color" instead of "color=").
1644 */
1645
1646 #define kDNSTextRecordNoValue ( (const void *) -1 )
1647
1648 //---------------------------------------------------------------------------------------------------------------------------
1649 /*! @defined kDNSTextRecordStringNoValue
1650
1651 @abstract Value to use when no value is desired for a name/value pair (e.g. "color" instead of "color=").
1652 */
1653
1654 #define kDNSTextRecordStringNoValue ( (const char *) -1 )
1655
1656 //---------------------------------------------------------------------------------------------------------------------------
1657 /*! @defined kDNSTextRecordNoValue
1658
1659 @abstract Size value to use when no value is desired for a name/value pair (e.g. "color" instead of "color=").
1660 */
1661
1662 #define kDNSTextRecordNoSize ( (size_t) -1 )
1663
1664 //---------------------------------------------------------------------------------------------------------------------------
1665 /*! @function DNSDynamicTextRecordBuildEscaped
1666
1667 @abstract Builds a TXT record from a string with \001 escape sequences to separate strings within the TXT record.
1668
1669 @param inFormat C-string TXT record with \001 escape sequences as record separators.
1670 @param outTextRecord Receives a ptr to a built TXT record. Must free with DNSDynamicTextRecordRelease.
1671 @param outSize Receive actual size of the built TXT record. Use NULL if you don't need the size.
1672
1673 @result Error code indicating failure reason or kDNSNoErr if successful.
1674
1675 @discussion
1676
1677 A DNS TXT record consists of a packed array of length-prefixed strings with each string being up to 255 characters.
1678 To allow this to be described with a null-terminated C-string, a special escape sequence of \001 is used to separate
1679 individual character strings within the C-string.
1680
1681 For example, to represent the following 3 segments "test1=1", "test2=2", and "test3=3", you would use the following:
1682
1683 DNSUInt8 * txt;
1684 size_t size;
1685
1686 txt = NULL;
1687
1688 err = DNSDynamicTextRecordBuildEscaped( "test1=1\001test2=2\001test3=3", &txt, &size );
1689 require_noerr( err, exit );
1690
1691 ... use text record
1692
1693 exit:
1694 DNSDynamicTextRecordRelease( txt );
1695 */
1696
1697 DNSStatus DNSDynamicTextRecordBuildEscaped( const char *inFormat, void *outTextRecord, size_t *outSize );
1698
1699 //---------------------------------------------------------------------------------------------------------------------------
1700 /*! @function DNSDynamicTextRecordAppendCString
1701
1702 @abstract Appends a name/value pair with the value being a C-string to a dynamic DNS TXT record data section.
1703
1704 @param ioTxt Input: Ptr to a ptr to TXT record to append to.
1705 Output: Receives newly allocated ptr to the new TXT record.
1706 Note: Use a ptr to NULL the first time this is called.
1707
1708 @param ioTxtSize Input: Ptr to size of existing TXT record.
1709 Output: Receives new size of TXT record.
1710
1711 @param inName C-string name in the name/value pair (e.g. "path" for HTTP).
1712
1713 @param inValue C-string value in the name/value pair (e.g. "/index.html for HTTP).
1714
1715 @result Error code indicating failure reason or kDNSNoErr if successful.
1716
1717 @discussion
1718
1719 This can be used to easily build dynamically-resized TXT records containing multiple name/value pairs of C-strings.
1720 For example, the following adds "name=Ryknow", "age=30", and "job=Musician":
1721
1722 DNSUInt8 * txt;
1723 size_t size;
1724
1725 txt = NULL;
1726 size = 0;
1727
1728 err = DNSDynamicTextRecordAppendCString( &txt, &size, "name", "Ryknow" );
1729 require_noerr( err, exit );
1730
1731 err = DNSDynamicTextRecordAppendCString( &txt, &size, "age", "30" );
1732 require_noerr( err, exit );
1733
1734 err = DNSDynamicTextRecordAppendCString( &txt, &size, "job", "Musician" );
1735 require_noerr( err, exit );
1736
1737 ... use text record
1738
1739 exit:
1740 DNSDynamicTextRecordRelease( txt );
1741 */
1742
1743 DNSStatus DNSDynamicTextRecordAppendCString( void *ioTxt, size_t *ioTxtSize, const char *inName, const char *inValue );
1744
1745 //---------------------------------------------------------------------------------------------------------------------------
1746 /*! @function DNSDynamicTextRecordAppendData
1747
1748 @abstract Appends a name/value pair to a dynamic DNS TXT record data section.
1749
1750 @param ioTxt Input: Ptr to a ptr to TXT record to append to.
1751 Output: Receives newly allocated ptr to the new TXT record.
1752 Note: Use a ptr to NULL the first time this is called.
1753
1754 @param ioTxtSize Input: Ptr to size of existing TXT record.
1755 Output: Receives new size of TXT record.
1756
1757 @param inName C-string name in the name/value pair (e.g. "path" for HTTP).
1758
1759 @param inValue Value data to associate with the name. Use kDNSTextRecordNoValue for no value.
1760
1761 @param inValueSize Size of value data. Use kDNSTextRecordNoSize for no value.
1762
1763 @result Error code indicating failure reason or kDNSNoErr if successful.
1764 */
1765
1766 DNSStatus
1767 DNSDynamicTextRecordAppendData(
1768 void * ioTxt,
1769 size_t * ioTxtSize,
1770 const char * inName,
1771 const void * inValue,
1772 size_t inValueSize );
1773
1774 //---------------------------------------------------------------------------------------------------------------------------
1775 /*! @function DNSDynamicTextRecordRelease
1776
1777 @abstract Releases a dynamically allocated TXT record.
1778
1779 @param inTxt Dynamic TXT record to release.
1780
1781 @discussion
1782
1783 This API may only be used with TXT records generated with DNSDynamicTextRecordAppendCString and
1784 DNSDynamicTextRecordAppendData.
1785 */
1786
1787 void DNSDynamicTextRecordRelease( void *inTxt );
1788
1789 //---------------------------------------------------------------------------------------------------------------------------
1790 /*! @function DNSTextRecordAppendCString
1791
1792 @abstract Appends a name/value pair with the value being a C-string to DNS TXT record data section.
1793
1794 @param inTxt TXT record to append to.
1795 @param inTxtSize Size of existing TXT record.
1796 @param inTxtMaxSize Maximum size of TXT record (i.e. size of buffer).
1797 @param inName C-string name in the name/value pair (e.g. "path" for HTTP).
1798 @param inValue C-string value in the name/value pair (e.g. "/index.html for HTTP).
1799 @param outTxtSize Receives resulting size of TXT record. Pass NULL if not needed.
1800
1801 @result Error code indicating failure reason or kDNSNoErr if successful.
1802
1803 @discussion
1804
1805 This can be used to easily build TXT records containing multiple name/value pairs of C-strings. For example, the
1806 following adds "name=Ryknow", "age=30", and "job=Musician":
1807
1808 DNSUInt8 txt[ 256 ];
1809 size_t size;
1810
1811 size = 0;
1812
1813 err = DNSTextRecordAppendCString( txt, size, sizeof( txt ), "name", "Ryknow", &size );
1814 require_noerr( err, exit );
1815
1816 err = DNSTextRecordAppendCString( txt, size, sizeof( txt ), "age", "30", &size );
1817 require_noerr( err, exit );
1818
1819 err = DNSTextRecordAppendCString( txt, size, sizeof( txt ), "job", "Musician", &size );
1820 require_noerr( err, exit );
1821 */
1822
1823 DNSStatus
1824 DNSTextRecordAppendCString(
1825 void * inTxt,
1826 size_t inTxtSize,
1827 size_t inTxtMaxSize,
1828 const char * inName,
1829 const char * inValue,
1830 size_t * outTxtSize );
1831
1832 //---------------------------------------------------------------------------------------------------------------------------
1833 /*! @function DNSTextRecordAppendData
1834
1835 @abstract Appends a name/value pair to a DNS TXT record data section.
1836
1837 @param inTxt TXT record to append to.
1838 @param inTxtSize Size of existing TXT record.
1839 @param inTxtMaxSize Maximum size of TXT record (i.e. size of buffer).
1840 @param inName C-string name in the name/value pair (e.g. "path" for HTTP).
1841 @param inValue Value data to associate with the name. Use kDNSTextRecordNoValue for no value.
1842 @param inValueSize Size of value data. Use kDNSTextRecordNoSize for no value.
1843 @param outTxtSize Receives resulting size of TXT record. Pass NULL if not needed.
1844
1845 @result Error code indicating failure reason or kDNSNoErr if successful.
1846 */
1847
1848 DNSStatus
1849 DNSTextRecordAppendData(
1850 void * inTxt,
1851 size_t inTxtSize,
1852 size_t inTxtMaxSize,
1853 const char * inName,
1854 const void * inValue,
1855 size_t inValueSize,
1856 size_t * outTxtSize );
1857
1858 //---------------------------------------------------------------------------------------------------------------------------
1859 /*! @function DNSTextRecordEscape
1860
1861 @abstract Converts a raw TXT record into a single, null-terminated string with \001 to delimit records.
1862
1863 @param inTextRecord Raw TXT record to escape.
1864 @param inTextSize Number of bytes in the raw TXT record to escape.
1865 @param outEscapedString Receives ptr to escaped, \001-delimited, null-terminated string.
1866
1867 @result Error code indicating failure reason or kDNSNoErr if successful.
1868 */
1869
1870 DNSStatus DNSTextRecordEscape( const void *inTextRecord, size_t inTextSize, char **outEscapedString );
1871
1872 //---------------------------------------------------------------------------------------------------------------------------
1873 /*! @function DNSNameValidate
1874
1875 @abstract Validates a DNS name for correctness.
1876
1877 @param inName C-string DNS name to validate.
1878
1879 @result Error code indicating failure reason or kDNSNoErr if valid.
1880 */
1881
1882 DNSStatus DNSNameValidate( const char *inName );
1883
1884 //---------------------------------------------------------------------------------------------------------------------------
1885 /*! @function DNSServiceTypeValidate
1886
1887 @abstract Validates a service type for correctness.
1888
1889 @param inServiceType C-string service type to validate.
1890
1891 @result Error code indicating failure reason or kDNSNoErr if valid.
1892 */
1893
1894 DNSStatus DNSServiceTypeValidate( const char *inServiceType );
1895
1896 //---------------------------------------------------------------------------------------------------------------------------
1897 /*! @function DNSTextRecordValidate
1898
1899 @abstract Validates a text record for correctness and optionally builds the TXT reocrd, and returns the actual size.
1900
1901 @param inText C-string TXT record to validate. Use \001 escape sequence as record separator.
1902 @param inMaxSize Maximum size of the TXT record. Use a large number if a max size is not appropriate.
1903 @param outRecord Buffer to receive built TXT record. Use NULL if you don't need a built TXT record.
1904 @param outActualSize Ptr to receive actual size of TXT record. Use NULL if you don't need the actual size.
1905
1906 @result Error code indicating failure reason or kDNSNoErr if valid.
1907
1908 @discussion
1909
1910 A DNS TXT record consists of a packed array of length-prefixed strings with each string being up to 255 characters.
1911 To allow this to be described with a null-terminated C-string, a special escape sequence of \001 is used to separate
1912 individual character strings within the C-string.
1913
1914 For example, to represent the following 3 segments "test1=1", "test2=2", and "test3=3", you would use the following:
1915
1916 "test1=1\001test2=2\001test3=3"
1917 */
1918
1919 DNSStatus DNSTextRecordValidate( const char *inText, size_t inMaxSize, void *outRecord, size_t *outActualSize );
1920
1921 #ifdef __cplusplus
1922 }
1923 #endif
1924
1925 #endif // __DNS_SERVICES__
mirror of mDNSResponder