mDNSMacOSX/mdns_objects/mdns_object.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_OBJECT_H__
  18 #define __MDNS_OBJECT_H__
  19
  20 #include "mdns_base.h"
  21
  22 #include <CoreFoundation/CoreFoundation.h>
  23
  24 /*!
  25  *      @brief
  26  *              CFArray callbacks for mdns objects.
  27  */
  28 extern const CFArrayCallBacks mdns_cfarray_callbacks;
  29
  30 MDNS_ASSUME_NONNULL_BEGIN
  31
  32 /*!
  33  *      @typedef        mdns_any_t
  34  *      @brief
  35  *              A pointer to an mdns object.
  36  */
  37 #if OS_OBJECT_USE_OBJC
  38         typedef mdns_object_t   mdns_any_t;
  39 #else
  40         #if defined(__cplusplus)
  41                 typedef void *  mdns_any_t;
  42         #else
  43                 #if !defined(MDNS_ANY_TYPE_INTERNAL_MEMBERS)
  44                         #define MDNS_ANY_TYPE_INTERNAL_MEMBERS
  45                 #endif
  46                 typedef union {
  47                         MDNS_UNION_MEMBER(object);
  48                         MDNS_UNION_MEMBER(address);
  49                         MDNS_UNION_MEMBER(dns_service);
  50                         MDNS_UNION_MEMBER(dns_service_manager);
  51                         MDNS_UNION_MEMBER(interface_monitor);
  52                         MDNS_UNION_MEMBER(message);
  53                         MDNS_UNION_MEMBER(query_message);
  54                         MDNS_UNION_MEMBER(querier);
  55                         MDNS_UNION_MEMBER(resolver);
  56                         MDNS_UNION_MEMBER(set);
  57                         MDNS_UNION_MEMBER(trust);
  58                         MDNS_ANY_TYPE_INTERNAL_MEMBERS
  59                 } mdns_any_t __attribute__((__transparent_union__));
  60         #endif
  61 #endif
  62
  63 __BEGIN_DECLS
  64
  65 /*!
  66  *      @brief
  67  *              Increments the reference count of an mdns object.
  68  *
  69  *      @param object
  70  *              The mdns object.
  71  */
  72 mdns_object_t
  73 mdns_retain(mdns_any_t object);
  74 #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
  75         #undef mdns_retain
  76         #define mdns_retain(object)     [(object) retain]
  77 #endif
  78
  79 /*!
  80  *      @brief
  81  *              Decrements the reference count of an mdns object.
  82  *
  83  *      @param object
  84  *              The mdns object.
  85  */
  86 void
  87 mdns_release(mdns_any_t object);
  88 #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
  89         #undef mdns_release
  90         #define mdns_release(object)    [(object) release]
  91 #endif
  92
  93 /*!
  94  *      @brief
  95  *              Creates a human-readable description of an mdns object as a C string encoded in UTF-8.
  96  *
  97  *      @param object
  98  *              The mdns object.
  99  *
 100  *      @result
 101  *              A C string that must be freed with free(3).
 102  */
 103 MDNS_WARN_RESULT
 104 char * _Nullable
 105 mdns_copy_description(mdns_any_t object);
 106
 107 /*!
 108  *      @brief
 109  *              Determines whether two mdns objects are equal.
 110  *
 111  *      @param object1
 112  *              The first object.
 113  *
 114  *      @param object2
 115  *              The second object.
 116  *
 117  *      @result
 118  *              Returns true if the two objects are equal, otherwise false.
 119  */
 120 bool
 121 mdns_equal(mdns_any_t object1, mdns_any_t object2);
 122
 123 /*!
 124  *      @brief
 125  *              Generic events that may occur during the lifetime of some mdns objects.
 126  *
 127  *      @const mdns_event_error
 128  *              A fatal error has occurred.
 129  *
 130  *      @const mdns_event_invalidated
 131  *              The object has been invalidated.
 132  *
 133  *      @const mdns_event_update
 134  *              Some aspect of the object has been updated.
 135  */
 136 OS_CLOSED_ENUM(mdns_event, int,
 137         mdns_event_error                = 1,
 138         mdns_event_invalidated  = 2,
 139         mdns_event_update               = 3
 140 );
 141
 142 static inline const char *
 143 mdns_event_to_string(mdns_event_t event)
 144 {
 145         switch (event) {
 146                 case mdns_event_error:                  return "Error";
 147                 case mdns_event_invalidated:    return "Invalidated";
 148                 default:                                                return "?";
 149         }
 150 }
 151
 152 /*!
 153  *      @brief
 154  *              Generic event handler for mdns objects.
 155  *
 156  *      @param event
 157  *              The event.
 158  *
 159  *      @param error
 160  *              The error associated with a <code>mdns_event_error</code> event. This argument should be ignored for all
 161  *              other types of events.
 162  *
 163  *      @discussion
 164  *              After an <code>mdns_event_invalidated</code> event, none of the object's handlers will ever be invoked again.
 165  */
 166 typedef void (^mdns_event_handler_t)(mdns_event_t event, OSStatus error);
 167
 168 __END_DECLS
 169
 170 MDNS_ASSUME_NONNULL_END
 171
 172 #if OS_OBJECT_USE_OBJC && __has_feature(objc_arc)
 173         #define mdns_retain_arc_safe(OBJ)       (OBJ)
 174         #define mdns_release_arc_safe(OBJ)      do {} while (0)
 175 #else
 176         #define mdns_retain_arc_safe(OBJ)       mdns_retain(OBJ)
 177         #define mdns_release_arc_safe(OBJ)      mdns_release(OBJ)
 178 #endif
 179
 180 #define mdns_retain_null_safe(OBJ)              \
 181         do {                                                            \
 182                 if (OBJ) {                                              \
 183                         mdns_retain_arc_safe(OBJ);      \
 184                 }                                                               \
 185         } while (0)                                                     \
 186
 187 #define mdns_release_null_safe(OBJ)             \
 188         do {                                                            \
 189                 if (OBJ) {                                              \
 190                         mdns_release_arc_safe(OBJ);     \
 191                 }                                                               \
 192         } while (0)                                                     \
 193
 194 #define mdns_forget(PTR)                                        \
 195         do {                                                                    \
 196                 if (*(PTR)) {                                           \
 197                         mdns_release_arc_safe(*(PTR));  \
 198                         *(PTR) = NULL;                                  \
 199                 }                                                                       \
 200         } while(0)
 201
 202 #define mdns_replace(PTR, OBJ)                          \
 203         do {                                                                    \
 204                 if (OBJ) {                                                      \
 205                         mdns_retain_arc_safe(OBJ);              \
 206                 }                                                                       \
 207                 if (*(PTR)) {                                           \
 208                         mdns_release_arc_safe(*(PTR));  \
 209                 }                                                                       \
 210                 *(PTR) = (OBJ);                                         \
 211         } while(0)
 212
 213 #endif  // __MDNS_OBJECT_H__