mDNSMacOSX/dnssd_private.h

   1 /*
   2  * Copyright (c) 2019-2020 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  *     https://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 <xpc/xpc.h>
  22 #include <dns_sd.h>
  23 #include <os/object.h>
  24
  25 #if OS_OBJECT_USE_OBJC
  26         #define DNSSD_DECL(NAME)                OS_OBJECT_DECL_SUBCLASS(dnssd_ ## NAME, dnssd_object)
  27         #define DNSSD_RETURNS_RETAINED  OS_OBJECT_RETURNS_RETAINED
  28
  29         OS_OBJECT_DECL(dnssd_object,);
  30 #else
  31         #define DNSSD_DECL(NAME)                typedef struct dnssd_ ## NAME ## _s *   dnssd_ ## NAME ## _t
  32         #define DNSSD_RETURNS_RETAINED
  33
  34         DNSSD_DECL(object);
  35 #endif
  36
  37 #define DNSSD_ASSUME_NONNULL_BEGIN      OS_ASSUME_NONNULL_BEGIN
  38 #define DNSSD_ASSUME_NONNULL_END        OS_ASSUME_NONNULL_END
  39
  40 DNSSD_DECL(getaddrinfo);
  41 DNSSD_DECL(getaddrinfo_result);
  42 DNSSD_DECL(cname_array);
  43
  44 DNSSD_ASSUME_NONNULL_BEGIN
  45
  46 #if OS_OBJECT_USE_OBJC
  47         typedef dnssd_object_t  dnssd_any_t;
  48 #else
  49         #if !defined(__cplusplus)
  50                 typedef union {
  51                         dnssd_object_t                          object;
  52                         dnssd_getaddrinfo_t                     gai;
  53                         dnssd_getaddrinfo_result_t      gai_result;
  54                         dnssd_cname_array_t                     cname_array;
  55                 } dnssd_any_t __attribute__((__transparent_union__));
  56         #else
  57                 typedef void *  dnssd_any_t;
  58         #endif
  59 #endif
  60
  61 #define DNSSD_MALLOC    __attribute__((__malloc__))
  62 #define DNSSD_AVAILABLE SPI_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
  63
  64 #if __has_attribute(noescape)
  65 #define DNSSD_NOESCAPE __attribute__((__noescape__))
  66 #else // noescape
  67 #define DNSSD_NOESCAPE
  68 #endif // noescape
  69
  70 __BEGIN_DECLS
  71
  72 /*!
  73  *      @brief
  74  *              Increments the reference count of a dnssd object.
  75  *
  76  *      @param object
  77  *              The dnssd object.
  78  *
  79  *      @discussion
  80  *              Calls to dnssd_retain() must be balanced with calls to dnssd_release().
  81  */
  82 DNSSD_AVAILABLE
  83 void
  84 dnssd_retain(dnssd_any_t object);
  85 #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
  86 #undef dnssd_retain
  87 #define dnssd_retain(object)    [(object) retain]
  88 #endif
  89
  90 /*!
  91  *      @brief
  92  *              Decrements the reference count of a dnssd object.
  93  *
  94  *      @param object
  95  *              The dnssd object.
  96  *
  97  *      @discussion
  98  *              Calls to dnssd_retain() must be balanced with calls to dnssd_release().
  99  */
 100 DNSSD_AVAILABLE
 101 void
 102 dnssd_release(dnssd_any_t object);
 103 #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
 104 #undef dnssd_release
 105 #define dnssd_release(object)   [(object) release]
 106 #endif
 107
 108
 109 /*!
 110  *      @brief
 111  *              Provides a textual description of a dnssd object.
 112  *
 113  *      @param object
 114  *              The dnssd object.
 115  *
 116  *      @result
 117  *              Textual description of the object as a C string.
 118  *
 119  *      @discussion
 120  *              The string returned by this function must be released with <code>free(3)</code>.
 121  */
 122 DNSSD_AVAILABLE
 123 DNSSD_MALLOC char * _Nullable
 124 dnssd_copy_description(dnssd_any_t object);
 125
 126 /*!
 127  *      @brief
 128  *              Creates a getaddrinfo object.
 129  *
 130  *      @result
 131  *              A new getaddrinfo object.
 132  *
 133  *      @discussion
 134  *              A getaddrinfo object resolves a hostname to its IPv4 and IPv6 addresses.
 135  */
 136 DNSSD_AVAILABLE
 137 DNSSD_RETURNS_RETAINED dnssd_getaddrinfo_t _Nullable
 138 dnssd_getaddrinfo_create(void);
 139
 140 /*!
 141  *      @brief
 142  *              Specifies the queue on which to invoke the getaddrinfo object's result and event blocks.
 143  *
 144  *      @param gai
 145  *              The getaddrinfo object.
 146  *
 147  *      @param queue
 148  *              A serial queue.
 149  *
 150  *      @discussion
 151  *              This call must be made before activating the getaddrinfo object.
 152  *
 153  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 154  */
 155 DNSSD_AVAILABLE
 156 void
 157 dnssd_getaddrinfo_set_queue(dnssd_getaddrinfo_t gai, dispatch_queue_t queue);
 158
 159 /*!
 160  *      @brief
 161  *              Specifies the DNSServiceFlags to use for the getaddrinfo operation.
 162  *
 163  *      @param gai
 164  *              The getaddrinfo object.
 165  *
 166  *      @param flags
 167  *              Flags.
 168  *
 169  *      @discussion
 170  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 171  */
 172 DNSSD_AVAILABLE
 173 void
 174 dnssd_getaddrinfo_set_flags(dnssd_getaddrinfo_t gai, DNSServiceFlags flags);
 175
 176 #define DNSSD_GETADDRINFO_SUPPORTS_ACCOUNT_ID 1
 177
 178 /*!
 179  *      @brief
 180  *              Specifies the account id to use for the getaddrinfo operation.
 181  *
 182  *      @param gai
 183  *              The getaddrinfo object.
 184  *
 185  *      @param account_id
 186  *              The account id.
 187  *
 188  *      @discussion
 189  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 190  */
 191 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 192 void
 193 dnssd_getaddrinfo_set_account_id(dnssd_getaddrinfo_t gai, const char * account_id);
 194
 195 /*!
 196  *      @brief
 197  *              Specifies the hostname to resolve.
 198  *
 199  *      @param gai
 200  *              The getaddrinfo object.
 201  *
 202  *      @param hostname
 203  *              Hostname as a fully-qualified domain name.
 204  *
 205  *      @discussion
 206  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 207  */
 208 DNSSD_AVAILABLE
 209 void
 210 dnssd_getaddrinfo_set_hostname(dnssd_getaddrinfo_t gai, const char *hostname);
 211
 212 #define DNSSD_GETADDRINFO_SUPPORTS_SERVICE_SCHEME 1
 213
 214 /*!
 215  *      @brief
 216  *              Specifies the optional service scheme to resolve.
 217  *
 218  *      @param gai
 219  *              The getaddrinfo object.
 220  *
 221  *      @param service_scheme
 222  *              Service scheme as a string, such as "_443._https".
 223  *
 224  *      @discussion
 225  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 226  */
 227 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 228 void
 229 dnssd_getaddrinfo_set_service_scheme(dnssd_getaddrinfo_t gai, const char * _Nullable service_scheme);
 230
 231 /*!
 232  *      @brief
 233  *              Specifies the index of the interface via which to resolve the hostname.
 234  *
 235  *      @param gai
 236  *              The getaddrinfo object.
 237  *
 238  *      @param interface_index
 239  *              Interface index.
 240  *
 241  *      @discussion
 242  *              If <code>kDNSServiceInterfaceIndexAny</code> is used as the interface index, then special behavior applies. If
 243  *              the hostname is in the "local." domain, then an attempt will be made to resolve the hostname via all active
 244  *              mDNS-capable interfaces. If the hostname is in any other domain, then the hostname will be resolved via the
 245  *              primary interface.
 246  *
 247  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 248  */
 249 DNSSD_AVAILABLE
 250 void
 251 dnssd_getaddrinfo_set_interface_index(dnssd_getaddrinfo_t gai, uint32_t interface_index);
 252
 253 /*!
 254  *      @brief
 255  *              Specifies the types of addresses to which to resolve the hostname.
 256  *
 257  *      @param gai
 258  *              The getaddrinfo object.
 259  *
 260  *      @param protocols
 261  *              Protocols.
 262  *
 263  *      @discussion
 264  *              Set <code>protocols</code> to <code>kDNSServiceProtocol_IPv4</code> to resolve the hostname to IPv4 addresses.
 265  *
 266  *              Set <code>protocols</code> to <code>kDNSServiceProtocol_IPv6</code> to resolve the hostname to IPv6 addresses.
 267  *
 268  *              Set <code>protocols</code> to <code>kDNSServiceProtocol_IPv4 | kDNSServiceProtocol_IPv6</code> to resolve the
 269  *              hostname to both IPv4 and IPv6 addresses.
 270  *
 271  *              Set <code>protocols</code> to 0 to limit resolution to addresses of protocols of which the host has routable
 272  *              addresses. That is, an attempt will be made to resolve the hostname to IPv4 addresses if and only if the host
 273  *              has a routable IPv4 address. Likewise, an attempt will be made to resolve the hostname to IPv6 addresses if and
 274  *              only if the host has a routable IPv6 address.
 275  *
 276  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 277  */
 278 DNSSD_AVAILABLE
 279 void
 280 dnssd_getaddrinfo_set_protocols(dnssd_getaddrinfo_t gai, DNSServiceProtocol protocols);
 281
 282 /*!
 283  *      @brief
 284  *              Sets the process ID (PID) of the process on whose behalf the getaddrinfo operation is being performed.
 285  *
 286  *      @param gai
 287  *              The getaddrinfo object.
 288  *
 289  *      @param pid
 290  *              PID of the process being represented.
 291  *
 292  *      @discussion
 293  *              If a delegate PID is set, then the calling process must have the proper entitlement in order for the
 294  *              getaddrinfo operation to not fail with a kDNSServiceErr_NotAuth error.
 295  *
 296  *              This function is an alternative to <code>dnssd_getaddrinfo_set_delegate_uuid()</code>.
 297  *              This function is an alternative to <code>dnssd_getaddrinfo_set_delegate_audit_token()</code>.
 298  *
 299  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 300  */
 301 DNSSD_AVAILABLE
 302 void
 303 dnssd_getaddrinfo_set_delegate_pid(dnssd_getaddrinfo_t gai, pid_t pid);
 304
 305 /*!
 306  *      @brief
 307  *              Sets the UUID of the process on whose behalf the getaddrinfo operation is being performed.
 308  *
 309  *      @param gai
 310  *              The getaddrinfo object.
 311  *
 312  *      @param uuid
 313  *              UUID of the process being represented.
 314  *
 315  *      @discussion
 316  *              If a delegate UUID is set, then the calling process must have the proper entitlement in order for the
 317  *              getaddrinfo operation to not fail with the <code>kDNSServiceErr_NotAuth</code> error.
 318  *
 319  *              This function is an alternative to <code>dnssd_getaddrinfo_set_delegate_pid()</code>.
 320  *              This function is an alternative to <code>dnssd_getaddrinfo_set_delegate_audit_token()</code>.
 321  *
 322  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 323  */
 324 DNSSD_AVAILABLE
 325 void
 326 dnssd_getaddrinfo_set_delegate_uuid(dnssd_getaddrinfo_t gai, uuid_t _Nonnull uuid);
 327
 328 #define DNSSD_GETADDRINFO_SUPPORTS_DELEGATE_AUDIT_TOKEN 1
 329
 330 /*!
 331  *      @brief
 332  *              Sets the audit token of the process on whose behalf the getaddrinfo operation is being performed.
 333  *
 334  *      @param gai
 335  *              The getaddrinfo object.
 336  *
 337  *      @param audit_token
 338  *              audit token of the process being represented.
 339  *
 340  *      @discussion
 341  *              If a delegate audit token is set, then the calling process must have the proper entitlement in order for the
 342  *              getaddrinfo operation to not fail with the <code>kDNSServiceErr_NotAuth</code> error.
 343  *
 344  *              This function is an alternative to <code>dnssd_getaddrinfo_set_delegate_pid()</code>.
 345  *              This function is an alternative to <code>dnssd_getaddrinfo_set_delegate_uuid()</code>.
 346  *
 347  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 348  */
 349 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 350 void
 351 dnssd_getaddrinfo_set_delegate_audit_token(dnssd_getaddrinfo_t gai, audit_token_t audit_token);
 352
 353 /*!
 354  *      @brief
 355  *              Specifies whether or not getaddrinfo results (of types <code>dnssd_getaddrinfo_result_type_add</code> and
 356  *              <code>dnssd_getaddrinfo_result_type_expired</code>) should include authentication tags from the stub resolver.
 357  *
 358  *      @param gai
 359  *              The getaddrinfo object.
 360  *
 361  *      @param need
 362  *              Pass <code>true</code> if authenticated results are needed, otherwise, pass <code>false</code>.
 363  *
 364  *      @discussion
 365  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 366  */
 367 DNSSD_AVAILABLE
 368 void
 369 dnssd_getaddrinfo_set_need_authenticated_results(dnssd_getaddrinfo_t gai, bool need);
 370
 371 #define DNSSD_GETADDRINFO_SUPPORTS_ENCRYPTED_QUERIES 1
 372
 373 /*!
 374  *      @brief
 375  *              Specifies whether or not getaddrinfo queries must use encrypted transports to the next DNS server.
 376  *
 377  *      @param gai
 378  *              The getaddrinfo object.
 379  *
 380  *      @param need
 381  *              Pass <code>true</code> if encrypted queries are required, otherwise, pass <code>false</code>.
 382  *
 383  *      @param fallback_config
 384  *              If not NULL, specify a custom resolver configuration to use if no encrypted resolver configuation is otherwise
 385  *              available.
 386  *
 387  *      @discussion
 388  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 389  */
 390 DNSSD_AVAILABLE
 391 void
 392 dnssd_getaddrinfo_set_need_encrypted_query(dnssd_getaddrinfo_t gai, bool need, _Nullable xpc_object_t fallback_config);
 393
 394 /*!
 395  *      @brief
 396  *              Add a resolver UUID that represents a resolver configuration registered with the system that should
 397  *              be applied to this resolution. Multiple UUIDs can be set.
 398  *
 399  *      @param gai
 400  *              The getaddrinfo object.
 401  *
 402  *      @param uuid
 403  *              UUID of a resolver configuration registered with the system.
 404  *
 405  *      @discussion
 406  *              This function has no effect on a getaddrinfo object that has been activated or invalidated.
 407
 408  */
 409 DNSSD_AVAILABLE
 410 void
 411 dnssd_getaddrinfo_add_resolver_uuid(dnssd_getaddrinfo_t gai, uuid_t _Nonnull uuid);
 412
 413 /*!
 414  *      @brief
 415  *              Activates a getaddrinfo object.
 416  *
 417  *      @param gai
 418  *              The getaddrinfo object.
 419  *
 420  *      @discussion
 421  *              This function has no effect on a getaddrinfo object that has already been activated or has been invalidated.
 422  */
 423 DNSSD_AVAILABLE
 424 void
 425 dnssd_getaddrinfo_activate(dnssd_getaddrinfo_t gai);
 426
 427 /*!
 428  *      @brief
 429  *              Asynchronously invalidates a getaddrinfo object.
 430  *
 431  *      @param gai
 432  *              The getaddrinfo object.
 433  *
 434  *      @discussion
 435  *              As a result of calling this function, the getaddrinfo object's event handler will be invoked with a
 436  *              <code>dnssd_event_invalidated</code> event. After this, the object's event and result handlers will never be
 437  *              invoked again.
 438  *
 439  *              This function has no effect on a getaddrinfo object that has already been invalidated.
 440  */
 441 DNSSD_AVAILABLE
 442 void
 443 dnssd_getaddrinfo_invalidate(dnssd_getaddrinfo_t gai);
 444
 445 /*!
 446  *      @brief
 447  *              Handler for getaddrinfo results.
 448  *
 449  *      @param result_array
 450  *              C array of getaddrinfo results.
 451  *
 452  *      @param result_count
 453  *              Size of the array in terms of number of results.
 454  */
 455 typedef void (^dnssd_getaddrinfo_result_handler_t)(dnssd_getaddrinfo_result_t _Nonnull * _Nonnull result_array,
 456                                                                                                    size_t result_count);
 457
 458 /*!
 459  *      @brief
 460  *              Specifies a getaddrinfo object's result handler.
 461  *
 462  *      @param gai
 463  *              The getaddrinfo object.
 464  *
 465  *      @param handler
 466  *              Result handler.
 467  */
 468 DNSSD_AVAILABLE
 469 void
 470 dnssd_getaddrinfo_set_result_handler(dnssd_getaddrinfo_t gai, dnssd_getaddrinfo_result_handler_t _Nullable handler);
 471
 472 /*!
 473  *      @brief
 474  *              Events that can occur during the lifetime of a getaddrinfo object.
 475  */
 476 typedef enum {
 477         /*! @const dnssd_event_error An error occurred. */
 478         dnssd_event_error               = 1,
 479         /*! @const dnssd_event_remove_all All results prior to this event are no longer valid. */
 480         dnssd_event_remove_all  = 2,
 481         /*! @const dnssd_event_invalidated The object has been invalidated. */
 482         dnssd_event_invalidated = 3,
 483 } dnssd_event_t;
 484
 485 /*!
 486  *      @brief
 487  *              Handler for getaddrinfo events.
 488  *
 489  *      @param event
 490  *              Event.
 491  *
 492  *      @param error
 493  *              The error associated with a <code>dnssd_event_error</code> event. Ignore for all other types of events.
 494  *
 495  *      @discussion
 496  *              After a <code>dnssd_event_invalidated</code> event, a getaddrinfo object's result and event handlers will never
 497  *              be invoked again.
 498  */
 499 typedef void (^dnssd_event_handler_t)(dnssd_event_t event, DNSServiceErrorType error);
 500
 501 /*!
 502  *      @brief
 503  *              Sets a getaddrinfo object's event handler.
 504  *
 505  *      @param gai
 506  *              The getaddrinfo object.
 507  *
 508  *      @param handler
 509  *              Event handler.
 510  */
 511 DNSSD_AVAILABLE
 512 void
 513 dnssd_getaddrinfo_set_event_handler(dnssd_getaddrinfo_t gai, dnssd_event_handler_t _Nullable handler);
 514
 515 /*!
 516  *      @brief
 517  *              Types of getaddrinfo results.
 518  */
 519 typedef enum {
 520         /*! @const dnssd_getaddrinfo_result_type_add The contained hostname and address pair is valid. */
 521         dnssd_getaddrinfo_result_type_add                               = 1,
 522         /*! @const dnssd_getaddrinfo_result_type_remove The contained hostname and address pair is no longer valid. */
 523         dnssd_getaddrinfo_result_type_remove                    = 2,
 524         /*! @const dnssd_getaddrinfo_result_type_no_address The contained hostname has no address of a particular type. */
 525         dnssd_getaddrinfo_result_type_no_address                = 3,
 526         /*! @const dnssd_getaddrinfo_result_type_expired A hostname and address pair contained came from an expired cached record and may no longer be valid. */
 527         dnssd_getaddrinfo_result_type_expired                   = 4,
 528         /*! @const dnssd_getaddrinfo_result_type_service_binding A hostname has associated service binding information. */
 529         dnssd_getaddrinfo_result_type_service_binding   = 5,
 530 } dnssd_getaddrinfo_result_type_t;
 531
 532 /*!
 533  *      @brief
 534  *              Gets a getaddrinfo result's type.
 535  *
 536  *      @param gai_result
 537  *              The getaddrinfo result.
 538  *
 539  *      @result
 540  *              Result type.
 541  */
 542 DNSSD_AVAILABLE
 543 dnssd_getaddrinfo_result_type_t
 544 dnssd_getaddrinfo_result_get_type(dnssd_getaddrinfo_result_t gai_result);
 545
 546 /*!
 547  *      @brief
 548  *              Gets a getaddrinfo result's actual hostname.
 549  *
 550  *      @param gai_result
 551  *              The getaddrinfo result.
 552  *
 553  *      @result
 554  *              The getaddrinfo result's actual hostname.
 555  *
 556  *      @discussion
 557  *              The hostname returned by this function is the canonical name of the hostname that was requested. In other
 558  *              words, it's the canonical name of the hostname set with <code>dnssd_getaddrinfo_set_hostname()</code>.
 559  *
 560  *              The pointer returned by this function is valid until the getaddrinfo result is released.
 561  */
 562 DNSSD_AVAILABLE
 563 const char *
 564 dnssd_getaddrinfo_result_get_actual_hostname(dnssd_getaddrinfo_result_t gai_result);
 565
 566 /*!
 567  *      @brief
 568  *              Gets a getaddrinfo result's address.
 569  *
 570  *      @param gai_result
 571  *              The getaddrinfo result.
 572  *
 573  *      @result
 574  *              The getaddrinfo result's address as a sockaddr structure.
 575  *
 576  *      @discussion
 577  *              For getaddrinfo results of type <code>dnssd_getaddrinfo_result_type_no_address</code>, the sockaddr structure's
 578  *              sa_family member variable can be used to determine the type of address that the hostname lacks.
 579  */
 580 DNSSD_AVAILABLE
 581 const struct sockaddr *
 582 dnssd_getaddrinfo_result_get_address(dnssd_getaddrinfo_result_t gai_result);
 583
 584 /*!
 585  *      @brief
 586  *              Gets a getaddrinfo result's hostname.
 587  *
 588  *      @param gai_result
 589  *              The getaddrinfo result.
 590  *
 591  *      @result
 592  *              The getaddrinfo result's hostname.
 593  *
 594  *      @discussion
 595  *              The hostname returned by this function is the hostname whose resolution was requested. In other words, it's
 596  *              equal to the hostname set with <code>dnssd_getaddrinfo_set_hostname()</code>.
 597  *
 598  *              The pointer returned by this function is valid until the getaddrinfo result is released.
 599  */
 600 DNSSD_AVAILABLE
 601 const char *
 602 dnssd_getaddrinfo_result_get_hostname(dnssd_getaddrinfo_result_t gai_result);
 603
 604 /*!
 605  *      @brief
 606  *              Gets the interface index to which a getaddrinfo result pertains.
 607  *
 608  *      @param gai_result
 609  *              The getaddrinfo result.
 610  *
 611  *      @result
 612  *              For hostnames that were resolved via mDNS, the return value is the index of the interface via which the
 613  *              hostname was resolved. For hostnames that were resolved via DNS, the return value is 0.
 614  */
 615 DNSSD_AVAILABLE
 616 uint32_t
 617 dnssd_getaddrinfo_result_get_interface_index(dnssd_getaddrinfo_result_t gai_result);
 618
 619 /*!
 620  *      @brief
 621  *              Gets a getaddrinfo result's authentication tag.
 622  *
 623  *      @param gai_result
 624  *              The getaddrinfo result.
 625  *
 626  *      @param out_length
 627  *              If non-NULL, gets set to the length of the authentication tag.
 628  *
 629  *      @result
 630  *              A pointer to the getaddrinfo result's authentication tag, if it has one. Otherwise, NULL.
 631  *
 632  *      @discussion
 633  *              The returned pointer, if non-NULL, is valid until the getaddrinfo result is released.
 634  */
 635 DNSSD_AVAILABLE
 636 const void * _Nullable
 637 dnssd_getaddrinfo_result_get_authentication_tag(dnssd_getaddrinfo_result_t gai_result, size_t *_Nullable out_length);
 638
 639 /*!
 640  *      @brief
 641  *              Types of protocols used for getaddrinfo results.
 642  */
 643 typedef enum {
 644         /*! @const dnssd_getaddrinfo_result_protocol_udp The answers were retrieved using UDP. */
 645         dnssd_getaddrinfo_result_protocol_udp           = 1,
 646         /*! @const dnssd_getaddrinfo_result_protocol_tcp The answers were retrieved using TCP. */
 647         dnssd_getaddrinfo_result_protocol_tcp           = 2,
 648         /*! @const dnssd_getaddrinfo_result_protocol_tls The answers were retrieved using DNS over TLS. */
 649         dnssd_getaddrinfo_result_protocol_tls           = 3,
 650         /*! @const dnssd_getaddrinfo_result_protocol_https The answers were retrieved using DNS over HTTPS. */
 651         dnssd_getaddrinfo_result_protocol_https         = 4,
 652 } dnssd_getaddrinfo_result_protocol_t;
 653
 654 #define DNSSD_GETADDRINFO_HAS_GET_PROTOCOL 1
 655
 656 /*!
 657  *      @brief
 658  *              Gets a getaddrinfo result's protocol.
 659  *
 660  *      @param gai_result
 661  *              The getaddrinfo result.
 662  *
 663  *      @result
 664  *              Result protocol.
 665  */
 666 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 667 dnssd_getaddrinfo_result_protocol_t
 668 dnssd_getaddrinfo_result_get_protocol(dnssd_getaddrinfo_result_t gai_result);
 669
 670 #define DNSSD_GETADDRINFO_HAS_GET_PROVIDER_NAME 1
 671
 672 /*!
 673  *      @brief
 674  *              Gets a getaddrinfo result's DNS provider name, if applicable.
 675  *
 676  *      @param gai_result
 677  *              The getaddrinfo result.
 678  *
 679  *      @result
 680  *              DNS provider name.
 681  */
 682 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 683 const char * _Nullable
 684 dnssd_getaddrinfo_result_get_provider_name(dnssd_getaddrinfo_result_t gai_result);
 685
 686 /*!
 687  *      @brief
 688  *              Checks if a getaddrinfo result has valid service binding information.
 689  *
 690  *      @param gai_result
 691  *              The getaddrinfo result.
 692  *
 693  *      @result
 694  *              Returns true if service binding information is valid.
 695  */
 696 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 697 bool
 698 dnssd_getaddrinfo_result_service_is_valid(dnssd_getaddrinfo_result_t gai_result);
 699
 700 #define DNSSD_GETADDRINFO_SERVICE_PRIORITY_ALIAS 0
 701
 702 /*!
 703  *      @brief
 704  *              Gets a getaddrinfo result's service binding priority.
 705  *
 706  *      @param gai_result
 707  *              The getaddrinfo result.
 708  *
 709  *      @result
 710  *              Service binding priority.
 711  */
 712 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 713 uint16_t
 714 dnssd_getaddrinfo_result_get_service_priority(dnssd_getaddrinfo_result_t gai_result);
 715
 716 /*!
 717  *      @brief
 718  *              Gets a getaddrinfo result's service binding port.
 719  *
 720  *      @param gai_result
 721  *              The getaddrinfo result.
 722  *
 723  *      @result
 724  *              Service binding port.
 725  */
 726 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 727 uint16_t
 728 dnssd_getaddrinfo_result_get_service_port(dnssd_getaddrinfo_result_t gai_result);
 729
 730 /*!
 731  *      @brief
 732  *              Gets a getaddrinfo result's service name.
 733  *
 734  *      @param gai_result
 735  *              The getaddrinfo result.
 736  *
 737  *      @result
 738  *              String containing the service binding name.
 739  */
 740 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 741 const char * _Nullable
 742 dnssd_getaddrinfo_result_get_service_name(dnssd_getaddrinfo_result_t gai_result);
 743
 744 /*!
 745  *      @brief
 746  *              Gets a getaddrinfo result's associated DoH URI if present.
 747  *
 748  *      @param gai_result
 749  *              The getaddrinfo result.
 750  *
 751  *      @result
 752  *              String containing a DoH URI, if present.
 753  */
 754 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 755 const char * _Nullable
 756 dnssd_getaddrinfo_result_get_doh_uri(dnssd_getaddrinfo_result_t gai_result);
 757
 758 /*!
 759  *      @brief
 760  *              Gets a getaddrinfo result's ECH (Encrypted Client Hello) configuration.
 761  *
 762  *      @param gai_result
 763  *              The getaddrinfo result.
 764  *
 765  *      @param out_length
 766  *              If non-NULL, gets set to the length of the ECH config.
 767  *
 768  *      @result
 769  *              A pointer to the getaddrinfo result's ECH config, if it has one. Otherwise, NULL.
 770  *
 771  *      @discussion
 772  *              The returned pointer, if non-NULL, is valid until the getaddrinfo result is released.
 773  */
 774 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 775 const void * _Nullable
 776 dnssd_getaddrinfo_result_get_ech_config(dnssd_getaddrinfo_result_t gai_result, size_t *_Nullable out_length);
 777
 778 #ifdef __BLOCKS__
 779
 780 typedef bool (^dnssd_getaddrinfo_enumerate_alpn_values_block_t)(const char *alpn);
 781
 782 /*!
 783  *      @brief
 784  *              Enumerates a getaddrinfo result's service binding ALPN (application layer protocol negotiation) hints.
 785  *
 786  *      @param gai_result
 787  *              The getaddrinfo result.
 788  *
 789  *      @param enumerator
 790  *              A block to invoke for each ALPN hint.
 791  */
 792 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 793 void
 794 dnssd_getaddrinfo_result_enumerate_alpn_values(dnssd_getaddrinfo_result_t gai_result,
 795                                                                                            DNSSD_NOESCAPE dnssd_getaddrinfo_enumerate_alpn_values_block_t enumerator);
 796
 797 typedef bool (^dnssd_getaddrinfo_enumerate_addresses_block_t)(const struct sockaddr *address);
 798
 799 /*!
 800  *      @brief
 801  *              Enumerates a getaddrinfo result's service address hints.
 802  *
 803  *      @param gai_result
 804  *              The getaddrinfo result.
 805  *
 806  *      @param enumerator
 807  *              A block to invoke for each address hint.
 808  */
 809 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 810 void
 811 dnssd_getaddrinfo_result_enumerate_service_address_hints(dnssd_getaddrinfo_result_t gai_result,
 812                                                                                                                  DNSSD_NOESCAPE dnssd_getaddrinfo_enumerate_addresses_block_t enumerator);
 813
 814 #endif // __BLOCKS__
 815
 816
 817 /*!
 818  *      @brief
 819  *              Gets the canonical names, if any, of a getaddrinfo result's hostname.
 820  *
 821  *      @param gai_result
 822  *              The getaddrinfo result.
 823  *
 824  *      @result
 825  *              An array containing zero or more canonical names.
 826  *
 827  *      @discussion
 828  *              Canonical names will not be provided for a getaddrinfo objects's results unless the
 829  *              <code>kDNSServiceFlagsReturnIntermediates</code> flag was set for the getaddrinfo object with
 830  *              <code>dnssd_getaddrinfo_set_flags()</code>.
 831  *
 832  *              The canonical names in the array are ordered in the following way. For non-empty arrays, the first
 833  *              canonical name in the array is the immediate canonical name of the getaddrinfo operation's hostname.
 834  *              For all canonical names beyond the first, a canonical name is the immediate canonical name of the
 835  *              canonical name that precedes it in the array.
 836  *
 837  *              For hostnames that have no canonical names, i.e., hostnames that aren't aliases, an empty array will be
 838  *              returned.
 839  *
 840  *              The array returned by this function is guaranteed to be valid during the lifetime of the getaddrinfo
 841  *              result. If the array is needed beyond the lifetime of the getaddrinfo result, then the array must be
 842  *              retained.
 843  */
 844 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 845 dnssd_cname_array_t
 846 dnssd_getaddrinfo_result_get_cnames(dnssd_getaddrinfo_result_t gai_result);
 847
 848 /*!
 849  *      @brief
 850  *              Determines whether a getaddrinfo result was the product of cached DNS records, i.e., no additional DNS
 851  *              queries needed to be sent by mDNSResponder to provide the result.
 852  *
 853  *      @param gai_result
 854  *              The getaddrinfo result.
 855  *
 856  *      @result
 857  *              Returns <code>true</code> if the result came from cached DNS records, otherwise, returns
 858  *              <code>false</code>.
 859  */
 860 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 861 bool
 862 dnssd_getaddrinfo_result_is_from_cache(dnssd_getaddrinfo_result_t gai_result);
 863
 864 /*!
 865  *      @brief
 866  *              Gets the count of canonical names in a canonical name array.
 867  *
 868  *      @param cname_array
 869  *              The canonical name array.
 870  *
 871  *      @result
 872  *              The count of canonical names in the canonical name array.
 873  */
 874 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 875 size_t
 876 dnssd_cname_array_get_count(dnssd_cname_array_t cname_array);
 877
 878 /*!
 879  *      @brief
 880  *              Gets the canonical name at a specific index in a canonical name array.
 881  *
 882  *      @param cname_array
 883  *              The canonical name array.
 884  *
 885  *      @param index
 886  *              The zero-based index of the canonical name to get. The index must be no greater than the array's count,
 887  *              i.e., the value returned by <code>dnssd_cname_array_get_count()</code> for the array.
 888  *
 889  *      @result
 890  *              The canonical name at the specified index as a C string.
 891  *
 892  *      @discussion
 893  *              The pointer returned by this function is guaranteed to be valid until the array is released.
 894  */
 895 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 896 const char * _Nullable
 897 dnssd_cname_array_get_cname(dnssd_cname_array_t cname_array, size_t index);
 898
 899 static inline const char *
 900 dnssd_getaddrinfo_result_type_to_string(dnssd_getaddrinfo_result_type_t result)
 901 {
 902         switch (result) {
 903                 case dnssd_getaddrinfo_result_type_add:                         return "Add";
 904                 case dnssd_getaddrinfo_result_type_remove:                      return "Remove";
 905                 case dnssd_getaddrinfo_result_type_no_address:          return "NoAddress";
 906                 case dnssd_getaddrinfo_result_type_expired:                     return "Expired";
 907                 case dnssd_getaddrinfo_result_type_service_binding:     return "ServiceBinding";
 908                 default:                                                                                        return "?";
 909         }
 910 }
 911
 912 static inline const char *
 913 dnssd_getaddrinfo_result_protocol_to_string(dnssd_getaddrinfo_result_protocol_t protocol)
 914 {
 915         switch (protocol) {
 916                 case dnssd_getaddrinfo_result_protocol_udp:             return "UDP";
 917                 case dnssd_getaddrinfo_result_protocol_tcp:             return "TCP";
 918                 case dnssd_getaddrinfo_result_protocol_tls:             return "TLS";
 919                 case dnssd_getaddrinfo_result_protocol_https:   return "HTTPS";
 920                 default:                                                                                return "?";
 921         }
 922 }
 923
 924 static inline const char *
 925 dnssd_event_to_string(dnssd_event_t event)
 926 {
 927         switch (event) {
 928                 case dnssd_event_remove_all:    return "RemoveAll";
 929                 case dnssd_event_error:                 return "Error";
 930                 case dnssd_event_invalidated:   return "Invalidated";
 931                 default:                                                return "?";
 932         }
 933 }
 934
 935 __END_DECLS
 936
 937 DNSSD_ASSUME_NONNULL_END
 938
 939
 940 #if OS_OBJECT_USE_OBJC && __has_feature(objc_arc)
 941         #define dnssd_retain_arc_safe(OBJ)      (OBJ)
 942         #define dnssd_release_arc_safe(OBJ)     do {} while (0)
 943 #else
 944         #define dnssd_retain_arc_safe(OBJ)      dnssd_retain(OBJ)
 945         #define dnssd_release_arc_safe(OBJ)     dnssd_release(OBJ)
 946 #endif
 947
 948 #define dnssd_getaddrinfo_forget(X)                             \
 949         do {                                                                            \
 950                 if (*(X)) {                                                             \
 951                         dnssd_getaddrinfo_invalidate(*(X));     \
 952                         dnssd_release_arc_safe(*(X));           \
 953                         *(X) = NULL;                                            \
 954                 }                                                                               \
 955         } while (0)
 956
 957 #endif  // __DNSSD_PRIVATE_H__