mDNSShared/dns_sd.h

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