mDNSMacOSX/mdns_objects/mdns_message.h

   1 /*
   2  * Copyright (c) 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 __MDNS_MESSAGE_H__
  18 #define __MDNS_MESSAGE_H__
  19
  20 #include "mdns_base.h"
  21
  22 #include <dispatch/dispatch.h>
  23 #include <MacTypes.h>
  24
  25 #define MDNS_MESSAGE_SUBKIND_DECLARE(NAME)      MDNS_DECL_SUBKIND(NAME ## _message, message)
  26
  27 MDNS_DECL(message);
  28 MDNS_MESSAGE_SUBKIND_DECLARE(query);
  29
  30 MDNS_ASSUME_NONNULL_BEGIN
  31
  32 #if OS_OBJECT_USE_OBJC
  33         typedef mdns_message_t  mdns_any_message_t;
  34 #else
  35         #if defined(__cplusplus)
  36                 typedef void *  mdns_any_message_t;
  37         #else
  38                 typedef union {
  39                         MDNS_UNION_MEMBER(message);
  40                         MDNS_UNION_MEMBER(query_message);
  41                 } mdns_any_message_t __attribute__((__transparent_union__));
  42         #endif
  43 #endif
  44
  45 /*!
  46  *      @typedef mdns_message_init_options_t
  47  *
  48  *      @brief
  49  *              Creates a DNS message object from a dispatch_data object.
  50  *
  51  *      @constant mdns_message_init_option_null
  52  *              Represents no option.
  53  *
  54  *      @constant mdns_message_init_option_disable_header_printing
  55  *              Disable message header printing in description.
  56  */
  57 OS_CLOSED_OPTIONS(mdns_message_init_options, uint32_t,
  58         mdns_message_init_option_null                                           = 0,            // Null option.
  59         mdns_message_init_option_disable_header_printing        = (1U << 0)     // Disable message header printing in description.
  60 );
  61
  62 __BEGIN_DECLS
  63
  64 /*!
  65  *      @brief
  66  *              Creates a DNS message object from a dispatch_data object.
  67  *
  68  *      @param data
  69  *              A dispatch_data object containing a DNS message in wire format.
  70  *
  71  *      @param options
  72  *              Message initialization options.
  73  *
  74  *      @result
  75  *              A new message object, or NULL if there was a lack of resources.
  76  */
  77 MDNS_RETURNS_RETAINED MDNS_WARN_RESULT
  78 mdns_message_t _Nullable
  79 mdns_message_create_with_dispatch_data(dispatch_data_t data, mdns_message_init_options_t options);
  80
  81 /*!
  82  *      @brief
  83  *              Gets a message's data in wire format as a dispatch_data object.
  84  *
  85  *      @param message
  86  *              The message.
  87  */
  88 dispatch_data_t
  89 mdns_message_get_dispatch_data(mdns_any_message_t message);
  90
  91 /*!
  92  *      @brief
  93  *              Returns a pointer to the first byte of a message's data in wire format.
  94  *
  95  *      @param message
  96  *              The message.
  97  */
  98 const uint8_t * _Nullable
  99 mdns_message_get_byte_ptr(mdns_any_message_t message);
 100
 101 /*!
 102  *      @brief
 103  *              Returns the length of a message's data in wire format.
 104  *
 105  *      @param message
 106  *              The message.
 107  */
 108 size_t
 109 mdns_message_get_length(mdns_any_message_t message);
 110
 111 /*!
 112  *      @brief
 113  *              Creates a DNS query message object.
 114  *
 115  *      @param options
 116  *              Message initialization options.
 117  *
 118  *      @result
 119  *              A new query message object, or NULL if there was a lack of resources.
 120  *
 121  *      @discussion
 122  *              A query message starts out in a mutable state. Functions such as mdns_query_message_set_qname(),
 123  *              mdns_query_message_set_qtype(), and mdns_query_message_set_qclass() can be used to modify the message.
 124  *              After all the desired modifications are made, the mdns_query_message_construct() function should be used
 125  *              to finalize them.
 126  */
 127 MDNS_RETURNS_RETAINED MDNS_WARN_RESULT
 128 mdns_query_message_t _Nullable
 129 mdns_query_message_create(mdns_message_init_options_t options);
 130
 131 /*!
 132  *      @brief
 133  *              Sets the QNAME of a query message's question.
 134  *
 135  *      @param message
 136  *              The query message.
 137  *
 138  *      @param qname
 139  *              The QNAME in wire format.
 140  *
 141  *      @result
 142  *              kNoErr if the QNAME was successfully set. Otherwise, an error code that indicates the error that was
 143  *              encountered.
 144  *
 145  *      @discussion
 146  *              This function has no effect on a query message that has been constructed.
 147  */
 148 OSStatus
 149 mdns_query_message_set_qname(mdns_query_message_t message, const uint8_t *qname);
 150
 151 /*!
 152  *      @brief
 153  *              Sets the QTYPE of a query message's question.
 154  *
 155  *      @param message
 156  *              The query message.
 157  *
 158  *      @param qtype
 159  *              The QTYPE.
 160  *
 161  *      @discussion
 162  *              This function has no effect on a query message that has been constructed.
 163  */
 164 void
 165 mdns_query_message_set_qtype(mdns_query_message_t message, uint16_t qtype);
 166
 167 /*!
 168  *      @brief
 169  *              Sets the QCLASS of a query message's question.
 170  *
 171  *      @param message
 172  *              The query message.
 173  *
 174  *      @param qclass
 175  *              The QCLASS.
 176  *
 177  *      @discussion
 178  *              This function has no effect on a query message that has been constructed.
 179  */
 180 void
 181 mdns_query_message_set_qclass(mdns_query_message_t message, uint16_t qclass);
 182
 183 /*!
 184  *      @brief
 185  *              Sets a query message's ID.
 186  *
 187  *      @param message
 188  *              The query message.
 189  *
 190  *      @param msg_id
 191  *              The message ID.
 192  *
 193  *      @discussion
 194  *              The default message ID is 0.
 195  *
 196  *              This function has no effect on a query message that has been constructed.
 197  */
 198 void
 199 mdns_query_message_set_message_id(mdns_query_message_t message, uint16_t msg_id);
 200
 201 /*!
 202  *      @brief
 203  *              Sets or clears a query message's AD (authentic data) bit.
 204  *
 205  *      @param message
 206  *              The query message.
 207  *
 208  *      @param set
 209  *              If true, the AD bit is set. If false, the AD bit is cleared.
 210  *
 211  *      @discussion
 212  *              The AD bit is clear by default.
 213  *
 214  *              See <https://tools.ietf.org/html/rfc6840#section-5.7>.
 215  *
 216  *              This function has no effect on a query message that has been constructed.
 217  */
 218 void
 219 mdns_query_message_set_ad_bit(mdns_query_message_t message, bool set);
 220
 221 /*!
 222  *      @brief
 223  *              Sets or clears a query message's CD (checking disabled) bit.
 224  *
 225  *      @param message
 226  *              The query message.
 227  *
 228  *      @param set
 229  *              If true, the CD bit is set. If false, the CD bit is cleared.
 230  *
 231  *      @discussion
 232  *              The CD bit is clear by default.
 233  *
 234  *              See <https://tools.ietf.org/html/rfc2535#section-6.1>.
 235  *
 236  *              This function has no effect on a query message that has been constructed.
 237  */
 238 void
 239 mdns_query_message_set_cd_bit(mdns_query_message_t message, bool set);
 240
 241 /*!
 242  *      @brief
 243  *              Sets or clears a query message's DO (DNSSEC OK) bit in its EDNS0 header.
 244  *
 245  *      @param message
 246  *              The query message.
 247  *
 248  *      @param set
 249  *              If true, the DO bit is set. If false, the DO bit is cleared.
 250  *
 251  *      @discussion
 252  *              The DO bit is clear by default.
 253  *
 254  *              See <https://tools.ietf.org/html/rfc3225#section-3>.
 255  *
 256  *              This function has no effect on a query message that has been constructed.
 257  */
 258 void
 259 mdns_query_message_set_do_bit(mdns_query_message_t message, bool set);
 260
 261 /*!
 262  *      @brief
 263  *              Specifies whether a query message should be constructed with EDNS0 padding.
 264  *
 265  *      @param message
 266  *              The query message.
 267  *
 268  *      @param use
 269  *              If true, EDNS0 padding will be used. If false, EDNS0 padding will not be used.
 270  *
 271  *      @discussion
 272  *              By default, EDNS0 padding is not used.
 273  *
 274  *              The padding strategy that will be utilized during construction is the Block-Length Padding strategy, as
 275  *              recommended by <https://tools.ietf.org/html/rfc8467#section-4.1>.
 276  *
 277  *              This function has no effect on a query message that has been constructed.
 278  */
 279 void
 280 mdns_query_message_use_edns0_padding(mdns_query_message_t message, bool use);
 281
 282 /*!
 283  *      @brief
 284  *              Constructs a query message's data in wire format.
 285  *
 286  *      @param message
 287  *              The query message.
 288  *
 289  *      @result
 290  *              kNoErr if the query message data was successfully constructed. Otherwise, an error code that indicates
 291  *              the error that was encountered during construction.
 292  *
 293  *      @discussion
 294  *              After a successful call of this function, the return values of mdns_message_get_dispatch_data(),
 295  *              mdns_message_get_byte_ptr(), and mdns_message_get_length() will reflect the newly constructed message
 296  *              data.
 297  *
 298  *              This function has no effect on a query message that has been constructed.
 299  */
 300 OSStatus
 301 mdns_query_message_construct(mdns_query_message_t message);
 302
 303 /*!
 304  *      @brief
 305  *              Gets a query message's question's QNAME in wire format.
 306  *
 307  *      @param message
 308  *              The query message.
 309  *
 310  *      @discussion
 311  *              The pointer returned by this function is guaranteed to be valid during the lifetime of the query message
 312  *              object.
 313  */
 314 const uint8_t *
 315 mdns_query_message_get_qname(mdns_query_message_t message);
 316
 317 /*!
 318  *      @brief
 319  *              Gets a query message's question's QTYPE value.
 320  *
 321  *      @param message
 322  *              The query message.
 323  */
 324 uint16_t
 325 mdns_query_message_get_qtype(mdns_query_message_t message);
 326
 327 /*!
 328  *      @brief
 329  *              Gets a query message's question's QCLASS value.
 330  *
 331  *      @param message
 332  *              The query message.
 333  */
 334 uint16_t
 335 mdns_query_message_get_qclass(mdns_query_message_t message);
 336
 337 /*!
 338  *      @brief
 339  *              Gets a query message's ID.
 340  *
 341  *      @param message
 342  *              The query message.
 343  */
 344 uint16_t
 345 mdns_query_message_get_message_id(mdns_query_message_t message);
 346
 347 /*!
 348  *      @brief
 349  *              Determines whether a query message's the DO bit is set.
 350  *
 351  *      @param message
 352  *              The query message.
 353  */
 354 bool
 355 mdns_query_message_do_bit_is_set(mdns_query_message_t message);
 356
 357 __END_DECLS
 358
 359 MDNS_ASSUME_NONNULL_END
 360
 361 #endif  // __MDNS_MESSAGE_H__