mDNSMacOSX/mdns_objects/mdns_interface_monitor.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 __MDNS_INTERFACE_MONITOR_H__
  18 #define __MDNS_INTERFACE_MONITOR_H__
  19
  20 #include "mdns_base.h"
  21 #include "mdns_object.h"
  22
  23 #include <stdint.h>
  24
  25 #include <dispatch/dispatch.h>
  26 #include <MacTypes.h>
  27
  28 MDNS_DECL(interface_monitor);
  29
  30 MDNS_ASSUME_NONNULL_BEGIN
  31
  32 __BEGIN_DECLS
  33
  34 /*!
  35  *      @brief
  36  *              Creates an interface monitor.
  37  *
  38  *      @param interface_index
  39  *              Index of the interface to monitor.
  40  *
  41  *      @result
  42  *              A new interface monitor or NULL if there was a lack of resources.
  43  *
  44  *      @discussion
  45  *              An interface monitor provides up-to-date information about an interface's properties, such as IPv4
  46  *              connectivity, IPv6 connectivity, whether the interface is expensive, and whether the interface is constrained.
  47  *
  48  *              If this function returns non-NULL, then the caller has an ownership reference to the newly created interface
  49  *              monitor, which can be relinquished with <code>mdns_release()</code>.
  50  */
  51 MDNS_RETURNS_RETAINED mdns_interface_monitor_t _Nullable
  52 mdns_interface_monitor_create(uint32_t interface_index);
  53
  54 /*!
  55  *      @brief
  56  *              Activates an interface monitor.
  57  *
  58  *      @param monitor
  59  *              The interface monitor.
  60  *
  61  *      @discussion
  62  *              Successful activation enables interface monitor updates.
  63  *
  64  *              This function has no effect on an interface monitor that has already been activated or one that has been
  65  *              invalidated.
  66  */
  67 void
  68 mdns_interface_monitor_activate(mdns_interface_monitor_t monitor);
  69
  70 /*!
  71  *      @brief
  72  *              Asynchronously invalidates an interface monitor.
  73  *
  74  *      @param monitor
  75  *              The interface monitor.
  76  *
  77  *      @discussion
  78  *              This function should be called when the interface monitor is no longer needed.
  79  *
  80  *              As a result of calling this function, the interface monitor's event handler will be invoked with a
  81  *              <code>mdns_event_invalidated</code> event, after which the interface monitor's event and update handlers will
  82  *              never be invoked again.
  83  *
  84  *              This function has no effect on an interface monitor that has already been invalidated.
  85  */
  86 void
  87 mdns_interface_monitor_invalidate(mdns_interface_monitor_t monitor);
  88
  89 /*!
  90  *      @brief
  91  *              Specifies the queue on which to invoke the interface monitor's event and update handlers.
  92  *
  93  *      @param monitor
  94  *              The interface monitor.
  95  *
  96  *      @param queue
  97  *              A serial queue.
  98  *
  99  *      @discussion
 100  *              This function must be called before activating the interface monitor.
 101  *
 102  *              This function has no effect on an interface monitor that has been activated or invalidated.
 103  */
 104 void
 105 mdns_interface_monitor_set_queue(mdns_interface_monitor_t monitor, dispatch_queue_t queue);
 106
 107 /*!
 108  *      @brief
 109  *              Sets an interface monitor's event handler.
 110  *
 111  *      @param monitor
 112  *              The interface monitor.
 113  *
 114  *      @param handler
 115  *              The event handler.
 116  *
 117  *      @discussion
 118  *              The event handler will never be invoked prior to activation.
 119  *
 120  *              The event handler will be invoked on the dispatch queue specified by
 121  *              <code>mdns_interface_monitor_set_queue()</code> with event <code>mdns_event_error</code> when a fatal error
 122  *              occurs and with event <code>mdns_event_invalidated</code> when the interface monitor has been invalidated.
 123  *
 124  *              After an <code>mdns_event_invalidated</code> event, the event handler will never be invoked again.
 125  */
 126 void
 127 mdns_interface_monitor_set_event_handler(mdns_interface_monitor_t monitor, mdns_event_handler_t _Nullable handler);
 128
 129 /*!
 130  *      @brief
 131  *              Flags that represent the properties of a monitored interface.
 132  *
 133  *      @discussion
 134  *              These flags don't represent the actual values of properties. The meaning of these flags depends on the
 135  *              context in which they're used. For example, as a parameter of mdns_interface_monitor_update_handler_t, a set
 136  *              flag means that the value of a given property has changed.
 137  */
 138 OS_CLOSED_OPTIONS(mdns_interface_flags, uint32_t,
 139         mdns_interface_flag_null                                = 0,
 140         mdns_interface_flag_ipv4_connectivity   = (1U <<  0),
 141         mdns_interface_flag_ipv6_connectivity   = (1U <<  1),
 142         mdns_interface_flag_expensive                   = (1U <<  2),
 143         mdns_interface_flag_constrained                 = (1U <<  3),
 144         mdns_interface_flag_clat46                              = (1U <<  4),
 145         mdns_interface_flag_vpn                                 = (1U <<  5),
 146         mdns_interface_flag_reserved                    = (1U << 31)
 147 );
 148
 149 /*!
 150  *      @brief
 151  *              Update handler for an interface monitor.
 152  *
 153  *      @param change_flags
 154  *              Each flag bit represents a property of a monitored interface. If the bit is set, then the value of that
 155  *              property has changed. If the bit is clear, then the value of that property has not changed.
 156  */
 157 typedef void (^mdns_interface_monitor_update_handler_t)(mdns_interface_flags_t change_flags);
 158
 159 /*!
 160  *      @brief
 161  *              Sets an interface monitor's update handler.
 162  *
 163  *      @param monitor
 164  *              The interface monitor.
 165  *
 166  *      @param handler
 167  *              The update handler.
 168  *
 169  *      @discussion
 170  *              The update handler will never be invoked prior to activation.
 171  *
 172  *              The update handler will be invoked on the dispatch queue specified by
 173  *              <code>mdns_interface_monitor_set_queue()</code> when any of the monitored interface's properties have been
 174  *              updated.
 175  *
 176  *              After an <code>mdns_event_invalidated</code> event, the update handler will ever be invoked again.
 177  */
 178 void
 179 mdns_interface_monitor_set_update_handler(mdns_interface_monitor_t monitor,
 180         mdns_interface_monitor_update_handler_t _Nullable handler);
 181
 182 /*!
 183  *      @brief
 184  *              Returns the index of the monitored interface.
 185  *
 186  *      @param monitor
 187  *              The interface monitor.
 188  */
 189 uint32_t
 190 mdns_interface_monitor_get_interface_index(mdns_interface_monitor_t monitor);
 191
 192 /*!
 193  *      @brief
 194  *              Determines whether the monitored interface currently has IPv4 connectivity.
 195  *
 196  *      @param monitor
 197  *              The interface monitor.
 198  *
 199  *      @discussion
 200  *              mdns_interface_flag_ipv4_connectivity will be set in the update handler's change_flags argument when the
 201  *              value of this property has changed.
 202  */
 203 bool
 204 mdns_interface_monitor_has_ipv4_connectivity(mdns_interface_monitor_t monitor);
 205
 206 /*!
 207  *      @brief
 208  *              Determines whether the monitored interface currently has IPv6 connectivity.
 209  *
 210  *      @param monitor
 211  *              The interface monitor.
 212  *
 213  *      @discussion
 214  *              mdns_interface_flag_ipv6_connectivity will be set in the update handler's change_flags argument when the
 215  *              value of this property has changed.
 216  */
 217 bool
 218 mdns_interface_monitor_has_ipv6_connectivity(mdns_interface_monitor_t monitor);
 219
 220 /*!
 221  *      @brief
 222  *              Determines whether the monitored interface is currently expensive.
 223  *
 224  *      @param monitor
 225  *              The interface monitor.
 226  *
 227  *      @discussion
 228  *              mdns_interface_flag_expensive will be set in the update handler's change_flags argument when the value
 229  *              of this property has changed.
 230  */
 231 bool
 232 mdns_interface_monitor_is_expensive(mdns_interface_monitor_t monitor);
 233
 234 /*!
 235  *      @brief
 236  *              Determines whether the monitored interface is currently constrained.
 237  *
 238  *      @param monitor
 239  *              The interface monitor.
 240  *
 241  *      @discussion
 242  *              mdns_interface_flag_constrained will be set in the update handler's change_flags argument when the value
 243  *              of this property has changed.
 244  */
 245 bool
 246 mdns_interface_monitor_is_constrained(mdns_interface_monitor_t monitor);
 247
 248 /*!
 249  *      @brief
 250  *              Determines whether the monitored interface has CLAT46 support.
 251  *
 252  *      @param monitor
 253  *              The interface monitor.
 254  *
 255  *      @discussion
 256  *              mdns_interface_flag_clat46 will be set in the update handler's change_flags argument when the value
 257  *              of this property has changed.
 258  */
 259 bool
 260 mdns_interface_monitor_is_clat46(mdns_interface_monitor_t monitor);
 261
 262 /*!
 263  *      @brief
 264  *              Determines whether the monitored interface is used for VPN.
 265  *
 266  *      @param monitor
 267  *              The interface monitor.
 268  *
 269  *      @discussion
 270  *              mdns_interface_flag_vpn will be set in the update handler's change_flags argument when the value of this
 271  *              property has changed.
 272  */
 273 bool
 274 mdns_interface_monitor_is_vpn(mdns_interface_monitor_t monitor);
 275
 276 __END_DECLS
 277
 278 MDNS_ASSUME_NONNULL_END
 279
 280 #define mdns_interface_monitor_forget(X)        mdns_forget_with_invalidation(X, interface_monitor)
 281
 282 #endif  // __MDNS_INTERFACE_MONITOR_H__