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