dnssd 0.6.0

Sign up to get free protection for your applications and to get access to all the features.
File without changes
@@ -0,0 +1,1493 @@
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: dns_sd.h,v $
28
+ Revision 1.1 2004/10/03 17:36:57 cmills
29
+ Adding the lastest version dns_sd.h to make it easier for users to compile
30
+ Ruby DNSSD from source.
31
+
32
+ Revision 1.17 2004/06/01 14:34:48 cheshire
33
+ For compatibility with older compilers, change '//' comments to ' / * ... * / '
34
+
35
+ Revision 1.16 2004/05/25 17:08:55 cheshire
36
+ Fix compiler warning (doesn't make sense for function return type to be const)
37
+
38
+ Revision 1.15 2004/05/21 21:41:35 cheshire
39
+ Add TXT record building and parsing APIs
40
+
41
+ Revision 1.14 2004/05/20 18:40:31 cheshire
42
+ Remove trailing comma that breaks build on strict compilers
43
+
44
+ Revision 1.13 2004/05/18 23:51:27 cheshire
45
+ Tidy up all checkin comments to use consistent "<rdar://problem/xxxxxxx>" format for bug numbers
46
+
47
+ Revision 1.12 2004/05/07 21:11:07 ksekar
48
+ API Update: Exposed new core error codes. Added constants for
49
+ InterfaceIndexAny and InterfaceIndexLocalOnly. Added flag for
50
+ long-lived unicast queries via DNSServiceQueryRecord.
51
+
52
+ Revision 1.11 2004/05/07 20:51:18 ksekar
53
+ <rdar://problem/3608226>: dns_sd.h needs to direct developers to
54
+ register their services at <http://www.dns-sd.org/ServiceTypes.html>
55
+
56
+ Revision 1.10 2004/05/06 18:42:58 ksekar
57
+ General dns_sd.h API cleanup, including the following radars:
58
+ <rdar://problem/3592068>: Remove flags with zero value
59
+ <rdar://problem/3479569>: Passing in NULL causes a crash.
60
+
61
+ Revision 1.9 2004/03/20 05:43:39 cheshire
62
+ Fix contributed by Terry Lambert & Alfred Perlstein:
63
+ On FreeBSD 4.x we need to include <sys/types.h> instead of <stdint.h>
64
+
65
+ Revision 1.8 2004/03/19 17:50:40 cheshire
66
+ Clarify comment about kDNSServiceMaxDomainName
67
+
68
+ Revision 1.7 2004/03/12 08:00:06 cheshire
69
+ Minor comment changes, headers, and wrap file in extern "C" for the benefit of C++ clients
70
+
71
+ Revision 1.6 2003/12/04 06:24:33 cheshire
72
+ Clarify meaning of MoreComing/Finished flag
73
+
74
+ Revision 1.5 2003/11/13 23:35:35 ksekar
75
+ <rdar://problem/3483020>: Header doesn't say that add/remove are possible values for flags
76
+ Bringing mDNSResponder project copy of dns_sd.h header up to date with
77
+ Libinfo copy
78
+
79
+ Revision 1.4 2003/10/13 23:50:53 ksekar
80
+ Updated dns_sd clientstub files to bring copies in synch with
81
+ top-of-tree Libinfo: A memory leak in dnssd_clientstub.c is fixed,
82
+ and comments in dns_sd.h are improved.
83
+
84
+ Revision 1.3 2003/08/12 19:51:51 cheshire
85
+ Update to APSL 2.0
86
+ */
87
+
88
+ #ifndef _DNS_SD_H
89
+ #define _DNS_SD_H
90
+
91
+ #ifdef __cplusplus
92
+ extern "C" {
93
+ #endif
94
+
95
+ #if defined(__FreeBSD__) && (__FreeBSD_version < 500000)
96
+ /* stdint.h does not exist on FreeBSD 4.x; its types are defined in sys/types.h instead */
97
+ #include <sys/types.h>
98
+ #else
99
+ #include <stdint.h>
100
+ #endif
101
+
102
+ /* DNSServiceRef, DNSRecordRef
103
+ *
104
+ * Opaque internal data types.
105
+ * Note: client is responsible for serializing access to these structures if
106
+ * they are shared between concurrent threads.
107
+ */
108
+
109
+ typedef struct _DNSServiceRef_t *DNSServiceRef;
110
+ typedef struct _DNSRecordRef_t *DNSRecordRef;
111
+
112
+ /* General flags used in functions defined below */
113
+ enum
114
+ {
115
+ kDNSServiceFlagsMoreComing = 0x1,
116
+ /* MoreComing indicates to a callback that at least one more result is
117
+ * queued and will be delivered following immediately after this one.
118
+ * Applications should not update their UI to display browse
119
+ * results when the MoreComing flag is set, because this would
120
+ * result in a great deal of ugly flickering on the screen.
121
+ * Applications should instead wait until until MoreComing is not set,
122
+ * and then update their UI.
123
+ * When MoreComing is not set, that doesn't mean there will be no more
124
+ * answers EVER, just that there are no more answers immediately
125
+ * available right now at this instant. If more answers become available
126
+ * in the future they will be delivered as usual.
127
+ */
128
+
129
+ kDNSServiceFlagsAdd = 0x2,
130
+ kDNSServiceFlagsDefault = 0x4,
131
+ /* Flags for domain enumeration and browse/query reply callbacks.
132
+ * "Default" applies only to enumeration and is only valid in
133
+ * conjuction with "Add". An enumeration callback with the "Add"
134
+ * flag NOT set indicates a "Remove", i.e. the domain is no longer
135
+ * valid.
136
+ */
137
+
138
+ kDNSServiceFlagsNoAutoRename = 0x8,
139
+ /* Flag for specifying renaming behavior on name conflict when registering
140
+ * non-shared records. By default, name conflicts are automatically handled
141
+ * by renaming the service. NoAutoRename overrides this behavior - with this
142
+ * flag set, name conflicts will result in a callback. The NoAutorename flag
143
+ * is only valid if a name is explicitly specified when registering a service
144
+ * (ie the default name is not used.)
145
+ */
146
+
147
+ kDNSServiceFlagsShared = 0x10,
148
+ kDNSServiceFlagsUnique = 0x20,
149
+ /* Flag for registering individual records on a connected
150
+ * DNSServiceRef. Shared indicates that there may be multiple records
151
+ * with this name on the network (e.g. PTR records). Unique indicates that the
152
+ * record's name is to be unique on the network (e.g. SRV records).
153
+ */
154
+
155
+ kDNSServiceFlagsBrowseDomains = 0x40,
156
+ kDNSServiceFlagsRegistrationDomains = 0x80,
157
+ /* Flags for specifying domain enumeration type in DNSServiceEnumerateDomains.
158
+ * BrowseDomains enumerates domains recommended for browsing, RegistrationDomains
159
+ * enumerates domains recommended for registration.
160
+ */
161
+
162
+ kDNSServiceFlagsLongLivedQuery = 0x100
163
+ /* Flag for creating a long-lived unicast query for the DNSServiceQueryRecord call. */
164
+ };
165
+
166
+ /* possible error code values */
167
+ enum
168
+ {
169
+ kDNSServiceErr_NoError = 0,
170
+ kDNSServiceErr_Unknown = -65537, /* 0xFFFE FFFF */
171
+ kDNSServiceErr_NoSuchName = -65538,
172
+ kDNSServiceErr_NoMemory = -65539,
173
+ kDNSServiceErr_BadParam = -65540,
174
+ kDNSServiceErr_BadReference = -65541,
175
+ kDNSServiceErr_BadState = -65542,
176
+ kDNSServiceErr_BadFlags = -65543,
177
+ kDNSServiceErr_Unsupported = -65544,
178
+ kDNSServiceErr_NotInitialized = -65545,
179
+ kDNSServiceErr_AlreadyRegistered = -65547,
180
+ kDNSServiceErr_NameConflict = -65548,
181
+ kDNSServiceErr_Invalid = -65549,
182
+ kDNSServiceErr_Incompatible = -65551, /* client library incompatible with daemon */
183
+ kDNSServiceErr_BadInterfaceIndex = -65552,
184
+ kDNSServiceErr_Refused = -65553,
185
+ kDNSServiceErr_NoSuchRecord = -65554,
186
+ kDNSServiceErr_NoAuth = -65555,
187
+ kDNSServiceErr_NoSuchKey = -65556
188
+ /* mDNS Error codes are in the range
189
+ * FFFE FF00 (-65792) to FFFE FFFF (-65537) */
190
+ };
191
+
192
+
193
+ /* Maximum length, in bytes, of a domain name represented as an escaped C-String */
194
+ /* including the final trailing dot, and the C-String terminating NULL at the end */
195
+
196
+ #define kDNSServiceMaxDomainName 1005
197
+
198
+ /* Constants for specifying an interface index. Specific interface indexes are
199
+ * identified via a 32-bit unsigned integer returned by the if_nametoindex()
200
+ * family of calls
201
+ */
202
+
203
+ #define kDNSServiceInterfaceIndexAny 0
204
+ #define kDNSServiceInterfaceIndexLocalOnly ( (uint32_t) ~0 )
205
+
206
+
207
+ typedef uint32_t DNSServiceFlags;
208
+ typedef int32_t DNSServiceErrorType;
209
+
210
+
211
+ /*********************************************************************************************
212
+ *
213
+ * Unix Domain Socket access, DNSServiceRef deallocation, and data processing functions
214
+ *
215
+ *********************************************************************************************/
216
+
217
+
218
+ /* DNSServiceRefSockFD()
219
+ *
220
+ * Access underlying Unix domain socket for an initialized DNSServiceRef.
221
+ * The DNS Service Discovery implmementation uses this socket to communicate between
222
+ * the client and the mDNSResponder daemon. The application MUST NOT directly read from
223
+ * or write to this socket. Access to the socket is provided so that it can be used as a
224
+ * run loop source, or in a select() loop: when data is available for reading on the socket,
225
+ * DNSServiceProcessResult() should be called, which will extract the daemon's reply from
226
+ * the socket, and pass it to the appropriate application callback. By using a run loop or
227
+ * select(), results from the daemon can be processed asynchronously. Without using these
228
+ * constructs, DNSServiceProcessResult() will block until the response from the daemon arrives.
229
+ * The client is responsible for ensuring that the data on the socket is processed in a timely
230
+ * fashion - the daemon may terminate its connection with a client that does not clear its
231
+ * socket buffer.
232
+ *
233
+ * sdRef: A DNSServiceRef initialized by any of the DNSService calls.
234
+ *
235
+ * return value: The DNSServiceRef's underlying socket descriptor, or -1 on
236
+ * error.
237
+ */
238
+
239
+ int DNSServiceRefSockFD(DNSServiceRef sdRef);
240
+
241
+
242
+ /* DNSServiceProcessResult()
243
+ *
244
+ * Read a reply from the daemon, calling the appropriate application callback. This call will
245
+ * block until the daemon's response is received. Use DNSServiceRefSockFD() in
246
+ * conjunction with a run loop or select() to determine the presence of a response from the
247
+ * server before calling this function to process the reply without blocking. Call this function
248
+ * at any point if it is acceptable to block until the daemon's response arrives. Note that the
249
+ * client is responsible for ensuring that DNSServiceProcessResult() is called whenever there is
250
+ * a reply from the daemon - the daemon may terminate its connection with a client that does not
251
+ * process the daemon's responses.
252
+ *
253
+ * sdRef: A DNSServiceRef initialized by any of the DNSService calls
254
+ * that take a callback parameter.
255
+ *
256
+ * return value: Returns kDNSServiceErr_NoError on success, otherwise returns
257
+ * an error code indicating the specific failure that occurred.
258
+ */
259
+
260
+ DNSServiceErrorType DNSServiceProcessResult(DNSServiceRef sdRef);
261
+
262
+
263
+ /* DNSServiceRefDeallocate()
264
+ *
265
+ * Terminate a connection with the daemon and free memory associated with the DNSServiceRef.
266
+ * Any services or records registered with this DNSServiceRef will be deregistered. Any
267
+ * Browse, Resolve, or Query operations called with this reference will be terminated.
268
+ *
269
+ * Note: If the reference's underlying socket is used in a run loop or select() call, it should
270
+ * be removed BEFORE DNSServiceRefDeallocate() is called, as this function closes the reference's
271
+ * socket.
272
+ *
273
+ * Note: If the reference was initialized with DNSServiceCreateConnection(), any DNSRecordRefs
274
+ * created via this reference will be invalidated by this call - the resource records are
275
+ * deregistered, and their DNSRecordRefs may not be used in subsequent functions. Similarly,
276
+ * if the reference was initialized with DNSServiceRegister, and an extra resource record was
277
+ * added to the service via DNSServiceAddRecord(), the DNSRecordRef created by the Add() call
278
+ * is invalidated when this function is called - the DNSRecordRef may not be used in subsequent
279
+ * functions.
280
+ *
281
+ * Note: This call is to be used only with the DNSServiceRef defined by this API. It is
282
+ * not compatible with dns_service_discovery_ref objects defined in the legacy Mach-based
283
+ * DNSServiceDiscovery.h API.
284
+ *
285
+ * sdRef: A DNSServiceRef initialized by any of the DNSService calls.
286
+ *
287
+ */
288
+
289
+ void DNSServiceRefDeallocate(DNSServiceRef sdRef);
290
+
291
+
292
+ /*********************************************************************************************
293
+ *
294
+ * Domain Enumeration
295
+ *
296
+ *********************************************************************************************/
297
+
298
+ /* DNSServiceEnumerateDomains()
299
+ *
300
+ * Asynchronously enumerate domains available for browsing and registration.
301
+ * Currently, the only domain returned is "local.", but other domains will be returned in future.
302
+ *
303
+ * The enumeration MUST be cancelled via DNSServiceRefDeallocate() when no more domains
304
+ * are to be found.
305
+ *
306
+ *
307
+ * DNSServiceDomainEnumReply Callback Parameters:
308
+ *
309
+ * sdRef: The DNSServiceRef initialized by DNSServiceEnumerateDomains().
310
+ *
311
+ * flags: Possible values are:
312
+ * kDNSServiceFlagsMoreComing
313
+ * kDNSServiceFlagsAdd
314
+ * kDNSServiceFlagsDefault
315
+ *
316
+ * interfaceIndex: Specifies the interface on which the domain exists. (The index for a given
317
+ * interface is determined via the if_nametoindex() family of calls.)
318
+ *
319
+ * errorCode: Will be kDNSServiceErr_NoError (0) on success, otherwise indicates
320
+ * the failure that occurred (other parameters are undefined if errorCode is nonzero).
321
+ *
322
+ * replyDomain: The name of the domain.
323
+ *
324
+ * context: The context pointer passed to DNSServiceEnumerateDomains.
325
+ *
326
+ */
327
+
328
+ typedef void (*DNSServiceDomainEnumReply)
329
+ (
330
+ DNSServiceRef sdRef,
331
+ DNSServiceFlags flags,
332
+ uint32_t interfaceIndex,
333
+ DNSServiceErrorType errorCode,
334
+ const char *replyDomain,
335
+ void *context
336
+ );
337
+
338
+
339
+ /* DNSServiceEnumerateDomains() Parameters:
340
+ *
341
+ *
342
+ * sdRef: A pointer to an uninitialized DNSServiceRef. May be passed to
343
+ * DNSServiceRefDeallocate() to cancel the enumeration.
344
+ *
345
+ * flags: Possible values are:
346
+ * kDNSServiceFlagsBrowseDomains to enumerate domains recommended for browsing.
347
+ * kDNSServiceFlagsRegistrationDomains to enumerate domains recommended
348
+ * for registration.
349
+ *
350
+ * interfaceIndex: If non-zero, specifies the interface on which to look for domains.
351
+ * (the index for a given interface is determined via the if_nametoindex()
352
+ * family of calls.) Most applications will pass 0 to enumerate domains on
353
+ * all interfaces.
354
+ *
355
+ * callBack: The function to be called when a domain is found or the call asynchronously
356
+ * fails.
357
+ *
358
+ * context: An application context pointer which is passed to the callback function
359
+ * (may be NULL).
360
+ *
361
+ * return value: Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
362
+ * errors are delivered to the callback), otherwise returns an error code indicating
363
+ * the error that occurred (the callback is not invoked and the DNSServiceRef
364
+ * is not initialized.)
365
+ */
366
+
367
+ DNSServiceErrorType DNSServiceEnumerateDomains
368
+ (
369
+ DNSServiceRef *sdRef,
370
+ DNSServiceFlags flags,
371
+ uint32_t interfaceIndex,
372
+ DNSServiceDomainEnumReply callBack,
373
+ void *context /* may be NULL */
374
+ );
375
+
376
+
377
+ /*********************************************************************************************
378
+ *
379
+ * Service Registration
380
+ *
381
+ *********************************************************************************************/
382
+
383
+ /* Register a service that is discovered via Browse() and Resolve() calls.
384
+ *
385
+ *
386
+ * DNSServiceRegisterReply() Callback Parameters:
387
+ *
388
+ * sdRef: The DNSServiceRef initialized by DNSServiceRegister().
389
+ *
390
+ * flags: Currently unused, reserved for future use.
391
+ *
392
+ * errorCode: Will be kDNSServiceErr_NoError on success, otherwise will
393
+ * indicate the failure that occurred (including name conflicts, if the
394
+ * kDNSServiceFlagsNoAutoRename flag was passed to the
395
+ * callout.) Other parameters are undefined if errorCode is nonzero.
396
+ *
397
+ * name: The service name registered (if the application did not specify a name in
398
+ * DNSServiceRegister(), this indicates what name was automatically chosen).
399
+ *
400
+ * regtype: The type of service registered, as it was passed to the callout.
401
+ *
402
+ * domain: The domain on which the service was registered (if the application did not
403
+ * specify a domain in DNSServiceRegister(), this indicates the default domain
404
+ * on which the service was registered).
405
+ *
406
+ * context: The context pointer that was passed to the callout.
407
+ *
408
+ */
409
+
410
+ typedef void (*DNSServiceRegisterReply)
411
+ (
412
+ DNSServiceRef sdRef,
413
+ DNSServiceFlags flags,
414
+ DNSServiceErrorType errorCode,
415
+ const char *name,
416
+ const char *regtype,
417
+ const char *domain,
418
+ void *context
419
+ );
420
+
421
+
422
+ /* DNSServiceRegister() Parameters:
423
+ *
424
+ * sdRef: A pointer to an uninitialized DNSServiceRef. If this call succeeds, the reference
425
+ * may be passed to
426
+ * DNSServiceRefDeallocate() to deregister the service.
427
+ *
428
+ * interfaceIndex: If non-zero, specifies the interface on which to register the service
429
+ * (the index for a given interface is determined via the if_nametoindex()
430
+ * family of calls.) Most applications will pass 0 to register on all
431
+ * available interfaces. Pass -1 to register a service only on the local
432
+ * machine (service will not be visible to remote hosts.)
433
+ *
434
+ * flags: Indicates the renaming behavior on name conflict (most applications
435
+ * will pass 0). See flag definitions above for details.
436
+ *
437
+ * name: If non-NULL, specifies the service name to be registered.
438
+ * Most applications will not specify a name, in which case the
439
+ * computer name is used (this name is communicated to the client via
440
+ * the callback).
441
+ *
442
+ * regtype: The service type followed by the protocol, separated by a dot
443
+ * (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp".
444
+ * New service types should be registered at htp://www.dns-sd.org/ServiceTypes.html.
445
+ *
446
+ * domain: If non-NULL, specifies the domain on which to advertise the service.
447
+ * Most applications will not specify a domain, instead automatically
448
+ * registering in the default domain(s).
449
+ *
450
+ * host: If non-NULL, specifies the SRV target host name. Most applications
451
+ * will not specify a host, instead automatically using the machine's
452
+ * default host name(s). Note that specifying a non-NULL host does NOT
453
+ * create an address record for that host - the application is responsible
454
+ * for ensuring that the appropriate address record exists, or creating it
455
+ * via DNSServiceRegisterRecord().
456
+ *
457
+ * port: The port, in network byte order, on which the service accepts connections.
458
+ * Pass 0 for a "placeholder" service (i.e. a service that will not be discovered
459
+ * by browsing, but will cause a name conflict if another client tries to
460
+ * register that same name). Most clients will not use placeholder services.
461
+ *
462
+ * txtLen: The length of the txtRecord, in bytes. Must be zero if the txtRecord is NULL.
463
+ *
464
+ * txtRecord: The txt record rdata. May be NULL. Note that a non-NULL txtRecord
465
+ * MUST be a properly formatted DNS TXT record, i.e. <length byte> <data>
466
+ * <length byte> <data> ...
467
+ *
468
+ * callBack: The function to be called when the registration completes or asynchronously
469
+ * fails. The client MAY pass NULL for the callback - The client will NOT be notified
470
+ * of the default values picked on its behalf, and the client will NOT be notified of any
471
+ * asynchronous errors (e.g. out of memory errors, etc.) that may prevent the registration
472
+ * of the service. The client may NOT pass the NoAutoRename flag if the callback is NULL.
473
+ * The client may still deregister the service at any time via DNSServiceRefDeallocate().
474
+ *
475
+ * context: An application context pointer which is passed to the callback function
476
+ * (may be NULL).
477
+ *
478
+ * return value: Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
479
+ * errors are delivered to the callback), otherwise returns an error code indicating
480
+ * the error that occurred (the callback is never invoked and the DNSServiceRef
481
+ * is not initialized.)
482
+ *
483
+ */
484
+
485
+ DNSServiceErrorType DNSServiceRegister
486
+ (
487
+ DNSServiceRef *sdRef,
488
+ DNSServiceFlags flags,
489
+ uint32_t interfaceIndex,
490
+ const char *name, /* may be NULL */
491
+ const char *regtype,
492
+ const char *domain, /* may be NULL */
493
+ const char *host, /* may be NULL */
494
+ uint16_t port,
495
+ uint16_t txtLen,
496
+ const void *txtRecord, /* may be NULL */
497
+ DNSServiceRegisterReply callBack, /* may be NULL */
498
+ void *context /* may be NULL */
499
+ );
500
+
501
+
502
+ /* DNSServiceAddRecord()
503
+ *
504
+ * Add a record to a registered service. The name of the record will be the same as the
505
+ * registered service's name.
506
+ * The record can later be updated or deregistered by passing the RecordRef initialized
507
+ * by this function to DNSServiceUpdateRecord() or DNSServiceRemoveRecord().
508
+ *
509
+ *
510
+ * Parameters;
511
+ *
512
+ * sdRef: A DNSServiceRef initialized by DNSServiceRegister().
513
+ *
514
+ * RecordRef: A pointer to an uninitialized DNSRecordRef. Upon succesfull completion of this
515
+ * call, this ref may be passed to DNSServiceUpdateRecord() or DNSServiceRemoveRecord().
516
+ * If the above DNSServiceRef is passed to DNSServiceRefDeallocate(), RecordRef is also
517
+ * invalidated and may not be used further.
518
+ *
519
+ * flags: Currently ignored, reserved for future use.
520
+ *
521
+ * rrtype: The type of the record (e.g. TXT, SRV, etc), as defined in nameser.h.
522
+ *
523
+ * rdlen: The length, in bytes, of the rdata.
524
+ *
525
+ * rdata: The raw rdata to be contained in the added resource record.
526
+ *
527
+ * ttl: The time to live of the resource record, in seconds.
528
+ *
529
+ * return value: Returns kDNSServiceErr_NoError on success, otherwise returns an
530
+ * error code indicating the error that occurred (the RecordRef is not initialized).
531
+ */
532
+
533
+ DNSServiceErrorType DNSServiceAddRecord
534
+ (
535
+ DNSServiceRef sdRef,
536
+ DNSRecordRef *RecordRef,
537
+ DNSServiceFlags flags,
538
+ uint16_t rrtype,
539
+ uint16_t rdlen,
540
+ const void *rdata,
541
+ uint32_t ttl
542
+ );
543
+
544
+
545
+ /* DNSServiceUpdateRecord
546
+ *
547
+ * Update a registered resource record. The record must either be:
548
+ * - The primary txt record of a service registered via DNSServiceRegister()
549
+ * - A record added to a registered service via DNSServiceAddRecord()
550
+ * - An individual record registered by DNSServiceRegisterRecord()
551
+ *
552
+ *
553
+ * Parameters:
554
+ *
555
+ * sdRef: A DNSServiceRef that was initialized by DNSServiceRegister()
556
+ * or DNSServiceCreateConnection().
557
+ *
558
+ * RecordRef: A DNSRecordRef initialized by DNSServiceAddRecord, or NULL to update the
559
+ * service's primary txt record.
560
+ *
561
+ * flags: Currently ignored, reserved for future use.
562
+ *
563
+ * rdlen: The length, in bytes, of the new rdata.
564
+ *
565
+ * rdata: The new rdata to be contained in the updated resource record.
566
+ *
567
+ * ttl: The time to live of the updated resource record, in seconds.
568
+ *
569
+ * return value: Returns kDNSServiceErr_NoError on success, otherwise returns an
570
+ * error code indicating the error that occurred.
571
+ */
572
+
573
+ DNSServiceErrorType DNSServiceUpdateRecord
574
+ (
575
+ DNSServiceRef sdRef,
576
+ DNSRecordRef RecordRef, /* may be NULL */
577
+ DNSServiceFlags flags,
578
+ uint16_t rdlen,
579
+ const void *rdata,
580
+ uint32_t ttl
581
+ );
582
+
583
+
584
+ /* DNSServiceRemoveRecord
585
+ *
586
+ * Remove a record previously added to a service record set via DNSServiceAddRecord(), or deregister
587
+ * an record registered individually via DNSServiceRegisterRecord().
588
+ *
589
+ * Parameters:
590
+ *
591
+ * sdRef: A DNSServiceRef initialized by DNSServiceRegister() (if the
592
+ * record being removed was registered via DNSServiceAddRecord()) or by
593
+ * DNSServiceCreateConnection() (if the record being removed was registered via
594
+ * DNSServiceRegisterRecord()).
595
+ *
596
+ * recordRef: A DNSRecordRef initialized by a successful call to DNSServiceAddRecord()
597
+ * or DNSServiceRegisterRecord().
598
+ *
599
+ * flags: Currently ignored, reserved for future use.
600
+ *
601
+ * return value: Returns kDNSServiceErr_NoError on success, otherwise returns an
602
+ * error code indicating the error that occurred.
603
+ */
604
+
605
+ DNSServiceErrorType DNSServiceRemoveRecord
606
+ (
607
+ DNSServiceRef sdRef,
608
+ DNSRecordRef RecordRef,
609
+ DNSServiceFlags flags
610
+ );
611
+
612
+
613
+ /*********************************************************************************************
614
+ *
615
+ * Service Discovery
616
+ *
617
+ *********************************************************************************************/
618
+
619
+ /* Browse for instances of a service.
620
+ *
621
+ *
622
+ * DNSServiceBrowseReply() Parameters:
623
+ *
624
+ * sdRef: The DNSServiceRef initialized by DNSServiceBrowse().
625
+ *
626
+ * flags: Possible values are kDNSServiceFlagsMoreComing and kDNSServiceFlagsAdd.
627
+ * See flag definitions for details.
628
+ *
629
+ * interfaceIndex: The interface on which the service is advertised. This index should
630
+ * be passed to DNSServiceResolve() when resolving the service.
631
+ *
632
+ * errorCode: Will be kDNSServiceErr_NoError (0) on success, otherwise will
633
+ * indicate the failure that occurred. Other parameters are undefined if
634
+ * the errorCode is nonzero.
635
+ *
636
+ * serviceName: The service name discovered.
637
+ *
638
+ * regtype: The service type, as passed in to DNSServiceBrowse().
639
+ *
640
+ * domain: The domain on which the service was discovered (if the application did not
641
+ * specify a domain in DNSServicBrowse(), this indicates the domain on which the
642
+ * service was discovered.)
643
+ *
644
+ * context: The context pointer that was passed to the callout.
645
+ *
646
+ */
647
+
648
+ typedef void (*DNSServiceBrowseReply)
649
+ (
650
+ DNSServiceRef sdRef,
651
+ DNSServiceFlags flags,
652
+ uint32_t interfaceIndex,
653
+ DNSServiceErrorType errorCode,
654
+ const char *serviceName,
655
+ const char *regtype,
656
+ const char *replyDomain,
657
+ void *context
658
+ );
659
+
660
+
661
+ /* DNSServiceBrowse() Parameters:
662
+ *
663
+ * sdRef: A pointer to an uninitialized DNSServiceRef. May be passed to
664
+ * DNSServiceRefDeallocate() to terminate the browse.
665
+ *
666
+ * flags: Currently ignored, reserved for future use.
667
+ *
668
+ * interfaceIndex: If non-zero, specifies the interface on which to browse for services
669
+ * (the index for a given interface is determined via the if_nametoindex()
670
+ * family of calls.) Most applications will pass 0 to browse on all available
671
+ * interfaces. Pass -1 to only browse for services provided on the local host.
672
+ *
673
+ * regtype: The service type being browsed for followed by the protocol, separated by a
674
+ * dot (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp".
675
+ *
676
+ * domain: If non-NULL, specifies the domain on which to browse for services.
677
+ * Most applications will not specify a domain, instead browsing on the
678
+ * default domain(s).
679
+ *
680
+ * callBack: The function to be called when an instance of the service being browsed for
681
+ * is found, or if the call asynchronously fails.
682
+ *
683
+ * context: An application context pointer which is passed to the callback function
684
+ * (may be NULL).
685
+ *
686
+ * return value: Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
687
+ * errors are delivered to the callback), otherwise returns an error code indicating
688
+ * the error that occurred (the callback is not invoked and the DNSServiceRef
689
+ * is not initialized.)
690
+ */
691
+
692
+ DNSServiceErrorType DNSServiceBrowse
693
+ (
694
+ DNSServiceRef *sdRef,
695
+ DNSServiceFlags flags,
696
+ uint32_t interfaceIndex,
697
+ const char *regtype,
698
+ const char *domain, /* may be NULL */
699
+ DNSServiceBrowseReply callBack,
700
+ void *context /* may be NULL */
701
+ );
702
+
703
+
704
+ /* DNSServiceResolve()
705
+ *
706
+ * Resolve a service name discovered via DNSServiceBrowse() to a target host name, port number, and
707
+ * txt record.
708
+ *
709
+ * Note: Applications should NOT use DNSServiceResolve() solely for txt record monitoring - use
710
+ * DNSServiceQueryRecord() instead, as it is more efficient for this task.
711
+ *
712
+ * Note: When the desired results have been returned, the client MUST terminate the resolve by calling
713
+ * DNSServiceRefDeallocate().
714
+ *
715
+ * Note: DNSServiceResolve() behaves correctly for typical services that have a single SRV record and
716
+ * a single TXT record (the TXT record may be empty.) To resolve non-standard services with multiple
717
+ * SRV or TXT records, DNSServiceQueryRecord() should be used.
718
+ *
719
+ * DNSServiceResolveReply Callback Parameters:
720
+ *
721
+ * sdRef: The DNSServiceRef initialized by DNSServiceResolve().
722
+ *
723
+ * flags: Currently unused, reserved for future use.
724
+ *
725
+ * interfaceIndex: The interface on which the service was resolved.
726
+ *
727
+ * errorCode: Will be kDNSServiceErr_NoError (0) on success, otherwise will
728
+ * indicate the failure that occurred. Other parameters are undefined if
729
+ * the errorCode is nonzero.
730
+ *
731
+ * fullname: The full service domain name, in the form <servicename>.<protocol>.<domain>.
732
+ * (Any literal dots (".") are escaped with a backslash ("\."), and literal
733
+ * backslashes are escaped with a second backslash ("\\"), e.g. a web server
734
+ * named "Dr. Pepper" would have the fullname "Dr\.\032Pepper._http._tcp.local.").
735
+ * This is the appropriate format to pass to standard system DNS APIs such as
736
+ * res_query(), or to the special-purpose functions included in this API that
737
+ * take fullname parameters.
738
+ *
739
+ * hosttarget: The target hostname of the machine providing the service. This name can
740
+ * be passed to functions like gethostbyname() to identify the host's IP address.
741
+ *
742
+ * port: The port, in network byte order, on which connections are accepted for this service.
743
+ *
744
+ * txtLen: The length of the txt record, in bytes.
745
+ *
746
+ * txtRecord: The service's primary txt record, in standard txt record format.
747
+ *
748
+
749
+ * context: The context pointer that was passed to the callout.
750
+ *
751
+ */
752
+
753
+ typedef void (*DNSServiceResolveReply)
754
+ (
755
+ DNSServiceRef sdRef,
756
+ DNSServiceFlags flags,
757
+ uint32_t interfaceIndex,
758
+ DNSServiceErrorType errorCode,
759
+ const char *fullname,
760
+ const char *hosttarget,
761
+ uint16_t port,
762
+ uint16_t txtLen,
763
+ const char *txtRecord,
764
+ void *context
765
+ );
766
+
767
+
768
+ /* DNSServiceResolve() Parameters
769
+ *
770
+ * sdRef: A pointer to an uninitialized DNSServiceRef. May be passed to
771
+ * DNSServiceRefDeallocate() to terminate the resolve.
772
+ *
773
+ * flags: Currently ignored, reserved for future use.
774
+ *
775
+ * interfaceIndex: The interface on which to resolve the service. The client should
776
+ * pass the interface on which the servicename was discovered, i.e.
777
+ * the interfaceIndex passed to the DNSServiceBrowseReply callback,
778
+ * or 0 to resolve the named service on all available interfaces.
779
+ *
780
+ * name: The servicename to be resolved.
781
+ *
782
+ * regtype: The service type being resolved followed by the protocol, separated by a
783
+ * dot (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp".
784
+ *
785
+ * domain: The domain on which the service is registered, i.e. the domain passed
786
+ * to the DNSServiceBrowseReply callback.
787
+ *
788
+ * callBack: The function to be called when a result is found, or if the call
789
+ * asynchronously fails.
790
+ *
791
+ * context: An application context pointer which is passed to the callback function
792
+ * (may be NULL).
793
+ *
794
+ * return value: Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
795
+ * errors are delivered to the callback), otherwise returns an error code indicating
796
+ * the error that occurred (the callback is never invoked and the DNSServiceRef
797
+ * is not initialized.)
798
+ */
799
+
800
+ DNSServiceErrorType DNSServiceResolve
801
+ (
802
+ DNSServiceRef *sdRef,
803
+ DNSServiceFlags flags,
804
+ uint32_t interfaceIndex,
805
+ const char *name,
806
+ const char *regtype,
807
+ const char *domain,
808
+ DNSServiceResolveReply callBack,
809
+ void *context /* may be NULL */
810
+ );
811
+
812
+
813
+ /*********************************************************************************************
814
+ *
815
+ * Special Purpose Calls (most applications will not use these)
816
+ *
817
+ *********************************************************************************************/
818
+
819
+ /* Note on DNS Naming Conventions:
820
+ *
821
+ * The functions below refer to resource records by their full domain name, unlike the
822
+ * functions above which divide the name into servicename/regtype/domain fields. In the
823
+ * functions above, a dot (".") is considered to be a literal dot in the servicename field
824
+ * (e.g. "Dr. Pepper") and a label separator in the regtype ("_ftp._tcp") or domain
825
+ * ("apple.com") fields. Literal dots in the domain field would be escaped with a backslash,
826
+ * and literal backslashes would be escaped with a second backslash (this is generally not an
827
+ * issue, as domain names on the Internet today almost never use characters other than
828
+ * letters, digits, or hyphens, and the dots are label separators.) Furthermore, this is
829
+ * transparent to the caller, so long as the fields are passed between functions without
830
+ * manipulation. However, the following, special-purpose calls use a single, full domain
831
+ * name. As such, all dots are considered to be label separators, unless escaped, and all
832
+ * backslashes are considered to be escape characters, unless preceded by a second backslash.
833
+ * For example, the name "Dr. Smith \ Dr. Johnson" could be passed literally as a service
834
+ * name parameter in the above calls, but in the special purpose calls, the dots and backslash
835
+ * would have to be escaped (e.g. "Dr\. Smith \\ Dr\. Johnson._ftp._tcp.apple.com" for an ftp
836
+ * service on the apple.com domain.) The function DNSServiceConstructFullName() is provided
837
+ * to aid in this conversion from servicename/regtype/domain to a single fully-qualified DNS
838
+ * name with proper escaping.
839
+ */
840
+
841
+ /* DNSServiceCreateConnection()
842
+ *
843
+ * Create a connection to the daemon allowing efficient registration of
844
+ * multiple individual records.
845
+ *
846
+ *
847
+ * Parameters:
848
+ *
849
+ * sdRef: A pointer to an uninitialized DNSServiceRef. Deallocating
850
+ * the reference (via DNSServiceRefDeallocate()) severs the
851
+ * connection and deregisters all records registered on this connection.
852
+ *
853
+ * return value: Returns kDNSServiceErr_NoError on success, otherwise returns
854
+ * an error code indicating the specific failure that occurred (in which
855
+ * case the DNSServiceRef is not initialized).
856
+ */
857
+
858
+ DNSServiceErrorType DNSServiceCreateConnection(DNSServiceRef *sdRef);
859
+
860
+
861
+ /* DNSServiceRegisterRecord
862
+ *
863
+ * Register an individual resource record on a connected DNSServiceRef.
864
+ *
865
+ * Note that name conflicts occurring for records registered via this call must be handled
866
+ * by the client in the callback.
867
+ *
868
+ *
869
+ * DNSServiceRegisterRecordReply() parameters:
870
+ *
871
+ * sdRef: The connected DNSServiceRef initialized by
872
+ * DNSServiceDiscoveryConnect().
873
+ *
874
+ * RecordRef: The DNSRecordRef initialized by DNSServiceRegisterRecord(). If the above
875
+ * DNSServiceRef is passed to DNSServiceRefDeallocate(), this DNSRecordRef is
876
+ * invalidated, and may not be used further.
877
+ *
878
+ * flags: Currently unused, reserved for future use.
879
+ *
880
+ * errorCode: Will be kDNSServiceErr_NoError on success, otherwise will
881
+ * indicate the failure that occurred (including name conflicts.)
882
+ * Other parameters are undefined if errorCode is nonzero.
883
+ *
884
+ * context: The context pointer that was passed to the callout.
885
+ *
886
+ */
887
+
888
+ typedef void (*DNSServiceRegisterRecordReply)
889
+ (
890
+ DNSServiceRef sdRef,
891
+ DNSRecordRef RecordRef,
892
+ DNSServiceFlags flags,
893
+ DNSServiceErrorType errorCode,
894
+ void *context
895
+ );
896
+
897
+
898
+ /* DNSServiceRegisterRecord() Parameters:
899
+ *
900
+ * sdRef: A DNSServiceRef initialized by DNSServiceCreateConnection().
901
+ *
902
+ * RecordRef: A pointer to an uninitialized DNSRecordRef. Upon succesfull completion of this
903
+ * call, this ref may be passed to DNSServiceUpdateRecord() or DNSServiceRemoveRecord().
904
+ * (To deregister ALL records registered on a single connected DNSServiceRef
905
+ * and deallocate each of their corresponding DNSServiceRecordRefs, call
906
+ * DNSServiceRefDealloocate()).
907
+ *
908
+ * flags: Possible values are kDNSServiceFlagsShared or kDNSServiceFlagsUnique
909
+ * (see flag type definitions for details).
910
+ *
911
+ * interfaceIndex: If non-zero, specifies the interface on which to register the record
912
+ * (the index for a given interface is determined via the if_nametoindex()
913
+ * family of calls.) Passing 0 causes the record to be registered on all interfaces.
914
+ * Passing -1 causes the record to only be visible on the local host.
915
+ *
916
+ * fullname: The full domain name of the resource record.
917
+ *
918
+ * rrtype: The numerical type of the resource record (e.g. PTR, SRV, etc), as defined
919
+ * in nameser.h.
920
+ *
921
+ * rrclass: The class of the resource record, as defined in nameser.h (usually 1 for the
922
+ * Internet class).
923
+ *
924
+ * rdlen: Length, in bytes, of the rdata.
925
+ *
926
+ * rdata: A pointer to the raw rdata, as it is to appear in the DNS record.
927
+ *
928
+ * ttl: The time to live of the resource record, in seconds.
929
+ *
930
+ * callBack: The function to be called when a result is found, or if the call
931
+ * asynchronously fails (e.g. because of a name conflict.)
932
+ *
933
+ * context: An application context pointer which is passed to the callback function
934
+ * (may be NULL).
935
+ *
936
+ * return value: Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
937
+ * errors are delivered to the callback), otherwise returns an error code indicating
938
+ * the error that occurred (the callback is never invoked and the DNSRecordRef is
939
+ * not initialized.)
940
+ */
941
+
942
+ DNSServiceErrorType DNSServiceRegisterRecord
943
+ (
944
+ DNSServiceRef sdRef,
945
+ DNSRecordRef *RecordRef,
946
+ DNSServiceFlags flags,
947
+ uint32_t interfaceIndex,
948
+ const char *fullname,
949
+ uint16_t rrtype,
950
+ uint16_t rrclass,
951
+ uint16_t rdlen,
952
+ const void *rdata,
953
+ uint32_t ttl,
954
+ DNSServiceRegisterRecordReply callBack,
955
+ void *context /* may be NULL */
956
+ );
957
+
958
+
959
+ /* DNSServiceQueryRecord
960
+ *
961
+ * Query for an arbitrary DNS record.
962
+ *
963
+ *
964
+ * DNSServiceQueryRecordReply() Callback Parameters:
965
+ *
966
+ * sdRef: The DNSServiceRef initialized by DNSServiceQueryRecord().
967
+ *
968
+ * flags: Possible values are kDNSServiceFlagsMoreComing and
969
+ * kDNSServiceFlagsAdd. The Add flag is NOT set for PTR records
970
+ * with a ttl of 0, i.e. "Remove" events.
971
+ *
972
+ * interfaceIndex: The interface on which the query was resolved (the index for a given
973
+ * interface is determined via the if_nametoindex() family of calls).
974
+ *
975
+ * errorCode: Will be kDNSServiceErr_NoError on success, otherwise will
976
+ * indicate the failure that occurred. Other parameters are undefined if
977
+ * errorCode is nonzero.
978
+ *
979
+ * fullname: The resource record's full domain name.
980
+ *
981
+ * rrtype: The resource record's type (e.g. PTR, SRV, etc) as defined in nameser.h.
982
+ *
983
+ * rrclass: The class of the resource record, as defined in nameser.h (usually 1).
984
+ *
985
+ * rdlen: The length, in bytes, of the resource record rdata.
986
+ *
987
+ * rdata: The raw rdata of the resource record.
988
+ *
989
+ * ttl: The resource record's time to live, in seconds.
990
+ *
991
+ * context: The context pointer that was passed to the callout.
992
+ *
993
+ */
994
+
995
+ typedef void (*DNSServiceQueryRecordReply)
996
+ (
997
+ DNSServiceRef DNSServiceRef,
998
+ DNSServiceFlags flags,
999
+ uint32_t interfaceIndex,
1000
+ DNSServiceErrorType errorCode,
1001
+ const char *fullname,
1002
+ uint16_t rrtype,
1003
+ uint16_t rrclass,
1004
+ uint16_t rdlen,
1005
+ const void *rdata,
1006
+ uint32_t ttl,
1007
+ void *context
1008
+ );
1009
+
1010
+
1011
+ /* DNSServiceQueryRecord() Parameters:
1012
+ *
1013
+ * sdRef: A pointer to an uninitialized DNSServiceRef.
1014
+ *
1015
+ * flags: Pass kDNSServiceFlagsLongLivedQuery to create a "long-lived" unicast
1016
+ * query in a non-local domain. Without setting this flag, unicast queries
1017
+ * will be one-shot - that is, only answers available at the time of the call
1018
+ * will be returned. By setting this flag, answers (including Add and Remove
1019
+ * events) that become available after the initial call is made will generate
1020
+ * callbacks. This flag has no effect on link-local multicast queries.
1021
+ *
1022
+ * interfaceIndex: If non-zero, specifies the interface on which to issue the query
1023
+ * (the index for a given interface is determined via the if_nametoindex()
1024
+ * family of calls.) Passing 0 causes the name to be queried for on all
1025
+ * interfaces. Passing -1 causes the name to be queried for only on the
1026
+ * local host.
1027
+ *
1028
+ * fullname: The full domain name of the resource record to be queried for.
1029
+ *
1030
+ * rrtype: The numerical type of the resource record to be queried for (e.g. PTR, SRV, etc)
1031
+ * as defined in nameser.h.
1032
+ *
1033
+ * rrclass: The class of the resource record, as defined in nameser.h
1034
+ * (usually 1 for the Internet class).
1035
+ *
1036
+ * callBack: The function to be called when a result is found, or if the call
1037
+ * asynchronously fails.
1038
+ *
1039
+ * context: An application context pointer which is passed to the callback function
1040
+ * (may be NULL).
1041
+ *
1042
+ * return value: Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
1043
+ * errors are delivered to the callback), otherwise returns an error code indicating
1044
+ * the error that occurred (the callback is never invoked and the DNSServiceRef
1045
+ * is not initialized.)
1046
+ */
1047
+
1048
+ DNSServiceErrorType DNSServiceQueryRecord
1049
+ (
1050
+ DNSServiceRef *sdRef,
1051
+ DNSServiceFlags flags,
1052
+ uint32_t interfaceIndex,
1053
+ const char *fullname,
1054
+ uint16_t rrtype,
1055
+ uint16_t rrclass,
1056
+ DNSServiceQueryRecordReply callBack,
1057
+ void *context /* may be NULL */
1058
+ );
1059
+
1060
+
1061
+ /* DNSServiceReconfirmRecord
1062
+ *
1063
+ * Instruct the daemon to verify the validity of a resource record that appears to
1064
+ * be out of date (e.g. because tcp connection to a service's target failed.)
1065
+ * Causes the record to be flushed from the daemon's cache (as well as all other
1066
+ * daemons' caches on the network) if the record is determined to be invalid.
1067
+ *
1068
+ * Parameters:
1069
+ *
1070
+ * flags: Currently unused, reserved for future use.
1071
+ *
1072
+ * fullname: The resource record's full domain name.
1073
+ *
1074
+ * rrtype: The resource record's type (e.g. PTR, SRV, etc) as defined in nameser.h.
1075
+ *
1076
+ * rrclass: The class of the resource record, as defined in nameser.h (usually 1).
1077
+ *
1078
+ * rdlen: The length, in bytes, of the resource record rdata.
1079
+ *
1080
+ * rdata: The raw rdata of the resource record.
1081
+ *
1082
+ */
1083
+
1084
+ void DNSServiceReconfirmRecord
1085
+ (
1086
+ DNSServiceFlags flags,
1087
+ uint32_t interfaceIndex,
1088
+ const char *fullname,
1089
+ uint16_t rrtype,
1090
+ uint16_t rrclass,
1091
+ uint16_t rdlen,
1092
+ const void *rdata
1093
+ );
1094
+
1095
+
1096
+ /*********************************************************************************************
1097
+ *
1098
+ * General Utility Functions
1099
+ *
1100
+ *********************************************************************************************/
1101
+
1102
+ /* DNSServiceConstructFullName()
1103
+ *
1104
+ * Concatenate a three-part domain name (as returned by the above callbacks) into a
1105
+ * properly-escaped full domain name. Note that callbacks in the above functions ALREADY ESCAPE
1106
+ * strings where necessary.
1107
+ *
1108
+ * Parameters:
1109
+ *
1110
+ * fullName: A pointer to a buffer that where the resulting full domain name is to be written.
1111
+ * The buffer must be kDNSServiceMaxDomainName (1005) bytes in length to
1112
+ * accommodate the longest legal domain name without buffer overrun.
1113
+ *
1114
+ * service: The service name - any dots or slashes must NOT be escaped.
1115
+ * May be NULL (to construct a PTR record name, e.g.
1116
+ * "_ftp._tcp.apple.com").
1117
+ *
1118
+ * regtype: The service type followed by the protocol, separated by a dot
1119
+ * (e.g. "_ftp._tcp").
1120
+ *
1121
+ * domain: The domain name, e.g. "apple.com". Any literal dots or backslashes
1122
+ * must be escaped.
1123
+ *
1124
+ * return value: Returns 0 on success, -1 on error.
1125
+ *
1126
+ */
1127
+
1128
+ int DNSServiceConstructFullName
1129
+ (
1130
+ char *fullName,
1131
+ const char *service, /* may be NULL */
1132
+ const char *regtype,
1133
+ const char *domain
1134
+ );
1135
+
1136
+
1137
+ /*********************************************************************************************
1138
+ *
1139
+ * TXT Record Construction Functions
1140
+ *
1141
+ *********************************************************************************************/
1142
+
1143
+ /*
1144
+ * A typical calling sequence for TXT record construction is something like:
1145
+ *
1146
+ * Client allocates storage for TXTRecord data (e.g. declare buffer on the stack)
1147
+ * TXTRecordCreate();
1148
+ * TXTRecordSetValue();
1149
+ * TXTRecordSetValue();
1150
+ * TXTRecordSetValue();
1151
+ * ...
1152
+ * DNSServiceRegister( ... TXTRecordGetLength(), TXTRecordGetBytesPtr() ... );
1153
+ * TXTRecordDeallocate();
1154
+ * Explicitly deallocate storage for TXTRecord data (if not allocated on the stack)
1155
+ */
1156
+
1157
+
1158
+ /* TXTRecordRef
1159
+ *
1160
+ * Opaque internal data type.
1161
+ * Note: Represents a DNS-SD TXT record.
1162
+ */
1163
+
1164
+ typedef struct _TXTRecordRef_t { char private[16]; } TXTRecordRef;
1165
+
1166
+
1167
+ /* TXTRecordCreate()
1168
+ *
1169
+ * Creates a new empty TXTRecordRef referencing the specified storage.
1170
+ *
1171
+ * If the buffer parameter is NULL, or the specified storage size is not
1172
+ * large enough to hold a key subsequently added using TXTRecordSetValue(),
1173
+ * then additional memory will be added as needed using malloc().
1174
+ *
1175
+ * On some platforms, when memory is low, malloc() may fail. In this
1176
+ * case, TXTRecordSetValue() will return kDNSServiceErr_NoMemory, and this
1177
+ * error condition will need to be handled as appropriate by the caller.
1178
+ *
1179
+ * You can avoid the need to handle this error condition if you ensure
1180
+ * that the storage you initially provide is large enough to hold all
1181
+ * the key/value pairs that are to be added to the record.
1182
+ * The caller can precompute the exact length required for all of the
1183
+ * key/value pairs to be added, or simply provide a fixed-sized buffer
1184
+ * known in advance to be large enough.
1185
+ * A no-value (key-only) key requires (1 + key length) bytes.
1186
+ * A key with empty value requires (1 + key length + 1) bytes.
1187
+ * A key with non-empty value requires (1 + key length + 1 + value length).
1188
+ * For most applications, DNS-SD TXT records are generally
1189
+ * less than 100 bytes, so in most cases a simple fixed-sized
1190
+ * 256-byte buffer will be more than sufficient.
1191
+ * Recommended size limits for DNS-SD TXT Records are discussed in
1192
+ * <http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt>
1193
+ *
1194
+ * txtRecord: A pointer to an uninitialized TXTRecordRef.
1195
+ *
1196
+ * bufferLen: The size of the storage provided in the "buffer" parameter.
1197
+ *
1198
+ * buffer: The storage used to hold the TXTRecord data.
1199
+ * This storage must remain valid for as long as
1200
+ * the TXTRecordRef.
1201
+ */
1202
+
1203
+ void TXTRecordCreate
1204
+ (
1205
+ TXTRecordRef *txtRecord,
1206
+ uint16_t bufferLen,
1207
+ void *buffer
1208
+ );
1209
+
1210
+
1211
+ /* TXTRecordDeallocate()
1212
+ *
1213
+ * Releases any resources allocated in the course of preparing a TXT Record
1214
+ * using TXTRecordCreate()/TXTRecordSetValue()/TXTRecordRemoveValue().
1215
+ * Ownership of the buffer provided in TXTRecordCreate() returns to the client.
1216
+ *
1217
+ * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate().
1218
+ *
1219
+ */
1220
+
1221
+ void TXTRecordDeallocate
1222
+ (
1223
+ TXTRecordRef *txtRecord
1224
+ );
1225
+
1226
+
1227
+ /* TXTRecordSetValue()
1228
+ *
1229
+ * Adds a key (optionally with value) to a TXTRecordRef. If the "key" already
1230
+ * exists in the TXTRecordRef, then the current value will be replaced with
1231
+ * the new value.
1232
+ * Keys may exist in four states with respect to a given TXT record:
1233
+ * - Absent (key does not appear at all)
1234
+ * - Present with no value ("key" appears alone)
1235
+ * - Present with empty value ("key=" appears in TXT record)
1236
+ * - Present with non-empty value ("key=value" appears in TXT record)
1237
+ * For more details refer to "Data Syntax for DNS-SD TXT Records" in
1238
+ * <http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt>
1239
+ *
1240
+ * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate().
1241
+ *
1242
+ * key: A null-terminated string which only contains printable ASCII
1243
+ * values (0x20-0x7E), excluding '=' (0x3D). Keys should be
1244
+ * 14 characters or less (not counting the terminating null).
1245
+ *
1246
+ * valueSize: The size of the value.
1247
+ *
1248
+ * value: Any binary value. For values that represent
1249
+ * textual data, UTF-8 is STRONGLY recommended.
1250
+ * For values that represent textual data, valueSize
1251
+ * should NOT include the terminating null (if any)
1252
+ * at the end of the string.
1253
+ * If NULL, then "key" will be added with no value.
1254
+ * If non-NULL but valueSize is zero, then "key=" will be
1255
+ * added with empty value.
1256
+ *
1257
+ * return value: Returns kDNSServiceErr_NoError on success.
1258
+ * Returns kDNSServiceErr_Invalid if the "key" string contains
1259
+ * illegal characters.
1260
+ * Returns kDNSServiceErr_NoMemory if adding this key would
1261
+ * exceed the available storage.
1262
+ */
1263
+
1264
+ DNSServiceErrorType TXTRecordSetValue
1265
+ (
1266
+ TXTRecordRef *txtRecord,
1267
+ const char *key,
1268
+ uint8_t valueSize, /* may be zero */
1269
+ const void *value /* may be NULL */
1270
+ );
1271
+
1272
+
1273
+ /* TXTRecordRemoveValue()
1274
+ *
1275
+ * Removes a key from a TXTRecordRef. The "key" must be an
1276
+ * ASCII string which exists in the TXTRecordRef.
1277
+ *
1278
+ * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate().
1279
+ *
1280
+ * key: A key name which exists in the TXTRecordRef.
1281
+ *
1282
+ * return value: Returns kDNSServiceErr_NoError on success.
1283
+ * Returns kDNSServiceErr_NoSuchKey if the "key" does not
1284
+ * exist in the TXTRecordRef.
1285
+ *
1286
+ */
1287
+
1288
+ DNSServiceErrorType TXTRecordRemoveValue
1289
+ (
1290
+ TXTRecordRef *txtRecord,
1291
+ const char *key
1292
+ );
1293
+
1294
+
1295
+ /* TXTRecordGetLength()
1296
+ *
1297
+ * Allows you to determine the length of the raw bytes within a TXTRecordRef.
1298
+ *
1299
+ * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate().
1300
+ *
1301
+ * return value: Returns the size of the raw bytes inside a TXTRecordRef
1302
+ * which you can pass directly to DNSServiceRegister() or
1303
+ * to DNSServiceUpdateRecord().
1304
+ * Returns 0 if the TXTRecordRef is empty.
1305
+ *
1306
+ */
1307
+
1308
+ uint16_t TXTRecordGetLength
1309
+ (
1310
+ const TXTRecordRef *txtRecord
1311
+ );
1312
+
1313
+
1314
+ /* TXTRecordGetBytesPtr()
1315
+ *
1316
+ * Allows you to retrieve a pointer to the raw bytes within a TXTRecordRef.
1317
+ *
1318
+ * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate().
1319
+ *
1320
+ * return value: Returns a pointer to the raw bytes inside the TXTRecordRef
1321
+ * which you can pass directly to DNSServiceRegister() or
1322
+ * to DNSServiceUpdateRecord().
1323
+ *
1324
+ */
1325
+
1326
+ const void * TXTRecordGetBytesPtr
1327
+ (
1328
+ const TXTRecordRef *txtRecord
1329
+ );
1330
+
1331
+
1332
+ /*********************************************************************************************
1333
+ *
1334
+ * TXT Record Parsing Functions
1335
+ *
1336
+ *********************************************************************************************/
1337
+
1338
+ /*
1339
+ * A typical calling sequence for TXT record parsing is something like:
1340
+ *
1341
+ * Receive TXT record data in DNSServiceResolve() callback
1342
+ * if (TXTRecordContainsKey(txtLen, txtRecord, "key")) then do something
1343
+ * val1ptr = TXTRecordGetValuePtr(txtLen, txtRecord, "key1", &len1);
1344
+ * val2ptr = TXTRecordGetValuePtr(txtLen, txtRecord, "key2", &len2);
1345
+ * ...
1346
+ * bcopy(val1ptr, myval1, len1);
1347
+ * bcopy(val2ptr, myval2, len2);
1348
+ * ...
1349
+ * return;
1350
+ *
1351
+ * If you wish to retain the values after return from the DNSServiceResolve()
1352
+ * callback, then you need to copy the data to your own storage using bcopy()
1353
+ * or similar, as shown in the example above.
1354
+ *
1355
+ * If for some reason you need to parse a TXT record you built yourself
1356
+ * using the TXT record construction functions above, then you can do
1357
+ * that using TXTRecordGetLength and TXTRecordGetBytesPtr calls:
1358
+ * TXTRecordGetValue(TXTRecordGetLength(x), TXTRecordGetBytesPtr(x), key, &len);
1359
+ *
1360
+ * Most applications only fetch keys they know about from a TXT record and
1361
+ * ignore the rest.
1362
+ * However, some debugging tools wish to fetch and display all keys.
1363
+ * To do that, use the TXTRecordGetCount() and TXTRecordGetItemAtIndex() calls.
1364
+ */
1365
+
1366
+ /* TXTRecordContainsKey()
1367
+ *
1368
+ * Allows you to determine if a given TXT Record contains a specified key.
1369
+ *
1370
+ * txtLen: The size of the received TXT Record.
1371
+ *
1372
+ * txtRecord: Pointer to the received TXT Record bytes.
1373
+ *
1374
+ * key: A null-terminated ASCII string containing the key name.
1375
+ *
1376
+ * return value: Returns 1 if the TXT Record contains the specified key.
1377
+ * Otherwise, it returns 0.
1378
+ *
1379
+ */
1380
+
1381
+ int TXTRecordContainsKey
1382
+ (
1383
+ uint16_t txtLen,
1384
+ const void *txtRecord,
1385
+ const char *key
1386
+ );
1387
+
1388
+
1389
+ /* TXTRecordGetValuePtr()
1390
+ *
1391
+ * Allows you to retrieve the value for a given key from a TXT Record.
1392
+ *
1393
+ * txtLen: The size of the received TXT Record
1394
+ *
1395
+ * txtRecord: Pointer to the received TXT Record bytes.
1396
+ *
1397
+ * key: A null-terminated ASCII string containing the key name.
1398
+ *
1399
+ * valueLen: On output, will be set to the size of the "value" data.
1400
+ *
1401
+ * return value: Returns NULL if the key does not exist in this TXT record,
1402
+ * or exists with no value (to differentiate between
1403
+ * these two cases use TXTRecordContainsKey()).
1404
+ * Returns pointer to location within TXT Record bytes
1405
+ * if the key exists with empty or non-empty value.
1406
+ * For empty value, valueLen will be zero.
1407
+ * For non-empty value, valueLen will be length of value data.
1408
+ */
1409
+
1410
+ const void * TXTRecordGetValuePtr
1411
+ (
1412
+ uint16_t txtLen,
1413
+ const void *txtRecord,
1414
+ const char *key,
1415
+ uint8_t *valueLen
1416
+ );
1417
+
1418
+
1419
+ /* TXTRecordGetCount()
1420
+ *
1421
+ * Returns the number of keys stored in the TXT Record. The count
1422
+ * can be used with TXTRecordGetItemAtIndex() to iterate through the keys.
1423
+ *
1424
+ * txtLen: The size of the received TXT Record.
1425
+ *
1426
+ * txtRecord: Pointer to the received TXT Record bytes.
1427
+ *
1428
+ * return value: Returns the total number of keys in the TXT Record.
1429
+ *
1430
+ */
1431
+
1432
+ uint16_t TXTRecordGetCount
1433
+ (
1434
+ uint16_t txtLen,
1435
+ const void *txtRecord
1436
+ );
1437
+
1438
+
1439
+ /* TXTRecordGetItemAtIndex()
1440
+ *
1441
+ * Allows you to retrieve a key name and value pointer, given an index into
1442
+ * a TXT Record. Legal index values range from zero to TXTRecordGetCount()-1.
1443
+ * It's also possible to iterate through keys in a TXT record by simply
1444
+ * calling TXTRecordGetItemAtIndex() repeatedly, beginning with index zero
1445
+ * and increasing until TXTRecordGetItemAtIndex() returns kDNSServiceErr_Invalid.
1446
+ *
1447
+ * On return:
1448
+ * For keys with no value, *value is set to NULL and *valueLen is zero.
1449
+ * For keys with empty value, *value is non-NULL and *valueLen is zero.
1450
+ * For keys with non-empty value, *value is non-NULL and *valueLen is non-zero.
1451
+ *
1452
+ * txtLen: The size of the received TXT Record.
1453
+ *
1454
+ * txtRecord: Pointer to the received TXT Record bytes.
1455
+ *
1456
+ * index: An index into the TXT Record.
1457
+ *
1458
+ * keyBufLen: The size of the string buffer being supplied.
1459
+ *
1460
+ * key: A string buffer used to store the key name.
1461
+ * On return, the buffer contains a null-terminated C string
1462
+ * giving the key name. DNS-SD TXT keys are usually
1463
+ * 14 characters or less. To hold the maximum possible
1464
+ * key name, the buffer should be 256 bytes long.
1465
+ *
1466
+ * valueLen: On output, will be set to the size of the "value" data.
1467
+ *
1468
+ * value: On output, *value is set to point to location within TXT
1469
+ * Record bytes that holds the value data.
1470
+ *
1471
+ * return value: Returns kDNSServiceErr_NoError on success.
1472
+ * Returns kDNSServiceErr_NoMemory if keyBufLen is too short.
1473
+ * Returns kDNSServiceErr_Invalid if index is greater than
1474
+ * TXTRecordGetCount()-1.
1475
+ */
1476
+
1477
+ DNSServiceErrorType TXTRecordGetItemAtIndex
1478
+ (
1479
+ uint16_t txtLen,
1480
+ const void *txtRecord,
1481
+ uint16_t index,
1482
+ uint16_t keyBufLen,
1483
+ char *key,
1484
+ uint8_t *valueLen,
1485
+ const void **value
1486
+ );
1487
+
1488
+
1489
+ #ifdef __cplusplus
1490
+ }
1491
+ #endif
1492
+
1493
+ #endif /* _DNS_SD_H */