mDNSMacOSX/dnssd_private.h

   1 /*
   2  * Copyright (c) 2019 Apple Inc. All rights reserved.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __DNSSD_PRIVATE_H__
  18 #define __DNSSD_PRIVATE_H__
  19
  20 #include <dispatch/dispatch.h>
  21 #include <dns_sd.h>
  22 #include <os/object.h>
  23
  24 #if OS_OBJECT_USE_OBJC
  25         #define DNSSD_DECL(NAME)                OS_OBJECT_DECL_SUBCLASS(dnssd_ ## NAME, dnssd_object)
  26         #define DNSSD_RETURNS_RETAINED  OS_OBJECT_RETURNS_RETAINED
  27
  28         OS_OBJECT_DECL(dnssd_object,);
  29 #else
  30         #define DNSSD_DECL(NAME)                typedef struct dnssd_ ## NAME ## _s *   dnssd_ ## NAME ## _t
  31         #define DNSSD_RETURNS_RETAINED
  32
  33         DNSSD_DECL(object);
  34 #endif
  35
  36 #define DNSSD_ASSUME_NONNULL_BEGIN      OS_ASSUME_NONNULL_BEGIN
  37 #define DNSSD_ASSUME_NONNULL_END        OS_ASSUME_NONNULL_END
  38
  39 DNSSD_DECL(getaddrinfo);
  40 DNSSD_DECL(getaddrinfo_result);
  41
  42 DNSSD_ASSUME_NONNULL_BEGIN
  43
  44 #if OS_OBJECT_USE_OBJC
  45         typedef dnssd_object_t  dnssd_any_t;
  46 #else
  47         #if !defined(__cplusplus)
  48                 typedef union {
  49                         dnssd_object_t                          base;
  50                         dnssd_getaddrinfo_t                     gai;
  51                         dnssd_getaddrinfo_result_t      gai_result;
  52                 } dnssd_any_t __attribute__((__transparent_union__));
  53         #else
  54                 typedef void *  dnssd_any_t;
  55         #endif
  56 #endif
  57
  58 #define DNSSD_MALLOC    __attribute__((__malloc__))
  59 #define DNSSD_AVAILABLE SPI_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
  60
  61 __BEGIN_DECLS
  62
  63 /*!
  64  *      @brief
  65  *              Increments the reference count of a dnssd object.
  66  *
  67  *      @param object
  68  *              The dnssd object.
  69  *
  70  *      @discussion
  71  *              Calls to dnssd_retain() must be balanced with calls to dnssd_release().
  72  */
  73 DNSSD_AVAILABLE
  74 void
  75 dnssd_retain(dnssd_any_t object);
  76 #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
  77 #undef dnssd_retain
  78 #define dnssd_retain(object)    [(object) retain]
  79 #endif
  80
  81 /*!
  82  *      @brief
  83  *              Decrements the reference count of a dnssd object.
  84  *
  85  *      @param object
  86  *              The dnssd object.
  87  *
  88  *      @discussion
  89  *              Calls to dnssd_retain() must be balanced with calls to dnssd_release().
  90  */
  91 DNSSD_AVAILABLE
  92 void
  93 dnssd_release(dnssd_any_t object);
  94 #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
  95 #undef dnssd_release
  96 #define dnssd_release(object)   [(object) release]
  97 #endif
  98
  99
 100 /*!
 101  *      @brief
 102  *              Provides a textual description of a dnssd object.
 103  *
 104  *      @param object
 105  *              The dnssd object.
 106  *
 107  *      @result
 108  *              Textual description of the object as a C string.
 109  *
 110  *      @discussion
 111  *              The string returned by this function must be released with <code>free(3)</code>.
 112  */
 113 DNSSD_AVAILABLE
 114 DNSSD_MALLOC char * _Nullable
 115 dnssd_copy_description(dnssd_any_t object);
 116
 117 /*!
 118  *      @brief
 119  *              Creates a getaddrinfo object.
 120  *
 121  *      @result
 122  *              A new getaddrinfo object.
 123  *
 124  *      @discussion
 125  *              A getaddrinfo object resolves a hostname to its IPv4 and IPv6 addresses.
 126  */
 127 DNSSD_AVAILABLE
 128 DNSSD_RETURNS_RETAINED dnssd_getaddrinfo_t _Nullable
 129 dnssd_getaddrinfo_create(void);
 130
 131 /*!
 132  *      @brief
 133  *              Specifies the queue on which to invoke the getaddrinfo object's result and event blocks.
 134  *
 135  *      @param gai
 136  *              The getaddrinfo object.
 137  *
 138  *      @param queue
 139  *              A serial queue.
 140  *
 141  *      @discussion
 142  *              This call must be made before activating the getaddrinfo object.
 143  *
 144  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 145  */
 146 DNSSD_AVAILABLE
 147 void
 148 dnssd_getaddrinfo_set_queue(dnssd_getaddrinfo_t gai, dispatch_queue_t queue);
 149
 150 /*!
 151  *      @brief
 152  *              Specifies the DNSServiceFlags to use for the getaddrinfo operation.
 153  *
 154  *      @param gai
 155  *              The getaddrinfo object.
 156  *
 157  *      @param flags
 158  *              Flags.
 159  *
 160  *      @discussion
 161  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 162  */
 163 DNSSD_AVAILABLE
 164 void
 165 dnssd_getaddrinfo_set_flags(dnssd_getaddrinfo_t gai, DNSServiceFlags flags);
 166
 167 /*!
 168  *      @brief
 169  *              Specifies the hostname to resolve.
 170  *
 171  *      @param gai
 172  *              The getaddrinfo object.
 173  *
 174  *      @param hostname
 175  *              Hostname as a fully-qualified domain name.
 176  *
 177  *      @discussion
 178  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 179  */
 180 DNSSD_AVAILABLE
 181 void
 182 dnssd_getaddrinfo_set_hostname(dnssd_getaddrinfo_t gai, const char *hostname);
 183
 184 /*!
 185  *      @brief
 186  *              Specifies the index of the interface via which to resolve the hostname.
 187  *
 188  *      @param gai
 189  *              The getaddrinfo object.
 190  *
 191  *      @param interface_index
 192  *              Interface index.
 193  *
 194  *      @discussion
 195  *              If <code>kDNSServiceInterfaceIndexAny</code> is used as the interface index, then special behavior applies. If
 196  *              the hostname is in the "local." domain, then an attempt will be made to resolve the hostname via all active
 197  *              mDNS-capable interfaces. If the hostname is in any other domain, then the hostname will be resolved via the
 198  *              primary interface.
 199  *
 200  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 201  */
 202 DNSSD_AVAILABLE
 203 void
 204 dnssd_getaddrinfo_set_interface_index(dnssd_getaddrinfo_t gai, uint32_t interface_index);
 205
 206 /*!
 207  *      @brief
 208  *              Specifies the types of addresses to which to resolve the hostname.
 209  *
 210  *      @param gai
 211  *              The getaddrinfo object.
 212  *
 213  *      @param protocols
 214  *              Protocols.
 215  *
 216  *      @discussion
 217  *              Set <code>protocols</code> to <code>kDNSServiceProtocol_IPv4</code> to resolve the hostname to IPv4 addresses.
 218  *
 219  *              Set <code>protocols</code> to <code>kDNSServiceProtocol_IPv6</code> to resolve the hostname to IPv6 addresses.
 220  *
 221  *              Set <code>protocols</code> to <code>kDNSServiceProtocol_IPv4 | kDNSServiceProtocol_IPv6</code> to resolve the
 222  *              hostname to both IPv4 and IPv6 addresses.
 223  *
 224  *              Set <code>protocols</code> to 0 to limit resolution to addresses of protocols of which the host has routable
 225  *              addresses. That is, an attempt will be made to resolve the hostname to IPv4 addresses if and only if the host
 226  *              has a routable IPv4 address. Likewise, an attempt will be made to resolve the hostname to IPv6 addresses if and
 227  *              only if the host has a routable IPv6 address.
 228  *
 229  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 230  */
 231 DNSSD_AVAILABLE
 232 void
 233 dnssd_getaddrinfo_set_protocols(dnssd_getaddrinfo_t gai, DNSServiceProtocol protocols);
 234
 235 /*!
 236  *      @brief
 237  *              Sets the process ID (PID) of the process on whose behalf the getaddrinfo operation is being performed.
 238  *
 239  *      @param gai
 240  *              The getaddrinfo object.
 241  *
 242  *      @param pid
 243  *              PID of the process being represented.
 244  *
 245  *      @discussion
 246  *              If a delegate PID is set, then the calling process must have the proper entitlement in order for the
 247  *              getaddrinfo operation to not fail with a kDNSServiceErr_NotAuth error.
 248  *
 249  *              This function is an alternative to <code>dnssd_getaddrinfo_set_delegate_uuid()</code>.
 250  *
 251  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 252  */
 253 DNSSD_AVAILABLE
 254 void
 255 dnssd_getaddrinfo_set_delegate_pid(dnssd_getaddrinfo_t gai, pid_t pid);
 256
 257 /*!
 258  *      @brief
 259  *              Sets the UUID of the process on whose behalf the getaddrinfo operation is being performed.
 260  *
 261  *      @param gai
 262  *              The getaddrinfo object.
 263  *
 264  *      @param uuid
 265  *              UUID of the process being represented.
 266  *
 267  *      @discussion
 268  *              If a delegate UUID is set, then the calling process must have the proper entitlement in order for the
 269  *              getaddrinfo operation to not fail with the <code>kDNSServiceErr_NotAuth</code> error.
 270  *
 271  *              This function is an alternative to <code>dnssd_getaddrinfo_set_delegate_pid()</code>.
 272  *
 273  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 274  */
 275 DNSSD_AVAILABLE
 276 void
 277 dnssd_getaddrinfo_set_delegate_uuid(dnssd_getaddrinfo_t gai, uuid_t _Nonnull uuid);
 278
 279 /*!
 280  *      @brief
 281  *              Specifies whether or not getaddrinfo results (of types <code>dnssd_getaddrinfo_result_type_add</code> and
 282  *              <code>dnssd_getaddrinfo_result_type_expired</code>) should include authentication tags from the stub resolver.
 283  *
 284  *      @param gai
 285  *              The getaddrinfo object.
 286  *
 287  *      @param need
 288  *              Pass <code>true</code> if authenticated results are needed, otherwise, pass <code>false</code>.
 289  *
 290  *      @discussion
 291  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 292  */
 293 DNSSD_AVAILABLE
 294 void
 295 dnssd_getaddrinfo_set_need_authenticated_results(dnssd_getaddrinfo_t gai, bool need);
 296
 297 /*!
 298  *      @brief
 299  *              Activates a getaddrinfo object.
 300  *
 301  *      @param gai
 302  *              The getaddrinfo object.
 303  *
 304  *      @discussion
 305  *              This function has no effect on a getaddrinfo object that has already been activated or has been invalidated.
 306  */
 307 DNSSD_AVAILABLE
 308 void
 309 dnssd_getaddrinfo_activate(dnssd_getaddrinfo_t gai);
 310
 311 /*!
 312  *      @brief
 313  *              Asynchronously invalidates a getaddrinfo object.
 314  *
 315  *      @param gai
 316  *              The getaddrinfo object.
 317  *
 318  *      @discussion
 319  *              As a result of calling this function, the getaddrinfo object's event handler will be invoked with a
 320  *              <code>dnssd_event_invalidated</code> event. After this, the object's event and result handlers will never be
 321  *              invoked again.
 322  *
 323  *              This function has no effect on a getaddrinfo object that has already been invalidated.
 324  */
 325 DNSSD_AVAILABLE
 326 void
 327 dnssd_getaddrinfo_invalidate(dnssd_getaddrinfo_t gai);
 328
 329 /*!
 330  *      @brief
 331  *              Handler for getaddrinfo results.
 332  *
 333  *      @param result_array
 334  *              C array of getaddrinfo results.
 335  *
 336  *      @param result_count
 337  *              Size of the array in terms of number of results.
 338  */
 339 typedef void (^dnssd_getaddrinfo_result_handler_t)(dnssd_getaddrinfo_result_t _Nonnull * _Nonnull result_array,
 340                                                                                                    size_t result_count);
 341
 342 /*!
 343  *      @brief
 344  *              Specifies a getaddrinfo object's result handler.
 345  *
 346  *      @param gai
 347  *              The getaddrinfo object.
 348  *
 349  *      @param handler
 350  *              Result handler.
 351  */
 352 DNSSD_AVAILABLE
 353 void
 354 dnssd_getaddrinfo_set_result_handler(dnssd_getaddrinfo_t gai, dnssd_getaddrinfo_result_handler_t _Nullable handler);
 355
 356 /*!
 357  *      @brief
 358  *              Events that can occur during the lifetime of a getaddrinfo object.
 359  */
 360 typedef enum {
 361         /*! @const dnssd_event_error An error occurred. */
 362         dnssd_event_error               = 1,
 363         /*! @const dnssd_event_remove_all All results prior to this event are no longer valid. */
 364         dnssd_event_remove_all  = 2,
 365         /*! @const dnssd_event_invalidated The object has been invalidated. */
 366         dnssd_event_invalidated = 3,
 367 } dnssd_event_t;
 368
 369 /*!
 370  *      @brief
 371  *              Handler for getaddrinfo events.
 372  *
 373  *      @param event
 374  *              Event.
 375  *
 376  *      @param error
 377  *              The error associated with a <code>dnssd_event_error</code> event. Ignore for all other types of events.
 378  *
 379  *      @discussion
 380  *              After a <code>dnssd_event_invalidated</code> event, a getaddrinfo object's result and event handlers will never
 381  *              be invoked again.
 382  */
 383 typedef void (^dnssd_event_handler_t)(dnssd_event_t event, DNSServiceErrorType error);
 384
 385 /*!
 386  *      @brief
 387  *              Sets a getaddrinfo object's event handler.
 388  *
 389  *      @param gai
 390  *              The getaddrinfo object.
 391  *
 392  *      @param handler
 393  *              Event handler.
 394  */
 395 DNSSD_AVAILABLE
 396 void
 397 dnssd_getaddrinfo_set_event_handler(dnssd_getaddrinfo_t gai, dnssd_event_handler_t _Nullable handler);
 398
 399 /*!
 400  *      @brief
 401  *              Types of getaddrinfo results.
 402  */
 403 typedef enum {
 404         /*! @const dnssd_getaddrinfo_result_type_add The contained hostname and address pair is valid. */
 405         dnssd_getaddrinfo_result_type_add                       = 1,
 406         /*! @const dnssd_getaddrinfo_result_type_remove The contained hostname and address pair is no longer valid. */
 407         dnssd_getaddrinfo_result_type_remove            = 2,
 408         /*! @const dnssd_getaddrinfo_result_type_no_address The contained hostname has no address of a particular type. */
 409         dnssd_getaddrinfo_result_type_no_address        = 3,
 410         /*! @const dnssd_getaddrinfo_result_type_expired A hostname and address pair contained came from an expired cached record and may no longer be valid. */
 411         dnssd_getaddrinfo_result_type_expired           = 4,
 412 } dnssd_getaddrinfo_result_type_t;
 413
 414 /*!
 415  *      @brief
 416  *              Gets a getaddrinfo result's type.
 417  *
 418  *      @param gai_result
 419  *              The getaddrinfo result.
 420  *
 421  *      @result
 422  *              Result type.
 423  */
 424 DNSSD_AVAILABLE
 425 dnssd_getaddrinfo_result_type_t
 426 dnssd_getaddrinfo_result_get_type(dnssd_getaddrinfo_result_t gai_result);
 427
 428 /*!
 429  *      @brief
 430  *              Gets a getaddrinfo result's actual hostname.
 431  *
 432  *      @param gai_result
 433  *              The getaddrinfo result.
 434  *
 435  *      @result
 436  *              The getaddrinfo result's actual hostname.
 437  *
 438  *      @discussion
 439  *              The hostname returned by this function is the canonical name of the hostname that was requested. In other
 440  *              words, it's the canonical name of the hostname set with <code>dnssd_getaddrinfo_set_hostname()</code>.
 441  *
 442  *              The pointer returned by this function is valid until the getaddrinfo result is released.
 443  */
 444 DNSSD_AVAILABLE
 445 const char *
 446 dnssd_getaddrinfo_result_get_actual_hostname(dnssd_getaddrinfo_result_t gai_result);
 447
 448 /*!
 449  *      @brief
 450  *              Gets a getaddrinfo result's address.
 451  *
 452  *      @param gai_result
 453  *              The getaddrinfo result.
 454  *
 455  *      @result
 456  *              The getaddrinfo result's address as a sockaddr structure.
 457  *
 458  *      @discussion
 459  *              For getaddrinfo results of type <code>dnssd_getaddrinfo_result_type_no_address</code>, the sockaddr structure's
 460  *              sa_family member variable can be used to determine the type of address that the hostname lacks.
 461  */
 462 DNSSD_AVAILABLE
 463 const struct sockaddr *
 464 dnssd_getaddrinfo_result_get_address(dnssd_getaddrinfo_result_t gai_result);
 465
 466 /*!
 467  *      @brief
 468  *              Gets a getaddrinfo result's hostname.
 469  *
 470  *      @param gai_result
 471  *              The getaddrinfo result.
 472  *
 473  *      @result
 474  *              The getaddrinfo result's hostname.
 475  *
 476  *      @discussion
 477  *              The hostname returned by this function is the hostname whose resolution was requested. In other words, it's
 478  *              equal to the hostname set with <code>dnssd_getaddrinfo_set_hostname()</code>.
 479  *
 480  *              The pointer returned by this function is valid until the getaddrinfo result is released.
 481  */
 482 DNSSD_AVAILABLE
 483 const char *
 484 dnssd_getaddrinfo_result_get_hostname(dnssd_getaddrinfo_result_t gai_result);
 485
 486 /*!
 487  *      @brief
 488  *              Gets the interface index to which a getaddrinfo result pertains.
 489  *
 490  *      @param gai_result
 491  *              The getaddrinfo result.
 492  *
 493  *      @result
 494  *              For hostnames that were resolved via mDNS, the return value is the index of the interface via which the
 495  *              hostname was resolved. For hostnames that were resolved via DNS, the return value is 0.
 496  */
 497 DNSSD_AVAILABLE
 498 uint32_t
 499 dnssd_getaddrinfo_result_get_interface_index(dnssd_getaddrinfo_result_t gai_result);
 500
 501 /*!
 502  *      @brief
 503  *              Gets a getaddrinfo result's authentication tag.
 504  *
 505  *      @param gai_result
 506  *              The getaddrinfo result.
 507  *
 508  *      @param out_length
 509  *              If non-NULL, gets set to the length of the authentication tag.
 510  *
 511  *      @result
 512  *              A pointer to the getaddrinfo result's authentication tag, if it has one. Otherwise, NULL.
 513  *
 514  *      @discussion
 515  *              The returned pointer, if non-NULL, is valid until the getaddrinfo result is released.
 516  */
 517 DNSSD_AVAILABLE
 518 const void * _Nullable
 519 dnssd_getaddrinfo_result_get_authentication_tag(dnssd_getaddrinfo_result_t gai_result, size_t *_Nullable out_length);
 520
 521 static inline const char *
 522 dnssd_getaddrinfo_result_type_to_string(dnssd_getaddrinfo_result_type_t result)
 523 {
 524         switch (result) {
 525                 case dnssd_getaddrinfo_result_type_add:                 return "Add";
 526                 case dnssd_getaddrinfo_result_type_remove:              return "Remove";
 527                 case dnssd_getaddrinfo_result_type_no_address:  return "NoAddress";
 528                 case dnssd_getaddrinfo_result_type_expired:             return "Expired";
 529                 default:                                                                                return "?";
 530         }
 531 }
 532
 533 static inline const char *
 534 dnssd_event_to_string(dnssd_event_t event)
 535 {
 536         switch (event) {
 537                 case dnssd_event_remove_all:    return "RemoveAll";
 538                 case dnssd_event_error:                 return "Error";
 539                 case dnssd_event_invalidated:   return "Invalidated";
 540                 default:                                                return "?";
 541         }
 542 }
 543
 544 __END_DECLS
 545
 546 DNSSD_ASSUME_NONNULL_END
 547
 548 #endif  // __DNSSD_PRIVATE_H__