mdns.subproj/dns_sd.h

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