mDNSMacOSX/dnssd_xpc.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_XPC_H__
  18 #define __DNSSD_XPC_H__
  19
  20 #include <CoreUtils/CommonServices.h>
  21 #include <dns_sd.h>
  22 #include <xpc/xpc.h>
  23
  24 #define DNSSD_MACH_SERVICE_NAME "com.apple.dnssd.service"
  25
  26 #define DNSSD_COMMAND_GETADDRINFO       "getaddrinfo"
  27 #define DNSSD_COMMAND_STOP                      "stop"
  28
  29 CU_ASSUME_NONNULL_BEGIN
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /*!
  36  *      @brief
  37  *              Gets command as a C string from XPC message.
  38  *
  39  *      @param msg
  40  *              XPC message.
  41  *
  42  *      @result
  43  *              Command, if present. Otherwise, NULL.
  44  */
  45 const char * _Nullable
  46 dnssd_xpc_message_get_command(xpc_object_t msg);
  47
  48 /*!
  49  *      @brief
  50  *              Gets error code from XPC message.
  51  *
  52  *      @param msg
  53  *              XPC message.
  54  *
  55  *      @param out_valid
  56  *              If non-NULL, set to true if value is present and of correct type, otherwise, set to false.
  57  *
  58  *      @result
  59  *              Error code, if present. Otherwise, 0.
  60  */
  61 DNSServiceErrorType
  62 dnssd_xpc_message_get_error(xpc_object_t msg, bool * _Nullable out_valid);
  63
  64 /*!
  65  *      @brief
  66  *              Gets command instance ID from XPC message.
  67  *
  68  *      @param msg
  69  *              XPC message.
  70  *
  71  *      @param out_valid
  72  *              If non-NULL, set to true if value is present and of correct type, otherwise, set to false.
  73  *
  74  *      @result
  75  *              ID, if present. Otherwise, 0.
  76  */
  77 uint64_t
  78 dnssd_xpc_message_get_id(xpc_object_t msg, bool * _Nullable out_valid);
  79
  80 /*!
  81  *      @brief
  82  *              Gets command parameter dictionary from XPC message.
  83  *
  84  *      @param msg
  85  *              XPC message.
  86  *
  87  *      @result
  88  *              Command parameter dictionary, if present. Otherwise, NULL.
  89  */
  90 xpc_object_t _Nullable
  91 dnssd_xpc_message_get_parameters(xpc_object_t msg);
  92
  93 /*!
  94  *      @brief
  95  *              Gets result array from XPC message.
  96  *
  97  *      @param msg
  98  *              XPC message.
  99  *
 100  *      @result
 101  *              Result array, if present. Otherwise, NULL.
 102  */
 103 xpc_object_t _Nullable
 104 dnssd_xpc_message_get_results(xpc_object_t msg);
 105
 106 /*!
 107  *      @brief
 108  *              Sets command in XPC message.
 109  *
 110  *      @param msg
 111  *              XPC message.
 112  *
 113  *      @param command
 114  *              Command as a C string.
 115  */
 116 void
 117 dnssd_xpc_message_set_command(xpc_object_t msg, const char *command);
 118
 119 /*!
 120  *      @brief
 121  *              Sets error code in XPC message.
 122  *
 123  *      @param msg
 124  *              XPC message.
 125  *
 126  *      @param error
 127  *              Error code.
 128  */
 129 void
 130 dnssd_xpc_message_set_error(xpc_object_t msg, DNSServiceErrorType error);
 131
 132 /*!
 133  *      @brief
 134  *              Sets command instance ID in XPC message.
 135  *
 136  *      @param msg
 137  *              XPC message.
 138  *
 139  *      @param ident
 140  *              Command instance ID.
 141  */
 142 void
 143 dnssd_xpc_message_set_id(xpc_object_t msg, uint64_t ident);
 144
 145 /*!
 146  *      @brief
 147  *              Sets command parameters dictionary in XPC message.
 148  *
 149  *      @param msg
 150  *              XPC message.
 151  *
 152  *      @param params
 153  *              Command parameters dictionary.
 154  */
 155 void
 156 dnssd_xpc_message_set_parameters(xpc_object_t msg, xpc_object_t params);
 157
 158 /*!
 159  *      @brief
 160  *              Sets command result array in XPC message.
 161  *
 162  *      @param msg
 163  *              XPC message.
 164  *
 165  *      @param results
 166  *              Command result array.
 167  */
 168 void
 169 dnssd_xpc_message_set_results(xpc_object_t msg, xpc_object_t results);
 170
 171 /*!
 172  *      @brief
 173  *              Gets delegate ID as a PID from a command parameters dictionary.
 174  *
 175  *      @param params
 176  *              Command parameters dictionary.
 177  *
 178  *      @param out_valid
 179  *              If non-NULL, set to true if value is present and of correct type, otherwise, set to false.
 180  *
 181  *      @result
 182  *              Delegate ID as PID, if present. Otherwise, 0.
 183  */
 184 pid_t
 185 dnssd_xpc_parameters_get_delegate_pid(xpc_object_t params, bool * _Nullable out_valid);
 186
 187 /*!
 188  *      @brief
 189  *              Gets delegate ID as a UUID from a command parameters dictionary.
 190  *
 191  *      @param params
 192  *              Command parameters dictionary.
 193  *
 194  *      @result
 195  *              Delegate ID as UUID, if present. Otherwise, NULL.
 196  */
 197 const uint8_t * _Nullable
 198 dnssd_xpc_parameters_get_delegate_uuid(xpc_object_t params);
 199
 200 /*!
 201  *      @brief
 202  *              Gets flags from a command parameters dictionary.
 203  *
 204  *      @param params
 205  *              Command parameters dictionary.
 206  *
 207  *      @param out_valid
 208  *              If non-NULL, set to true if value is present and of correct type, otherwise, set to false.
 209  *
 210  *      @result
 211  *              Flags, if present. Otherwise, 0.
 212  */
 213 DNSServiceFlags
 214 dnssd_xpc_parameters_get_flags(xpc_object_t params, bool * _Nullable out_valid);
 215
 216 /*!
 217  *      @brief
 218  *              Gets hostname from a command parameters dictionary.
 219  *
 220  *      @param params
 221  *              Command parameters dictionary.
 222  *
 223  *      @result
 224  *              Hostname, if present, as an XPC string object. Otherwise, NULL.
 225  */
 226 xpc_object_t _Nullable
 227 dnssd_xpc_parameters_get_hostname_object(xpc_object_t params);
 228
 229 /*!
 230  *      @brief
 231  *              Gets interface index from a command parameters dictionary.
 232  *
 233  *      @param params
 234  *              Command parameters dictionary.
 235  *
 236  *      @para out_valid
 237  *              If non-NULL, set to true if value is present and of correct type, otherwise, set to false.
 238  *
 239  *      @result
 240  *              Interface index, if present. Otherwise, 0.
 241  */
 242 uint32_t
 243 dnssd_xpc_parameters_get_interface_index(xpc_object_t params, bool * _Nullable out_valid);
 244
 245 /*!
 246  *      @brief
 247  *              Gets need_auth_tags boolean value from a command parameters dictionary.
 248  *
 249  *      @param params
 250  *              Command parameters dictionary.
 251  *
 252  *      @result
 253  *              A boolean value.
 254  */
 255 bool
 256 dnssd_xpc_parameters_get_need_authentication_tags(xpc_object_t params);
 257
 258 /*!
 259  *      @brief
 260  *              Gets protocols from a command parameters dictionary.
 261  *
 262  *      @param params
 263  *              Command parameters dictionary.
 264  *
 265  *      @param out_valid
 266  *              If non-NULL, set to true if value is present and of correct type, otherwise, set to false.
 267  *
 268  *      @result
 269  *              Protocols, if present. Otherwise, 0.
 270  */
 271 DNSServiceProtocol
 272 dnssd_xpc_parameters_get_protocols(xpc_object_t params, bool * _Nullable out_valid);
 273
 274 /*!
 275  *      @brief
 276  *              Sets delegate ID as a PID in a command parameters dictionary.
 277  *
 278  *      @param params
 279  *              Command parameters dictionary.
 280  *
 281  *      @param pid
 282  *              PID.
 283  */
 284 void
 285 dnssd_xpc_parameters_set_delegate_pid(xpc_object_t params, pid_t pid);
 286
 287 /*!
 288  *      @brief
 289  *              Sets delegate ID as a UUID in a command parameters dictionary.
 290  *
 291  *      @param params
 292  *              Command parameters dictionary.
 293  *
 294  *      @param uuid
 295  *              UUID.
 296  */
 297 void
 298 dnssd_xpc_parameters_set_delegate_uuid(xpc_object_t params, uuid_t _Nonnull uuid);
 299
 300 /*!
 301  *      @brief
 302  *              Sets flags in a command parameters dictionary.
 303  *
 304  *      @param params
 305  *              Command parameters dictionary.
 306  *
 307  *      @param flags
 308  *              Flags.
 309  */
 310 void
 311 dnssd_xpc_parameters_set_flags(xpc_object_t params, DNSServiceFlags flags);
 312
 313 /*!
 314  *      @brief
 315  *              Sets hostname in a command parameters dictionary.
 316  *
 317  *      @param params
 318  *              Command parameters dictionary.
 319  *
 320  *      @param hostname
 321  *              Hostname.
 322  */
 323 void
 324 dnssd_xpc_parameters_set_hostname(xpc_object_t params, const char *hostname);
 325
 326 /*!
 327  *      @brief
 328  *              Sets interface index in a command parameters dictionary.
 329  *
 330  *      @param params
 331  *              Command parameters dictionary.
 332  *
 333  *      @param interface_index
 334  *              Interface index.
 335  */
 336 void
 337 dnssd_xpc_parameters_set_interface_index(xpc_object_t params, uint32_t interface_index);
 338
 339 /*!
 340  *      @brief
 341  *              Sets whether mDNSResponder should include an authentication tag for each hostname resolution.
 342  *
 343  *      @param params
 344  *              Command parameters dictionary.
 345  *
 346  *      @param need
 347  *              Pass <code>true</code> to enable this behavior. Pass <code>false</code> to disable it.
 348  */
 349 void
 350 dnssd_xpc_parameters_set_need_authentication_tags(xpc_object_t params, bool need);
 351
 352 /*!
 353  *      @brief
 354  *              Sets protocols in a command parameters dictionary.
 355  *
 356  *      @param params
 357  *              Command parameters dictionary.
 358  *
 359  *      @param protocols
 360  *              Protocols.
 361  */
 362 void
 363 dnssd_xpc_parameters_set_protocols(xpc_object_t params, DNSServiceProtocol protocols);
 364
 365 /*!
 366  *      @brief
 367  *              Gets authentication tag from a command result dictionary.
 368  *
 369  *      @param result
 370  *              The command result dictionary.
 371  *
 372  *      @result
 373  *              Authentication tag, if present, as an XPC data object. Otherwise, NULL.
 374  */
 375 xpc_object_t _Nullable
 376 dnssd_xpc_result_get_authentication_tag_object(xpc_object_t result);
 377
 378 /*!
 379  *      @brief
 380  *              Gets error code from a command result dictionary.
 381  *
 382  *      @param result
 383  *              The command result dictionary.
 384  *
 385  *      @param out_valid
 386  *              If non-NULL, set to true if value is present and of correct type, otherwise, set to false.
 387  *
 388  *      @result
 389  *              Error code, if present. Otherwise, 0.
 390  */
 391 DNSServiceErrorType
 392 dnssd_xpc_result_get_error(xpc_object_t result, bool * _Nullable out_valid);
 393
 394 /*!
 395  *      @brief
 396  *              Gets flags from a command result dictionary.
 397  *
 398  *      @param result
 399  *              The command result dictionary.
 400  *
 401  *      @param out_valid
 402  *              If non-NULL, set to true if value is present and of correct type, otherwise, set to false.
 403  *
 404  *      @result
 405  *              Flags, if present. Otherwise, 0.
 406  */
 407 DNSServiceFlags
 408 dnssd_xpc_result_get_flags(xpc_object_t result, bool * _Nullable out_valid);
 409
 410 /*!
 411  *      @brief
 412  *              Gets interface index from a command result dictionary.
 413  *
 414  *      @param result
 415  *              The command result dictionary.
 416  *
 417  *      @param out_valid
 418  *              If non-NULL, set to true if value is present and of correct type, otherwise, set to false.
 419  *
 420  *      @result
 421  *              Interface index, if present. Otherwise, 0.
 422  */
 423 uint32_t
 424 dnssd_xpc_result_get_interface_index(xpc_object_t result, bool * _Nullable out_valid);
 425
 426 /*!
 427  *      @brief
 428  *              Gets record class from a command result dictionary.
 429  *
 430  *      @param result
 431  *              The command result dictionary.
 432  *
 433  *      @param out_valid
 434  *              If non-NULL, set to true if value is present and of correct type, otherwise, set to false.
 435  *
 436  *      @result
 437  *              Record class, if present. Otherwise, 0.
 438  */
 439 uint16_t
 440 dnssd_xpc_result_get_record_class(xpc_object_t result, bool * _Nullable out_valid);
 441
 442 /*!
 443  *      @brief
 444  *              Gets record data from a command result dictionary.
 445  *
 446  *      @param result
 447  *              The command result dictionary.
 448  *
 449  *      @result
 450  *              Record data, if present, as an XPC data object. Otherwise, NULL.
 451  */
 452 xpc_object_t _Nullable
 453 dnssd_xpc_result_get_record_data_object(xpc_object_t result);
 454
 455 /*!
 456  *      @brief
 457  *              Gets record name from a command result dictionary.
 458  *
 459  *      @param result
 460  *              The command result dictionary.
 461  *
 462  *      @result
 463  *              Record name, if present, as an XPC string object. Otherwise, NULL.
 464  */
 465 xpc_object_t _Nullable
 466 dnssd_xpc_result_get_record_name_object(xpc_object_t result);
 467
 468 /*!
 469  *      @brief
 470  *              Gets record type from a command result dictionary.
 471  *
 472  *      @param result
 473  *              The command result dictionary.
 474  *
 475  *      @param out_valid
 476  *              If non-NULL, set to true if value is present and of correct type, otherwise, set to false.
 477  *
 478  *      @result
 479  *              Record type, if present. Otherwise, 0.
 480  */
 481 uint16_t
 482 dnssd_xpc_result_get_record_type(xpc_object_t result, bool * _Nullable out_valid);
 483
 484 /*!
 485  *      @brief
 486  *              Sets the authentication tag in a command result dictionary.
 487  *
 488  *      @param result
 489  *              The command result dictionary.
 490  *
 491  *      @param auth_tag_ptr
 492  *              Pointer to the authentication tag.
 493  *
 494  *      @param auth_tag_len
 495  *              Length of the authentication tag.
 496  */
 497 void
 498 dnssd_xpc_result_set_authentication_tag(xpc_object_t result, const void *auth_tag_ptr, size_t auth_tag_len);
 499
 500 /*!
 501  *      @brief
 502  *              Sets the error code in a command result dictionary.
 503  *
 504  *      @param result
 505  *              The command result dictionary.
 506  *
 507  *      @param error
 508  *              Error code.
 509  */
 510 void
 511 dnssd_xpc_result_set_error(xpc_object_t result, DNSServiceErrorType error);
 512
 513 /*!
 514  *      @brief
 515  *              Sets flags in a command result dictionary.
 516  *
 517  *      @param result
 518  *              The command result dictionary.
 519  *
 520  *      @param flags
 521  *              Flags.
 522  */
 523 void
 524 dnssd_xpc_result_set_flags(xpc_object_t result, DNSServiceFlags flags);
 525
 526 /*!
 527  *      @brief
 528  *              Sets interface index in a command result dictionary.
 529  *
 530  *      @param result
 531  *              The command result dictionary.
 532  *
 533  *      @param interface_index
 534  *              Interface index.
 535  */
 536 void
 537 dnssd_xpc_result_set_interface_index(xpc_object_t result, uint32_t interface_index);
 538
 539 /*!
 540  *      @brief
 541  *              Sets record class in a command result dictionary.
 542  *
 543  *      @param result
 544  *              The command result dictionary.
 545  *
 546  *      @param class
 547  *              Record class.
 548  */
 549 void
 550 dnssd_xpc_result_set_record_class(xpc_object_t result, uint16_t class);
 551
 552 /*!
 553  *      @brief
 554  *              Sets the record data in a command result dictionary.
 555  *
 556  *      @param result
 557  *              The command result dictionary.
 558  *
 559  *      @param data_ptr
 560  *              Pointer to the record data.
 561  *
 562  *      @param data_len
 563  *              Length of the record data.
 564  */
 565 void
 566 dnssd_xpc_result_set_record_data(xpc_object_t result, const void * _Nullable data_ptr, size_t data_len);
 567
 568 /*!
 569  *      @brief
 570  *              Sets record name in a command result dictionary.
 571  *
 572  *      @param result
 573  *              The command result dictionary.
 574  *
 575  *      @param name
 576  *              Record name.
 577  */
 578 void
 579 dnssd_xpc_result_set_record_name(xpc_object_t result, const char *name);
 580
 581 /*!
 582  *      @brief
 583  *              Sets record type in a command result dictionary.
 584  *
 585  *      @param result
 586  *              The command result dictionary.
 587  *
 588  *      @param type
 589  *              Record type.
 590  */
 591 void
 592 dnssd_xpc_result_set_record_type(xpc_object_t result, uint16_t type);
 593
 594 #ifdef __cplusplus
 595 }
 596 #endif
 597
 598 CU_ASSUME_NONNULL_END
 599
 600 #endif  // __DNSSD_XPC_H__