mdns.subproj/dns_sd.h

   1 /*
   2  * Copyright (c) 2003 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
  26 #ifndef _DNS_SD_H
  27 #define _DNS_SD_H
  28
  29 #include <sys/types.h>
  30 #include <sys/socket.h>
  31 #include <stdint.h>
  32 #include <netinet/in.h>
  33
  34
  35 /* DNSServiceRef, DNSRecordRef
  36  *
  37  * Opaque internal data types.
  38  * Note: client is responsible for serializing access to these structures if
  39  * they are shared between concurrent threads.
  40  */
  41
  42 typedef struct _DNSServiceRef_t *DNSServiceRef;
  43 typedef struct _DNSRecordRef_t *DNSRecordRef;
  44
  45 /* General flags used in functions defined below */
  46 enum
  47     {
  48     kDNSServiceFlagsMoreComing          = 1,
  49     kDNSServiceFlagsFinished            = 0,  /* i.e. bit not set */
  50     /* MoreComing indicates to a Browse callback that another result is
  51      * queued.  Applications should not update their UI to display browse
  52      * results when the MoreComing flag is set, instead deferring the update
  53      * until the callback's flag is Finished. */
  54
  55     kDNSServiceFlagsAdd                 = 2,
  56     kDNSServiceFlagsDefault             = 4,
  57     kDNSServiceFlagsRemove              = 0,  /* i.e. bit not set */
  58     /* Flags for domain enumeration and browse reply callbacks.
  59      * "Default" applies only to enumeration and is only valid in
  60      * conjuction with "Add"
  61      */
  62
  63     kDNSServiceFlagsNoAutoRename        = 8,
  64     kDNSServiceFlagsAutoRename          = 0,  /* i.e. bit not set */
  65     /* Flag for specifying renaming behavior on name conflict when registering
  66      * non-shared records. NoAutorename is only valid if a name is explicitly
  67      * specified when registering a service (ie the default name is not used.)
  68      */
  69
  70
  71     kDNSServiceFlagsShared              = 16,
  72     kDNSServiceFlagsUnique              = 32,
  73     /* Flag for registering individual records on a connected
  74      * DNSServiceRef.  Shared indicates that there may be multiple records
  75      * with this name on the network (e.g. PTR records).  Unique indicates that the
  76      * record's name is to be unique on the network (e.g. SRV records).
  77      */
  78
  79     kDNSServiceFlagsBrowseDomains       = 64,
  80     kDNSServiceFlagsRegistrationDomains = 128
  81     /* Flags for specifying domain enumeration type in DNSServiceEnumerateDomains.
  82      * BrowseDomains enumerates domains recommended for browsing, RegistrationDomains
  83      * enumerates domains recommended for registration.
  84      */
  85     };
  86
  87 /* possible error code values */
  88 enum
  89     {
  90     kDNSServiceErr_NoError             = 0,
  91     kDNSServiceErr_Unknown             = -65537,       /* 0xFFFE FFFF */
  92     kDNSServiceErr_NoSuchName          = -65538,
  93     kDNSServiceErr_NoMemory            = -65539,
  94     kDNSServiceErr_BadParam            = -65540,
  95     kDNSServiceErr_BadReference        = -65541,
  96     kDNSServiceErr_BadState            = -65542,
  97     kDNSServiceErr_BadFlags            = -65543,
  98     kDNSServiceErr_Unsupported         = -65544,
  99     kDNSServiceErr_NotInitialized      = -65545,
 100     kDNSServiceErr_AlreadyRegistered   = -65547,
 101     kDNSServiceErr_NameConflict        = -65548,
 102     kDNSServiceErr_Invalid             = -65549,
 103     kDNSServiceErr_Incompatible        = -65551,        /* client library incompatible with daemon */
 104     kDNSServiceErr_BadinterfaceIndex   = -65552
 105     /* mDNS Error codes are in the range
 106      * FFFE FF00 (-65792) to FFFE FFFF (-65537) */
 107     };
 108
 109
 110 /* Maximum length, in bytes, of a domain name represented as an escaped C-String */
 111 #define kDNSServiceMaxDomainName 1005
 112
 113
 114 typedef uint32_t DNSServiceFlags;
 115 typedef int32_t DNSServiceErrorType;
 116
 117
 118 /*********************************************************************************************
 119  *
 120  * Unix Domain Socket access, DNSServiceRef deallocation, and data processing functions
 121  *
 122  *********************************************************************************************/
 123
 124
 125 /* DNSServiceRefSockFD()
 126  *
 127  * Access underlying Unix domain socket for an initialized DNSServiceRef.
 128  * The DNS Service Discovery implmementation uses this socket to communicate between
 129  * the client and the mDNSResponder daemon.  The application MUST NOT directly read from
 130  * or write to this socket.  Access to the socket is provided so that it can be used as a
 131  * run loop source, or in a select() loop: when data is available for reading on the socket,
 132  * DNSServiceProcessResult() should be called, which will extract the daemon's reply from
 133  * the socket, and pass it to the appropriate application callback.  By using a run loop or
 134  * select(), results from the daemon can be processed asynchronously.  Without using these
 135  * constructs, DNSServiceProcessResult() will block until the response from the daemon arrives.
 136  * The client is responsible for ensuring that the data on the socket is processed in a timely
 137  * fashion - the daemon may terminate its connection with a client that does not clear its
 138  * socket buffer.
 139  *
 140  * sdRef:            A DNSServiceRef initialized by any of the DNSService calls.
 141  *
 142  * return value:    The DNSServiceRef's underlying socket descriptor, or -1 on
 143  *                  error.
 144  */
 145
 146 int DNSServiceRefSockFD(DNSServiceRef sdRef);
 147
 148 /* DNSServiceProcessResult()
 149  *
 150  * Read a reply from the daemon, calling the appropriate application callback.  This call will
 151  * block until the daemon's response is received.  Use DNSServiceRefSockFD() in
 152  * conjunction with a run loop or select() to determine the presence of a response from the
 153  * server before calling this function to process the reply without blocking.  Call this function
 154  * at any point if it is acceptable to block until the daemon's response arrives.  Note that the
 155  * client is responsible for ensuring that DNSServiceProcessResult() is called whenever there is
 156  * a reply from the daemon - the daemon may terminate its connection with a client that does not
 157  * process the daemon's responses.
 158  *
 159  * sdRef:           A DNSServiceRef initialized by any of the DNSService calls
 160  *                  that take a callback parameter.
 161  *
 162  * return value:    Returns kDNSServiceErr_NoError on success, otherwise returns
 163  *                  an error code indicating the specific failure that occurred.
 164  */
 165
 166 DNSServiceErrorType DNSServiceProcessResult(DNSServiceRef sdRef);
 167
 168 /* DNSServiceRefDeallocate()
 169  *
 170  * Terminate a connection with the daemon and free memory associated with the DNSServiceRef.
 171  * Any services or records registered with this DNSServiceRef will be deregistered. Any
 172  * Browse, Resolve, or Query operations called with this reference will be terminated.
 173  *
 174  * Note: If the reference's underlying socket is used in a run loop or select() call, it should
 175  * be removed BEFORE DNSServiceRefDeallocate() is called, as this function closes the reference's
 176  * socket.
 177  *
 178  * Note: If the reference was initialized with DNSServiceCreateConnection(), any DNSRecordRefs
 179  * created via this reference will be invalidated by this call - the resource records are
 180  * deregistered, and their DNSRecordRefs may not be used in subsequent functions.  Similarly,
 181  * if the reference was initialized with DNSServiceRegister, and an extra resource record was
 182  * added to the service via DNSServiceAddRecord(), the DNSRecordRef created by the Add() call
 183  * is invalidated when this function is called - the DNSRecordRef may not be used in subsequent
 184  * functions.
 185  *
 186  * Note: This call is to be used only with the DNSServiceRef defined by this API.  It is
 187  * not compatible with dns_service_discovery_ref objects defined in the legacy Mach-based
 188  * DNSServiceDiscovery.h API.
 189  *
 190  * sdRef:           A DNSServiceRef initialized by any of the DNSService calls.
 191  *
 192  */
 193
 194 void DNSServiceRefDeallocate(DNSServiceRef sdRef);
 195
 196
 197 /*********************************************************************************************
 198  *
 199  * Domain Enumeration
 200  *
 201  *********************************************************************************************/
 202
 203 /* DNSServiceEnumerateDomains()
 204  *
 205  * Asynchronously enumerate domains available for browsing and registration.
 206  * Currently, the only domain returned is "local.", but other domains will be returned in future.
 207  *
 208  * The enumeration MUST be cancelled via DNSServiceRefDeallocate() when no more domains
 209  * are to be found.
 210  *
 211  *
 212  * DNSServiceDomainEnumReply Callback Parameters:
 213  *
 214  * sdRef:           The DNSServiceRef initialized by DNSServiceEnumerateDomains().
 215  *
 216  * flags:           Possible values are:
 217  *                  1 (MoreComing)
 218  *                  2 (Add/Remove)
 219  *                  4 (Add Default)
 220  *
 221  * interfaceIndex:  Specifies the interface on which the domain exists.  (The index for a given
 222  *                  interface is determined via the if_nametoindex() family of calls.)
 223  *
 224  * errorCode:       Will be kDNSServiceErr_NoError (0) on success, otherwise indicates
 225  *                  the failure that occurred (other parameters are undefined if errorCode is nonzero).
 226  *
 227  * replyDomain:     The name of the domain.
 228  *
 229  * context:         The context pointer passed to DNSServiceEnumerateDomains.
 230  *
 231  */
 232
 233 typedef void (*DNSServiceDomainEnumReply)
 234     (
 235     DNSServiceRef                       sdRef,
 236     DNSServiceFlags                     flags,
 237     uint32_t                            interfaceIndex,
 238     DNSServiceErrorType                 errorCode,
 239     const char                          *replyDomain,
 240     void                                *context
 241     );
 242
 243 /* DNSServiceEnumerateDomains() Parameters:
 244  *
 245  *
 246  * sdRef:           A pointer to an uninitialized sdRef.  May be passed to
 247  *                  DNSServiceRefDeallocate() to cancel the enumeration.
 248  *
 249  * flags:           Possible values are:
 250  *                  0 (BrowseDomains) to enumerate domains recommended for browsing.
 251  *                  32 (RegistrationDomains) to enumerate domains recommended for registration.
 252  *
 253  * interfaceIndex:  If non-zero, specifies the interface on which to look for domains.
 254  *                  (the index for a given interface is determined via the if_nametoindex()
 255  *                  family of calls.)  Most applications will pass 0 to enumerate domains on
 256  *                  all interfaces.
 257  *
 258  * callBack:        The function to be called when a domain is found or the call asynchronously
 259  *                  fails.
 260  *
 261  * context:         An application context pointer which is passed to the callback function
 262  *                  (may be NULL).
 263  *
 264  * return value:    Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
 265  *                  errors are delivered to the callback), otherwise returns an error code indicating
 266  *                  the error that occurred (the callback is not invoked and the DNSServiceRef
 267  *                  is not initialized.)
 268  */
 269
 270 DNSServiceErrorType DNSServiceEnumerateDomains
 271     (
 272     DNSServiceRef                       *sdRef,
 273     DNSServiceFlags                     flags,
 274     uint32_t                            interfaceIndex,
 275     DNSServiceDomainEnumReply           callBack,
 276     void                                *context  /* may be NULL */
 277     );
 278
 279 /*********************************************************************************************
 280  *
 281  *  Service Registration
 282  *
 283  *********************************************************************************************/
 284
 285 /* Register a service that is discovered via Browse() and Resolve() calls.
 286  *
 287  *
 288  * DNSServiceRegisterReply() Callback Parameters:
 289  *
 290  * sdRef:           The DNSServiceRef initialized by DNSServiceRegister().
 291  *
 292  * flags:           Currently unused, reserved for future use.
 293  *
 294  * errorCode:       Will be kDNSServiceErr_NoError on success, otherwise will
 295  *                  indicate the failure that occurred (including name conflicts, if the
 296  *                  kDNSServiceFlagsNoAutoRenameOnConflict flag was passed to the
 297  *                  callout.)  Other parameters are undefined if errorCode is nonzero.
 298  *
 299  * name:            The service name registered (if the application did not specify a name in
 300  *                  DNSServiceRegister(), this indicates what name was automatically chosen).
 301  *
 302  * regtype:         The type of service registered, as it was passed to the callout.
 303  *
 304  * domain:          The domain on which the service was registered (if the application did not
 305  *                  specify a domain in DNSServiceRegister(), this indicates the default domain
 306  *                  on which the service was registered).
 307  *
 308  * context:         The context pointer that was passed to the callout.
 309  *
 310  */
 311
 312 typedef void (*DNSServiceRegisterReply)
 313     (
 314     DNSServiceRef                       sdRef,
 315     DNSServiceFlags                     flags,
 316     DNSServiceErrorType                 errorCode,
 317     const char                          *name,
 318     const char                          *regtype,
 319     const char                          *domain,
 320     void                                *context
 321     );
 322
 323 /* DNSServiceRegister()  Parameters:
 324  *
 325  * sdRef:           A pointer to an uninitialized sdRef.  If this call succeeds, the reference
 326  *                  may be passed to
 327  *                  DNSServiceRefDeallocate() to deregister the service.
 328  *
 329  * interfaceIndex:  If non-zero, specifies the interface on which to register the service
 330  *                  (the index for a given interface is determined via the if_nametoindex()
 331  *                  family of calls.)  Most applications will pass 0 to register on all
 332  *                  available interfaces.  Pass -1 to register a service only on the local
 333  *                  machine (service will not be visible to remote hosts.)
 334  *
 335  * flags:           Indicates the renaming behavior on name conflict (most applications
 336  *                  will pass 0).  See flag definitions above for details.
 337  *
 338  * name:            If non-NULL, specifies the service name to be registered.
 339  *                  Most applications will not specify a name, in which case the
 340  *                  computer name is used (this name is communicated to the client via
 341  *                  the callback).
 342  *
 343  * regtype:         The service type followed by the protocol, separated by a dot
 344  *                  (e.g. "_ftp._tcp").  The transport protocol must be "_tcp" or "_udp".
 345  *
 346  * domain:          If non-NULL, specifies the domain on which to advertise the service.
 347  *                  Most applications will not specify a domain, instead automatically
 348  *                  registering in the default domain(s).
 349  *
 350  * host:            If non-NULL, specifies the SRV target host name.  Most applications
 351  *                  will not specify a host, instead automatically using the machine's
 352  *                  default host name(s).  Note that specifying a non-NULL host does NOT
 353  *                  create an address record for that host - the application is responsible
 354  *                  for ensuring that the appropriate address record exists, or creating it
 355  *                  via DNSServiceRegisterRecord().
 356  *
 357  * port:            The port on which the service accepts connections.  Pass 0 for a
 358  *                  "placeholder" service (i.e. a service that will not be discovered by
 359  *                  browsing, but will cause a name conflict if another client tries to
 360  *                  register that same name.)  Most clients will not use placeholder services.
 361  *
 362  * txtLen:          The length of the txtRecord, in bytes.  Must be zero if the txtRecord is NULL.
 363  *
 364  * txtRecord:       The txt record rdata.  May be NULL.  Note that a non-NULL txtRecord
 365  *                  MUST be a properly formatted DNS TXT record, i.e. <length byte> <data>
 366  *                  <length byte> <data> ...
 367  *
 368  * callBack:        The function to be called when the registration completes or asynchronously
 369  *                  fails.  The client MAY pass NULL for the callback -  The client will NOT be notified
 370  *                  of the default values picked on its behalf, and the client will NOT be notified of any
 371  *                  asynchronous errors (e.g. out of memory errors, etc.) that may prevent the registration
 372  *                  of the service.  The client may NOT pass the NoAutoRename flag if the callback is NULL.
 373  *                  The client may still deregister the service at any time via DNSServiceRefDeallocate().
 374  *
 375  * context:         An application context pointer which is passed to the callback function
 376  *                  (may be NULL).
 377  *
 378  * return value:    Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
 379  *                  errors are delivered to the callback), otherwise returns an error code indicating
 380  *                  the error that occurred (the callback is never invoked and the DNSServiceRef
 381  *                  is not initialized.)
 382  *
 383  */
 384
 385 DNSServiceErrorType DNSServiceRegister
 386     (
 387     DNSServiceRef                       *sdRef,
 388     DNSServiceFlags                     flags,
 389     uint32_t                            interfaceIndex,
 390     const char                          *name,         /* may be NULL */
 391     const char                          *regtype,
 392     const char                          *domain,       /* may be NULL */
 393     const char                          *host,         /* may be NULL */
 394     uint16_t                            port,
 395     uint16_t                            txtLen,
 396     const void                          *txtRecord,    /* may be NULL */
 397     DNSServiceRegisterReply             callBack,      /* may be NULL */
 398     void                                *context       /* may be NULL */
 399     );
 400
 401 /* DNSServiceAddRecord()
 402  *
 403  * Add a record to a registered service.  The name of the record will be the same as the
 404  * registered service's name.
 405  * The record can later be updated or deregistered by passing the RecordRef initialized
 406  * by this function to DNSServiceUpdateRecord() or DNSServiceRemoveRecord().
 407  *
 408  *
 409  * Parameters;
 410  *
 411  * sdRef:           A DNSServiceRef initialized by DNSServiceRegister().
 412  *
 413  * RecordRef:       A pointer to an uninitialized DNSRecordRef.  Upon succesfull completion of this
 414  *                  call, this ref may be passed to DNSServiceUpdateRecord() or DNSServiceRemoveRecord().
 415  *                  If the above DNSServiceRef is passed to DNSServiceRefDeallocate(), RecordRef is also
 416  *                  invalidated and may not be used further.
 417  *
 418  * flags:           Currently ignored, reserved for future use.
 419  *
 420  * rrtype:          The type of the record (e.g. TXT, SRV, etc), as defined in nameser.h.
 421  *
 422  * rdlen:           The length, in bytes, of the rdata.
 423  *
 424  * rdata:           The raw rdata to be contained in the added resource record.
 425  *
 426  * ttl:             The time to live of the resource record, in seconds.
 427  *
 428  * return value:    Returns kDNSServiceErr_NoError on success, otherwise returns an
 429  *                  error code indicating the error that occurred (the RecordRef is not initialized).
 430  */
 431
 432 DNSServiceErrorType DNSServiceAddRecord
 433     (
 434     DNSServiceRef                       sdRef,
 435     DNSRecordRef                        *RecordRef,
 436     DNSServiceFlags                     flags,
 437     uint16_t                            rrtype,
 438     uint16_t                            rdlen,
 439     const void                          *rdata,
 440     uint32_t                            ttl
 441     );
 442
 443 /* DNSServiceUpdateRecord
 444  *
 445  * Update a registered resource record.  The record must either be:
 446  *   - The primary txt record of a service registered via DNSServiceRegister()
 447  *   - A record added to a registered service via DNSServiceAddRecord()
 448  *   - An individual record registered by DNSServiceRegisterRecord()
 449  *
 450  *
 451  * Parameters:
 452  *
 453  * sdRef:           A DNSServiceRef that was initialized by DNSServiceRegister()
 454  *                  or DNSServiceCreateConnection().
 455  *
 456  * RecordRef:       A DNSRecordRef initialized by DNSServiceAddRecord, or NULL to update the
 457  *                  service's primary txt record.
 458  *
 459  * flags:           Currently ignored, reserved for future use.
 460  *
 461  * rdlen:           The length, in bytes, of the new rdata.
 462  *
 463  * rdata:           The new rdata to be contained in the updated resource record.
 464  *
 465  * ttl:             The time to live of the updated resource record, in seconds.
 466  *
 467  * return value:    Returns kDNSServiceErr_NoError on success, otherwise returns an
 468  *                  error code indicating the error that occurred.
 469  */
 470
 471 DNSServiceErrorType DNSServiceUpdateRecord
 472     (
 473     DNSServiceRef                       sdRef,
 474     DNSRecordRef                        RecordRef,     /* may be NULL */
 475     DNSServiceFlags                     flags,
 476     uint16_t                            rdlen,
 477     const void                          *rdata,
 478     uint32_t                            ttl
 479     );
 480
 481 /* DNSServiceRemoveRecord
 482  *
 483  * Remove a record previously added to a service record set via DNSServiceAddRecord(), or deregister
 484  * an record registered individually via DNSServiceRegisterRecord().
 485  *
 486  * Parameters:
 487  *
 488  * sdRef:           A DNSServiceRef initialized by DNSServiceRegister() (if the
 489  *                  record being removed was registered via DNSServiceAddRecord()) or by
 490  *                  DNSServiceCreateConnection() (if the record being removed was registered via
 491  *                  DNSServiceRegisterRecord()).
 492  *
 493  * recordRef:       A DNSRecordRef initialized by a successful call to DNSServiceAddRecord()
 494  *                  or DNSServiceRegisterRecord().
 495  *
 496  * flags:           Currently ignored, reserved for future use.
 497  *
 498  * return value:    Returns kDNSServiceErr_NoError on success, otherwise returns an
 499  *                  error code indicating the error that occurred.
 500  */
 501
 502 DNSServiceErrorType DNSServiceRemoveRecord
 503     (
 504     DNSServiceRef                 sdRef,
 505     DNSRecordRef                  RecordRef,
 506     DNSServiceFlags               flags
 507     );
 508
 509
 510 /*********************************************************************************************
 511  *
 512  *  Service Discovery
 513  *
 514  *********************************************************************************************/
 515
 516
 517 /* Browse for instances of a service.
 518  *
 519  *
 520  * DNSServiceBrowseReply() Parameters:
 521  *
 522  * sdRef:           The DNSServiceRef initialized by DNSServiceBrowse().
 523  *
 524  * flags:           Possible values are MoreComing and Add/Remove.  See flag definitions
 525  *                  for details.
 526  *
 527  * interfaceIndex:  The interface on which the service is advertised.  This index should
 528  *                  be passed to DNSServiceResolve() when resolving the service.
 529  *
 530  * errorCode:       Will be kDNSServiceErr_NoError (0) on success, otherwise will
 531  *                  indicate the failure that occurred.  Other parameters are undefined if
 532  *                  the errorCode is nonzero.
 533  *
 534  * serviceName:     The service name discovered.
 535  *
 536  * regtype:         The service type, as passed in to DNSServiceBrowse().
 537  *
 538  * domain:          The domain on which the service was discovered (if the application did not
 539  *                  specify a domain in DNSServicBrowse(), this indicates the domain on which the
 540  *                  service was discovered.)
 541  *
 542  * context:         The context pointer that was passed to the callout.
 543  *
 544  */
 545
 546 typedef void (*DNSServiceBrowseReply)
 547     (
 548     DNSServiceRef                       sdRef,
 549     DNSServiceFlags                     flags,
 550     uint32_t                            interfaceIndex,
 551     DNSServiceErrorType                 errorCode,
 552     const char                          *serviceName,
 553     const char                          *regtype,
 554     const char                          *replyDomain,
 555     void                                *context
 556     );
 557
 558 /* DNSServiceBrowse() Parameters:
 559  *
 560  * sdRef:           A pointer to an uninitialized sdRef.  May be passed to
 561  *                  DNSServiceRefDeallocate() to terminate the browse.
 562  *
 563  * flags:           Currently ignored, reserved for future use.
 564  *
 565  * interfaceIndex:  If non-zero, specifies the interface on which to browse for services
 566  *                  (the index for a given interface is determined via the if_nametoindex()
 567  *                  family of calls.)  Most applications will pass 0 to browse on all available
 568  *                  interfaces.  Pass -1 to only browse for services provided on the local host.
 569  *
 570  * regtype:         The service type being browsed for followed by the protocol, separated by a
 571  *                  dot (e.g. "_ftp._tcp").  The transport protocol must be "_tcp" or "_udp".
 572  *
 573  * domain:          If non-NULL, specifies the domain on which to browse for services.
 574  *                  Most applications will not specify a domain, instead browsing on the
 575  *                  default domain(s).
 576  *
 577  * callBack:        The function to be called when an instance of the service being browsed for
 578  *                  is found, or if the call asynchronously fails.
 579  *
 580  * context:         An application context pointer which is passed to the callback function
 581  *                  (may be NULL).
 582  *
 583  * return value:    Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
 584  *                  errors are delivered to the callback), otherwise returns an error code indicating
 585  *                  the error that occurred (the callback is not invoked and the DNSServiceRef
 586  *                  is not initialized.)
 587  */
 588
 589 DNSServiceErrorType DNSServiceBrowse
 590     (
 591     DNSServiceRef                       *sdRef,
 592     DNSServiceFlags                     flags,
 593     uint32_t                            interfaceIndex,
 594     const char                          *regtype,
 595     const char                          *domain,    /* may be NULL */
 596     DNSServiceBrowseReply               callBack,
 597     void                                *context    /* may be NULL */
 598     );
 599
 600 /* DNSServiceResolve()
 601  *
 602  * Resolve a service name discovered via DNSServiceBrowse() to a target host name, port number, and
 603  * txt record.
 604  *
 605  * Note: Applications should NOT use DNSServiceResolve() solely for txt record monitoring - use
 606  * DNSServiceQueryRecord() instead, as it is more efficient for this task.
 607  *
 608  * Note: When the desired results have been returned, the client MUST terminate the resolve by calling
 609  * DNSServiceRefDeallocate().
 610  *
 611  * Note: DNSServiceResolve() behaves correctly for typical services that have a single SRV record and
 612  * a single TXT record (the TXT record may be empty.)  To resolve non-standard services with multiple
 613  * SRV or TXT records, DNSServiceQueryRecord() should be used.
 614  *
 615  * DNSServiceResolveReply Callback Parameters:
 616  *
 617  * sdRef:           The DNSServiceRef initialized by DNSServiceResolve().
 618  *
 619  * flags:           Currently unused, reserved for future use.
 620  *
 621  * interfaceIndex:  The interface on which the service was resolved.
 622  *
 623  * errorCode:       Will be kDNSServiceErr_NoError (0) on success, otherwise will
 624  *                  indicate the failure that occurred.  Other parameters are undefined if
 625  *                  the errorCode is nonzero.
 626  *
 627  * fullname:        The full service domain name, in the form <servicename>.<protocol>.<domain>.
 628  *                  (Any literal dots (".") are escaped with a backslash ("\."), and literal
 629  *                  backslashes are escaped with a second backslash ("\\"), e.g. a web server
 630  *                  named "Dr. Pepper" would have the fullname  "Dr\.\032Pepper._http._tcp.local.").
 631  *                  This is the appropriate format to pass to standard system DNS APIs such as
 632  *                  res_query(), or to the special-purpose functions included in this API that
 633  *                  take fullname parameters.
 634  *
 635  * hosttarget:      The target hostname of the machine providing the service.  This name can
 636  *                  be passed to functions like gethostbyname() to identify the host's IP address.
 637  *
 638  * port:            The port number on which connections are accepted for this service.
 639  *
 640  * txtLen:          The length of the txt record, in bytes.
 641  *
 642  * txtRecord:       The service's primary txt record, in standard txt record format.
 643  *
 644
 645  * context:         The context pointer that was passed to the callout.
 646  *
 647  */
 648
 649 typedef void (*DNSServiceResolveReply)
 650     (
 651     DNSServiceRef                       sdRef,
 652     DNSServiceFlags                     flags,
 653     uint32_t                            interfaceIndex,
 654     DNSServiceErrorType                 errorCode,
 655     const char                          *fullname,
 656     const char                          *hosttarget,
 657     uint16_t                            port,
 658     uint16_t                            txtLen,
 659     const char                          *txtRecord,
 660     void                                *context
 661     );
 662
 663 /* DNSServiceResolve() Parameters
 664  *
 665  * sdRef:           A pointer to an uninitialized sdRef.  May be passed to
 666  *                  DNSServiceRefDeallocate() to terminate the resolve.
 667  *
 668  * flags:           Currently ignored, reserved for future use.
 669  *
 670  * interfaceIndex:  The interface on which to resolve the service.  The client should
 671  *                  pass the interface on which the servicename was discovered, i.e.
 672  *                  the interfaceIndex passed to the DNSServiceBrowseReply callback,
 673  *                  or 0 to resolve the named service on all available interfaces.
 674  *
 675  * name:            The servicename to be resolved.
 676  *
 677  * regtype:         The service type being resolved followed by the protocol, separated by a
 678  *                  dot (e.g. "_ftp._tcp").  The transport protocol must be "_tcp" or "_udp".
 679  *
 680  * domain:          The domain on which the service is registered, i.e. the domain passed
 681  *                  to the DNSServiceBrowseReply callback.
 682  *
 683  * callBack:        The function to be called when a result is found, or if the call
 684  *                  asynchronously fails.
 685  *
 686  * context:         An application context pointer which is passed to the callback function
 687  *                  (may be NULL).
 688  *
 689  * return value:    Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
 690  *                  errors are delivered to the callback), otherwise returns an error code indicating
 691  *                  the error that occurred (the callback is never invoked and the DNSServiceRef
 692  *                  is not initialized.)
 693  */
 694
 695
 696 DNSServiceErrorType DNSServiceResolve
 697     (
 698     DNSServiceRef                       *sdRef,
 699     DNSServiceFlags                     flags,
 700     uint32_t                            interfaceIndex,
 701     const char                          *name,
 702     const char                          *regtype,
 703     const char                          *domain,
 704     DNSServiceResolveReply              callBack,
 705     void                                *context  /* may be NULL */
 706     );
 707
 708
 709 /*********************************************************************************************
 710  *
 711  *  Special Purpose Calls (most applications will not use these)
 712  *
 713  *********************************************************************************************/
 714
 715 /* DNS Naming Conventions:
 716  *
 717  * The following functions refer to resource records by their full domain name, unlike the above
 718  * functions which divide the name into servicename/regtype/domain fields.  In the above functions,
 719  * a dot (".") is considered to be a literal dot in the servicename field (e.g. "Dr. Pepper") and
 720  * a label separator in the regtype ("_ftp._tcp") or domain ("apple.com") fields.  Literal dots in
 721  * the domain field would be escaped with a backslash, and literal backslashes would be escaped with
 722  * a second backslash (this is generally not an issue, as domain names on  the Internet today almost
 723  * never use characters other than letters, digits, or hyphens, and the dots are label separators.)
 724  * Furthermore, this is transparent to the caller, so long as the fields are passed between functions
 725  * without manipulation.  However, the following, special-purpose calls use a single, full domain name.
 726  * As such, all dots are considered to be label separators, unless escaped, and all backslashes are
 727  * considered to be escape characters, unless preceded by a second backslash.  For example, the name
 728  * "Dr. Smith \ Dr. Johnson" could be passed literally as a service name parameter in the above calls,
 729  * but in the special purpose call, the dots and backslash would have to be escaped
 730  * (e.g. "Dr\. Smith \\ Dr\. Johnson._ftp._tcp.apple.com" for an ftp service on the apple.com domain.)
 731  */
 732
 733 /* DNSServiceConstructFullName()
 734  *
 735  * Concatenate a three-part domain name (as returned by the above callbacks) into a properly-escaped
 736  * full domain name.  Note that callbacks in the above functions ALREADY ESCAPE strings where necessary.
 737  *
 738  * Parameters:
 739  *
 740  * fullName:        A pointer to a buffer that where the resulting full domain name is to be written.
 741  *                  The buffer must be kDNSServiceDiscoveryMaxDomainName (1005) bytes in length to
 742  *                          accommodate the longest legal domain name without buffer overrun.
 743  *
 744  * service:         The service name - any dots or slashes must NOT be escaped.
 745  *                  May be NULL (to construct a PTR record name, e.g.
 746  *                  "_ftp._tcp.apple.com").
 747  *
 748  * regtype:         The service type followed by the protocol, separated by a dot
 749  *                  (e.g. "_ftp._tcp").
 750  *
 751  * domain:          The domain name, e.g. "apple.com".  Any literal dots or backslashes
 752  *                  must be escaped.
 753  *
 754  * return value:    Returns 0 on success, -1 on error.
 755  *
 756  */
 757
 758 int DNSServiceConstructFullName
 759     (
 760     char                            *fullName,
 761     const char                      *service,      /* may be NULL */
 762     const char                      *regtype,
 763     const char                      *domain
 764     );
 765
 766 /* DNSServiceCreateConnection()
 767  *
 768  * Create a connection to the daemon allowing efficient registration of
 769  * multiple individual records.
 770  *
 771  *
 772  * Parameters:
 773  *
 774  * sdRef:           A pointer to an uninitialized DNSServiceRef.  Deallocating
 775  *                  the reference (via DNSServiceRefDeallocate()) severs the
 776  *                  connection and deregisters all records registered on this connection.
 777  *
 778  * return value:    Returns kDNSServiceErr_NoError on success, otherwise returns
 779  *                  an error code indicating the specific failure that occurred (in which
 780  *                  case the DNSServiceRef is not initialized).
 781  */
 782
 783 DNSServiceErrorType DNSServiceCreateConnection(DNSServiceRef *sdRef);
 784
 785
 786 /* DNSServiceRegisterRecord
 787  *
 788  * Register an individual resource record on a connected DNSServiceRef.
 789  *
 790  * Note that name conflicts occurring for records registered via this call must be handled
 791  * by the client in the callback.
 792  *
 793  *
 794  * DNSServiceRegisterRecordReply() parameters:
 795  *
 796  * sdRef:           The connected DNSServiceRef initialized by
 797  *                  DNSServiceDiscoveryConnect().
 798  *
 799  * RecordRef:       The DNSRecordRef initialized by DNSServiceRegisterRecord().  If the above
 800  *                  DNSServiceRef is passed to DNSServiceRefDeallocate(), this DNSRecordRef is
 801  *                  invalidated, and may not be used further.
 802  *
 803  * flags:           Currently unused, reserved for future use.
 804  *
 805  * errorCode:       Will be kDNSServiceErr_NoError on success, otherwise will
 806  *                  indicate the failure that occurred (including name conflicts.)
 807  *                  Other parameters are undefined if errorCode is nonzero.
 808  *
 809  * context:         The context pointer that was passed to the callout.
 810  *
 811  */
 812
 813  typedef void (*DNSServiceRegisterRecordReply)
 814     (
 815     DNSServiceRef                       sdRef,
 816     DNSRecordRef                        RecordRef,
 817     DNSServiceFlags                     flags,
 818     DNSServiceErrorType                 errorCode,
 819     void                                *context
 820     );
 821
 822
 823 /* DNSServiceRegisterRecord() Parameters:
 824  *
 825  * sdRef:           A DNSServiceRef initialized by DNSServiceCreateConnection().
 826  *
 827  * RecordRef:       A pointer to an uninitialized DNSRecordRef.  Upon succesfull completion of this
 828  *                  call, this ref may be passed to DNSServiceUpdateRecord() or DNSServiceRemoveRecord().
 829  *                  (To deregister ALL records registered on a single connected DNSServiceRef
 830  *                  and deallocate each of their corresponding DNSServiceRecordRefs, call
 831  *                  DNSServiceRefDealloocate()).
 832  *
 833  * flags:           Possible values are Shared/Unique (see flag type definitions for details).
 834  *
 835  * interfaceIndex:  If non-zero, specifies the interface on which to register the record
 836  *                  (the index for a given interface is determined via the if_nametoindex()
 837  *                  family of calls.)  Passing 0 causes the record to be registered on all interfaces.
 838  *                  Passing -1 causes the record to only be visible on the local host.
 839  *
 840  * fullname:        The full domain name of the resource record.
 841  *
 842  * rrtype:          The numerical type of the resource record (e.g. PTR, SRV, etc), as defined
 843  *                  in nameser.h.
 844  *
 845  * rrclass:         The class of the resource record, as defined in nameser.h (usually 1 for the
 846  *                  Internet class).
 847  *
 848  * rdlen:           Length, in bytes, of the rdata.
 849  *
 850  * rdata:           A pointer to the raw rdata, as it is to appear in the DNS record.
 851  *
 852  * ttl:             The time to live of the resource record, in seconds.
 853  *
 854  * callBack:        The function to be called when a result is found, or if the call
 855  *                  asynchronously fails (e.g. because of a name conflict.)
 856  *
 857  * context:         An application context pointer which is passed to the callback function
 858  *                  (may be NULL).
 859  *
 860  * return value:    Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
 861  *                  errors are delivered to the callback), otherwise returns an error code indicating
 862  *                  the error that occurred (the callback is never invoked and the DNSRecordRef is
 863  *                  not initialized.)
 864  */
 865
 866
 867 DNSServiceErrorType DNSServiceRegisterRecord
 868     (
 869     DNSServiceRef                       sdRef,
 870     DNSRecordRef                        *RecordRef,
 871     DNSServiceFlags                     flags,
 872     uint32_t                            interfaceIndex,
 873     const char                          *fullname,
 874     uint16_t                            rrtype,
 875     uint16_t                            rrclass,
 876     uint16_t                            rdlen,
 877     const void                          *rdata,
 878     uint32_t                            ttl,
 879     DNSServiceRegisterRecordReply       callBack,
 880     void                                *context    /* may be NULL */
 881     );
 882
 883
 884 /* DNSServiceQueryRecord
 885  *
 886  * Query for an arbitrary DNS record.
 887  *
 888  *
 889  * DNSServiceQueryRecordReply() Callback Parameters:
 890  *
 891  * sdRef:           The DNSServiceRef initialized by DNSServiceQueryRecord().
 892  *
 893  * flags:           Possible values are Finished/MoreComing.
 894  *
 895  * interfaceIndex:  The interface on which the query was resolved (the index for a given
 896  *                  interface is determined via the if_nametoindex() family of calls).
 897  *
 898  * errorCode:       Will be kDNSServiceErr_NoError on success, otherwise will
 899  *                  indicate the failure that occurred.  Other parameters are undefined if
 900  *                  errorCode is nonzero.
 901  *
 902  * fullname:        The resource record's full domain name.
 903  *
 904  * rrtype:          The resource record's type (e.g. PTR, SRV, etc) as defined in nameser.h.
 905  *
 906  * rrclass:         The class of the resource record, as defined in nameser.h (usually 1).
 907  *
 908  * rdlen:           The length, in bytes, of the resource record rdata.
 909  *
 910  * rdata:           The raw rdata of the resource record.
 911  *
 912  * ttl:             The resource record's time to live, in seconds.
 913  *
 914  * context:         The context pointer that was passed to the callout.
 915  *
 916  */
 917
 918 typedef void (*DNSServiceQueryRecordReply)
 919     (
 920     DNSServiceRef                       DNSServiceRef,
 921     DNSServiceFlags                     flags,
 922     uint32_t                            interfaceIndex,
 923     DNSServiceErrorType                 errorCode,
 924     const char                          *fullname,
 925     uint16_t                            rrtype,
 926     uint16_t                            rrclass,
 927     uint16_t                            rdlen,
 928     const void                          *rdata,
 929     uint32_t                            ttl,
 930     void                                *context
 931     );
 932
 933 /* DNSServiceQueryRecord() Parameters:
 934  *
 935  * sdRef:           A pointer to an uninitialized DNSServiceRef.
 936  *
 937  * flags:           Currently unused, reserved for future use.
 938  *
 939  * interfaceIndex:  If non-zero, specifies the interface on which to issue the query
 940  *                  (the index for a given interface is determined via the if_nametoindex()
 941  *                  family of calls.)  Passing 0 causes the name to be queried for on all
 942  *                  interfaces.  Passing -1 causes the name to be queried for only on the
 943  *                  local host.
 944  *
 945  * fullname:        The full domain name of the resource record to be queried for.
 946  *
 947  * rrtype:          The numerical type of the resource record to be queried for (e.g. PTR, SRV, etc)
 948  *                  as defined in nameser.h.
 949  *
 950  * rrclass:         The class of the resource record, as defined in nameser.h
 951  *                  (usually 1 for the Internet class).
 952  *
 953  * callBack:        The function to be called when a result is found, or if the call
 954  *                  asynchronously fails.
 955  *
 956  * context:         An application context pointer which is passed to the callback function
 957  *                  (may be NULL).
 958  *
 959  * return value:    Returns kDNSServiceErr_NoError on succeses (any subsequent, asynchronous
 960  *                  errors are delivered to the callback), otherwise returns an error code indicating
 961  *                  the error that occurred (the callback is never invoked and the DNSServiceRef
 962  *                  is not initialized.)
 963  */
 964
 965 DNSServiceErrorType DNSServiceQueryRecord
 966     (
 967     DNSServiceRef                       *sdRef,
 968     DNSServiceFlags                     flags,
 969     uint32_t                            interfaceIndex,
 970     const char                          *fullname,
 971     uint16_t                            rrtype,
 972     uint16_t                            rrclass,
 973     DNSServiceQueryRecordReply          callBack,
 974     void                                *context  /* may be NULL */
 975     );
 976
 977 /* DNSServiceReconfirmRecord
 978  *
 979  * Instruct the daemon to verify the validity of a resource record that appears to
 980  * be out of date (e.g. because tcp connection to a service's target failed.)
 981  * Causes the record to be flushed from the daemon's cache (as well as all other
 982  * daemons' caches on the network) if the record is determined to be invalid.
 983  *
 984  * Parameters:
 985  *
 986  * flags:           Currently unused, reserved for future use.
 987  *
 988  * fullname:        The resource record's full domain name.
 989  *
 990  * rrtype:          The resource record's type (e.g. PTR, SRV, etc) as defined in nameser.h.
 991  *
 992  * rrclass:         The class of the resource record, as defined in nameser.h (usually 1).
 993  *
 994  * rdlen:           The length, in bytes, of the resource record rdata.
 995  *
 996  * rdata:           The raw rdata of the resource record.
 997  *
 998  */
 999
1000 void DNSServiceReconfirmRecord
1001     (
1002     DNSServiceFlags                    flags,
1003     uint32_t                           interfaceIndex,
1004     const char                         *fullname,
1005     uint16_t                           rrtype,
1006     uint16_t                           rrclass,
1007     uint16_t                           rdlen,
1008     const void                         *rdata
1009     );
1010
1011
1012 #endif  // _DNS_SD_H
1013