mDNSMacOSX/mdns_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  *     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_PRIVATE_H__
  18 #define __MDNS_PRIVATE_H__
  19
  20 #include <CoreFoundation/CoreFoundation.h>
  21 #include <dispatch/dispatch.h>
  22 #include <MacTypes.h>
  23 #include <os/object.h>
  24
  25 #if OS_OBJECT_USE_OBJC
  26         #define MDNS_DECL(NAME)                 OS_OBJECT_DECL_SUBCLASS(mdns_ ## NAME, mdns_object)
  27         #define MDNS_RETURNS_RETAINED   OS_OBJECT_RETURNS_RETAINED
  28
  29         OS_OBJECT_DECL(mdns_object,);
  30 #else
  31         #define MDNS_DECL(NAME)                 typedef struct mdns_ ## NAME ## _s *    mdns_ ## NAME ## _t
  32         #define MDNS_RETURNS_RETAINED
  33
  34         MDNS_DECL(object);
  35 #endif
  36
  37 // mdns Object Declarations
  38
  39 MDNS_DECL(interface_monitor);
  40
  41 OS_ASSUME_NONNULL_BEGIN
  42
  43 #if OS_OBJECT_USE_OBJC
  44         typedef mdns_object_t   mdns_any_t;
  45 #else
  46         #if !defined(__cplusplus)
  47                 typedef union {
  48                         mdns_object_t                           base;
  49                         mdns_interface_monitor_t        interface_monitor;
  50                 } mdns_any_t __attribute__((__transparent_union__));
  51         #else
  52                 typedef void *  mdns_any_t;
  53         #endif
  54 #endif
  55
  56 __BEGIN_DECLS
  57
  58 /*!
  59  *      @brief
  60  *              Increments the reference count of an mdns object.
  61  *
  62  *      @param object
  63  *              The mdns object.
  64  */
  65 void
  66 mdns_retain(mdns_any_t object);
  67 #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
  68         #undef mdns_retain
  69         #define mdns_retain(object)     [(object) retain]
  70 #endif
  71
  72 /*!
  73  *      @brief
  74  *              Decrements the reference count of an mdns object.
  75  *
  76  *      @param object
  77  *              The mdns object.
  78  */
  79 void
  80 mdns_release(mdns_any_t object);
  81 #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
  82         #undef mdns_release
  83         #define mdns_release(object)    [(object) release]
  84 #endif
  85
  86 /*!
  87  *      @brief
  88  *              Creates a human-readable description of an mdns object as a C string.
  89  *
  90  *      @param object
  91  *              The mdns object.
  92  *
  93  *      @result
  94  *              A C string that must be freed with free(3).
  95  */
  96 OS_WARN_RESULT
  97 char * _Nullable
  98 mdns_copy_description(mdns_any_t object);
  99
 100 /*!
 101  *      @brief
 102  *              CFArray callbacks for mdns objects.
 103  */
 104 extern const CFArrayCallBacks mdns_cfarray_callbacks;
 105
 106 /*!
 107  *      @brief
 108  *              Creates an interface monitor.
 109  *
 110  *      @param interface_index
 111  *              Index of the interface to monitor.
 112  *
 113  *      @result
 114  *              A new interface monitor or NULL if there was a lack of resources.
 115  *
 116  *      @discussion
 117  *              An interface monitor provides up-to-date information about an interface's properties, such as IPv4
 118  *              connectivity, IPv6 connectivity, whether the interface is expensive, and whether the interface is constrained.
 119  *
 120  *              If this function returns non-NULL, then the caller has an ownership reference to the newly created interface
 121  *              monitor, which can be relinquished with <code>mdns_release()</code>.
 122  */
 123 MDNS_RETURNS_RETAINED mdns_interface_monitor_t _Nullable
 124 mdns_interface_monitor_create(uint32_t interface_index);
 125
 126 /*!
 127  *      @brief
 128  *              Activates an interface monitor.
 129  *
 130  *      @param monitor
 131  *              The interface monitor.
 132  *
 133  *      @discussion
 134  *              Successful activation enables interface monitor updates.
 135  *
 136  *              This function has no effect on an interface monitor that has already been activated or one that has been
 137  *              invalidated.
 138  */
 139 void
 140 mdns_interface_monitor_activate(mdns_interface_monitor_t monitor);
 141
 142 /*!
 143  *      @brief
 144  *              Asynchronously invalidates an interface monitor.
 145  *
 146  *      @param monitor
 147  *              The interface monitor.
 148  *
 149  *      @discussion
 150  *              This function should be called when the interface monitor is no longer needed.
 151  *
 152  *              As a result of calling this function, the interface monitor's event handler will be invoked with a
 153  *              <code>mdns_event_invalidated</code> event, after which the interface monitor's event and update handlers will
 154  *              never be invoked again.
 155  *
 156  *              This function has no effect on an interface monitor that has already been invalidated.
 157  */
 158 void
 159 mdns_interface_monitor_invalidate(mdns_interface_monitor_t monitor);
 160
 161 /*!
 162  *      @brief
 163  *              Specifies the queue on which to invoke the interface monitor's event and update handlers.
 164  *
 165  *      @param monitor
 166  *              The interface monitor.
 167  *
 168  *      @param queue
 169  *              A serial queue.
 170  *
 171  *      @discussion
 172  *              This function must be called before activating the interface monitor.
 173  *
 174  *              This function has no effect on an interface monitor that has been activated or invalidated.
 175  */
 176 void
 177 mdns_interface_monitor_set_queue(mdns_interface_monitor_t monitor, dispatch_queue_t queue);
 178
 179 /*!
 180  *      @brief
 181  *              Generic events that can occur during the lifetime of an mdns object.
 182  */
 183 OS_CLOSED_ENUM(mdns_event, int,
 184         /*! @const mdns_event_error A fatal error has occurred. */
 185         mdns_event_error                = 1,
 186         /*! @const mdns_event_invalidated The object has been invalidated. */
 187         mdns_event_invalidated  = 2
 188 );
 189
 190 static inline const char *
 191 mdns_event_to_string(mdns_event_t event)
 192 {
 193         switch (event) {
 194                 case mdns_event_error:                  return "Error";
 195                 case mdns_event_invalidated:    return "Invalidated";
 196                 default:                                                return "?";
 197         }
 198 }
 199
 200 /*!
 201  *      @brief
 202  *              Generic event handler for mdns objects.
 203  *
 204  *      @param event
 205  *              The event.
 206  *
 207  *      @param error
 208  *              The error associated with a <code>mdns_event_error</code> event. This argument should be ignored for all other
 209  *              types of events.
 210  *
 211  *      @discussion
 212  *              After an <code>mdns_event_invalidated</code> event, none of the object's handlers will ever be invoked again.
 213  */
 214 typedef void (^mdns_event_handler_t)(mdns_event_t event, OSStatus error);
 215
 216 /*!
 217  *      @brief
 218  *              Sets an interface monitor's event handler.
 219  *
 220  *      @param monitor
 221  *              The interface monitor.
 222  *
 223  *      @param handler
 224  *              The event handler.
 225  *
 226  *      @discussion
 227  *              The event handler will never be invoked prior to activation.
 228  *
 229  *              The event handler will be invoked on the dispatch queue specified by
 230  *              <code>mdns_interface_monitor_set_queue()</code> with event <code>mdns_event_error</code> when a fatal error
 231  *              occurs and with event <code>mdns_event_invalidated</code> when the interface monitor has been invalidated.
 232  *
 233  *              After an <code>mdns_event_invalidated</code> event, the event handler will never be invoked again.
 234  */
 235 void
 236 mdns_interface_monitor_set_event_handler(mdns_interface_monitor_t monitor, mdns_event_handler_t _Nullable handler);
 237
 238 /*!
 239  *      @brief
 240  *              Flags that represent the properties of a monitored interface.
 241  *
 242  *      @discussion
 243  *              These flags don't represent the actual values of properties. The meaning of these flags depends on the context
 244  *              in which they're used. For example, as a parameter of mdns_interface_monitor_update_handler_t, a set flag
 245  *              means that the value of a given property has changed.
 246  */
 247 OS_CLOSED_OPTIONS(mdns_interface_flags, uint32_t,
 248         mdns_interface_flag_null                                = 0,
 249         mdns_interface_flag_ipv4_connectivity   = (1U <<  0),
 250         mdns_interface_flag_ipv6_connectivity   = (1U <<  1),
 251         mdns_interface_flag_expensive                   = (1U <<  2),
 252         mdns_interface_flag_constrained                 = (1U <<  3),
 253         mdns_interface_flag_clat46                              = (1U <<  4),
 254         mdns_interface_flag_reserved                    = (1U << 31)
 255 );
 256
 257 /*!
 258  *      @brief
 259  *              Update handler for an interface monitor.
 260  *
 261  *      @param change_flags
 262  *              Each flag bit represents a property of a monitored interface. If the bit is set, then the value of that
 263  *              property has changed. If the bit is clear, then the value of that property has not changed.
 264  */
 265 typedef void (^mdns_interface_monitor_update_handler_t)(mdns_interface_flags_t change_flags);
 266
 267 /*!
 268  *      @brief
 269  *              Sets an interface monitor's update handler.
 270  *
 271  *      @param monitor
 272  *              The interface monitor.
 273  *
 274  *      @param handler
 275  *              The update handler.
 276  *
 277  *      @discussion
 278  *              The update handler will never be invoked prior to activation.
 279  *
 280  *              The update handler will be invoked on the dispatch queue specified by
 281  *              <code>mdns_interface_monitor_set_queue()</code> when any of the monitored interface's properties have been
 282  *              updated.
 283  *
 284  *              After an <code>mdns_event_invalidated</code> event, the update handler will ever be invoked again.
 285  */
 286 void
 287 mdns_interface_monitor_set_update_handler(mdns_interface_monitor_t monitor,
 288         mdns_interface_monitor_update_handler_t _Nullable handler);
 289
 290 /*!
 291  *      @brief
 292  *              Returns the index of the monitored interface.
 293  *
 294  *      @param monitor
 295  *              The interface monitor.
 296  */
 297 uint32_t
 298 mdns_interface_monitor_get_interface_index(mdns_interface_monitor_t monitor);
 299
 300 /*!
 301  *      @brief
 302  *              Determines whether the monitored interface currently has IPv4 connectivity.
 303  *
 304  *      @param monitor
 305  *              The interface monitor.
 306  *
 307  *      @discussion
 308  *              mdns_interface_flag_ipv4_connectivity will be set in the update handler's change_flags argument when the value
 309  *              of this property has changed.
 310  */
 311 bool
 312 mdns_interface_monitor_has_ipv4_connectivity(mdns_interface_monitor_t monitor);
 313
 314 /*!
 315  *      @brief
 316  *              Determines whether the monitored interface currently has IPv6 connectivity.
 317  *
 318  *      @param monitor
 319  *              The interface monitor.
 320  *
 321  *      @discussion
 322  *              mdns_interface_flag_ipv6_connectivity will be set in the update handler's change_flags argument when the value
 323  *              of this property has changed.
 324  */
 325 bool
 326 mdns_interface_monitor_has_ipv6_connectivity(mdns_interface_monitor_t monitor);
 327
 328 /*!
 329  *      @brief
 330  *              Determines whether the monitored interface is currently expensive.
 331  *
 332  *      @param monitor
 333  *              The interface monitor.
 334  *
 335  *      @discussion
 336  *              mdns_interface_flag_expensive will be set in the update handler's change_flags argument when the value
 337  *              of this property has changed.
 338  */
 339 bool
 340 mdns_interface_monitor_is_expensive(mdns_interface_monitor_t monitor);
 341
 342 /*!
 343  *      @brief
 344  *              Determines whether the monitored interface is currently constrained.
 345  *
 346  *      @param monitor
 347  *              The interface monitor.
 348  *
 349  *      @discussion
 350  *              mdns_interface_flag_constrained will be set in the update handler's change_flags argument when the value
 351  *              of this property has changed.
 352  */
 353 bool
 354 mdns_interface_monitor_is_constrained(mdns_interface_monitor_t monitor);
 355
 356 /*!
 357  *      @brief
 358  *              Determines whether the monitored interface has CLAT46 support.
 359  *
 360  *      @param monitor
 361  *              The interface monitor.
 362  *
 363  *      @discussion
 364  *              mdns_interface_flag_clat46 will be set in the update handler's change_flags argument when the value
 365  *              of this property has changed.
 366  */
 367 bool
 368 mdns_interface_monitor_is_clat46(mdns_interface_monitor_t monitor);
 369
 370 __END_DECLS
 371
 372 OS_ASSUME_NONNULL_END
 373
 374 #endif  // __MDNS_PRIVATE_H__