mDNSMacOSX/Private/advertising_proxy_services.h

   1 /* advertising_proxy_services.h
   2  *
   3  * Copyright (c) 2020 Apple Computer, Inc. All rights reserved.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  *
  17  * This file contains definitions for the SRP Advertising Proxy management
  18  * API on MacOS, which is private API used to control and manage the advertising
  19  * proxy.
  20  */
  21
  22 #ifndef DNSSD_PROXY_SERVICES_H
  23 #define DNSSD_PROXY_SERVICES_H
  24
  25 #if defined(TARGET_OS_TV)
  26
  27 #include <dispatch/dispatch.h>
  28 #include <xpc/xpc.h>
  29
  30 #if (defined(__GNUC__) && (__GNUC__ >= 4))
  31 #define DNS_SERVICES_EXPORT __attribute__((visibility("default")))
  32 #else
  33 #define DNS_SERVICES_EXPORT
  34 #endif
  35
  36 // advertising_proxy_conn_ref: Opaque internal data type
  37 typedef struct _advertising_proxy_conn_ref_t *advertising_proxy_conn_ref;
  38
  39 typedef enum
  40 {
  41     kDNSSDAdvertisingProxyStatus_NoError                   =  0,
  42     kDNSSDAdvertisingProxyStatus_UnknownErr                = -65537,   /* 0xFFFE FFFF */
  43     kDNSSDAdvertisingProxyStatus_NoMemory                  = -65539,   /* No Memory   */
  44     kDNSSDAdvertisingProxyStatus_BadParam                  = -65540,   /* Client passed invalid arg */
  45     kDNSSDAdvertisingProxyStatus_DaemonNotRunning          = -65563,   /* Daemon not running */
  46     kDNSSDAdvertisingProxyStatus_Disconnected              = -65569    /* Daemon disconnected */
  47 } advertising_proxy_error_type;
  48
  49 /*********************************************************************************************
  50  *
  51  *  DNSSD Advertising Proxy control/management library functions
  52  *
  53  *********************************************************************************************/
  54
  55 /* advertising_proxy_reply: Callback from all DNSSD Advertising proxy library functions
  56  *
  57  * advertising_proxy_reply() parameters:
  58  *
  59  * conn_ref:                   The advertising_proxy_conn_ref initialized by the library function.  Call advertising_proxy_
  60  *
  61  * response:                   Any data returned by the advertising proxy in response to the request.
  62  *
  63  * errCode:                    Will be kDNSSDAdvertisingProxy_NoError on success, otherwise will indicate the
  64  *                             failure that occurred.
  65  *
  66  */
  67
  68 typedef void (*advertising_proxy_reply)
  69 (
  70     advertising_proxy_conn_ref  conn_ref,
  71     xpc_object_t                response,
  72     advertising_proxy_error_type errCode
  73 );
  74
  75 /* advertising_proxy_enable
  76  *
  77  * enables the DNSSD Advertising Proxy functionality which will remain ON until the client explicitly turns it OFF
  78  * by passing the returned advertising_proxy_conn_ref to advertising_proxy_ref_dealloc(), or the client exits or crashes.
  79  *
  80  * advertising_proxy_enable() Parameters:
  81  *
  82  * conn_ref:                   A pointer to advertising_proxy_conn_ref that is initialized to NULL.
  83  *                            If the call succeeds it will be initialized to a non-NULL value.
  84  *                            Client terminates the DNSSD Advertising Proxy by passing this advertising_proxy_conn_ref to advertising_proxy_ref_dealloc().
  85  *
  86  * clientq:                   Queue the client wants to schedule the callback on (Note: Must not be NULL)
  87  *
  88  * callback:                  CallBack function for the client that indicates success or failure.
  89  *                            Note: callback may be invoked more than once, For e.g. if enabling DNSSD Advertising Proxy
  90  *                            first succeeds and the daemon possibly crashes sometime later.
  91  *
  92  * return value:              Returns kDNSSDAdvertisingProxy_NoError when no error otherwise returns an error code indicating
  93  *                            the error that occurred. Note: A return value of kDNSSDAdvertisingProxy_NoError does not mean
  94  *                            that DNSSD Advertising Proxy was successfully enabled. The callback may asynchronously
  95  *                            return an error (such as kDNSSDAdvertisingProxy_DaemonNotRunning)
  96  *
  97  */
  98
  99 DNS_SERVICES_EXPORT
 100 advertising_proxy_error_type advertising_proxy_enable
 101 (
 102     advertising_proxy_conn_ref *conn_ref,
 103     dispatch_queue_t            clientq,
 104     advertising_proxy_reply     callback
 105 );
 106
 107 /* advertising_proxy_flush_entries
 108  *
 109  * Flushes any host entries that have been registered with the advertising proxy.   For testing only:
 110  * this is never the right thing to do in production.
 111  *
 112  * advertising_proxy_flush_entries() Parameters:
 113  *
 114  * conn_ref:                  A pointer to advertising_proxy_conn_ref that is initialized to NULL.
 115  *                            If the call succeeds it will be initialized to a non-NULL value.
 116  *                            The same conn_ref can be used for more than one call.
 117  *
 118  * clientq:                   Queue the client wants to schedule the callback on (Note: Must not be NULL)
 119  *
 120  * callback:                  CallBack function for the client that indicates success or failure.
 121  *                            Callback is not called until either the command has failed, or has completed.
 122  *
 123  * return value:              Returns kDNSSDAdvertisingProxy_NoError when no error otherwise returns an
 124  *                            error code indicating the error that occurred. Note: A return value of
 125  *                            kDNSSDAdvertisingProxy_NoError does not mean that DNSSD Advertising Proxy host
 126  *                            table was successfully flushed. The callback may asynchronously return an
 127  *                            error (such as kDNSSDAdvertisingProxy_DaemonNotRunning)
 128  *
 129  */
 130
 131 DNS_SERVICES_EXPORT
 132 advertising_proxy_error_type advertising_proxy_flush_entries
 133 (
 134     advertising_proxy_conn_ref *conn_ref,
 135     dispatch_queue_t            clientq,
 136     advertising_proxy_reply     callback
 137 );
 138
 139 /* advertising_proxy_get_service_list
 140  *
 141  * Returns a list of registered services on the advertising proxy.
 142  *
 143  * advertising_proxy_get_service_list() Parameters:
 144  *
 145  * conn_ref:                  A pointer to advertising_proxy_conn_ref that is initialized to NULL.
 146  *                            If the call succeeds it will be initialized to a non-NULL value.
 147  *                            The same conn_ref can be used for more than one call.
 148  *
 149  * clientq:                   Queue the client wants to schedule the callback on (Note: Must not be NULL)
 150  *
 151  * callback:                  CallBack function for the client that indicates success or failure.
 152  *                            Callback is not called until either the command has failed, or has completed.
 153  *
 154  * return value:              Returns kDNSSDAdvertisingProxy_NoError when no error otherwise returns an
 155  *                            error code indicating the error that occurred. Note: A return value of
 156  *                            kDNSSDAdvertisingProxy_NoError does not mean that DNSSD Advertising Proxy host
 157  *                            table was successfully flushed. The callback may asynchronously return an
 158  *                            error (such as kDNSSDAdvertisingProxy_DaemonNotRunning)
 159  *
 160  */
 161
 162 DNS_SERVICES_EXPORT
 163 advertising_proxy_error_type advertising_proxy_get_service_list
 164 (
 165     advertising_proxy_conn_ref *conn_ref,
 166     dispatch_queue_t            clientq,
 167     advertising_proxy_reply     callback
 168 );
 169
 170 /* advertising_proxy_block_service
 171  *
 172  * For testing, block advertisement of SRP service on the thread network.
 173  *
 174  * advertising_proxy_block_service() Parameters:
 175  *
 176  * conn_ref:                  A pointer to advertising_proxy_conn_ref that is initialized to NULL.
 177  *                            If the call succeeds it will be initialized to a non-NULL value.
 178  *                            The same conn_ref can be used for more than one call.
 179  *
 180  * clientq:                   Queue the client wants to schedule the callback on (Note: Must not be NULL)
 181  *
 182  * callback:                  CallBack function for the client that indicates success or failure.
 183  *                            Callback is not called until either the command has failed, or has completed.
 184  *
 185  * return value:              Returns kDNSSDAdvertisingProxy_NoError when no error otherwise returns an
 186  *                            error code indicating the error that occurred. Note: A return value of
 187  *                            kDNSSDAdvertisingProxy_NoError does not mean that DNSSD Advertising Proxy host
 188  *                            table was successfully flushed. The callback may asynchronously return an
 189  *                            error (such as kDNSSDAdvertisingProxy_DaemonNotRunning)
 190  *
 191  */
 192
 193 DNS_SERVICES_EXPORT
 194 advertising_proxy_error_type advertising_proxy_block_service
 195 (
 196     advertising_proxy_conn_ref *conn_ref,
 197     dispatch_queue_t            clientq,
 198     advertising_proxy_reply     callback
 199 );
 200
 201 /* advertising_proxy_unblock_service
 202  *
 203  * For testing, unblock advertisement of SRP service on the thread network.
 204  *
 205  * advertising_proxy_unblock_service() Parameters:
 206  *
 207  * conn_ref:                  A pointer to advertising_proxy_conn_ref that is initialized to NULL.
 208  *                            If the call succeeds it will be initialized to a non-NULL value.
 209  *                            The same conn_ref can be used for more than one call.
 210  *
 211  * clientq:                   Queue the client wants to schedule the callback on (Note: Must not be NULL)
 212  *
 213  * callback:                  CallBack function for the client that indicates success or failure.
 214  *                            Callback is not called until either the command has failed, or has completed.
 215  *
 216  * return value:              Returns kDNSSDAdvertisingProxy_NoError when no error otherwise returns an
 217  *                            error code indicating the error that occurred. Note: A return value of
 218  *                            kDNSSDAdvertisingProxy_NoError does not mean that DNSSD Advertising Proxy host
 219  *                            table was successfully flushed. The callback may asynchronously return an
 220  *                            error (such as kDNSSDAdvertisingProxy_DaemonNotRunning)
 221  *
 222  */
 223
 224 DNS_SERVICES_EXPORT
 225 advertising_proxy_error_type advertising_proxy_unblock_service
 226 (
 227     advertising_proxy_conn_ref *conn_ref,
 228     dispatch_queue_t            clientq,
 229     advertising_proxy_reply     callback
 230 );
 231
 232 /* advertising_proxy_regenerate_ula
 233  *
 234  * For testing, generate a new ULA prefix
 235  *
 236  * advertising_proxy_regenerate_ula() Parameters:
 237  *
 238  * conn_ref:                  A pointer to advertising_proxy_conn_ref that is initialized to NULL.
 239  *                            If the call succeeds it will be initialized to a non-NULL value.
 240  *                            The same conn_ref can be used for more than one call.
 241  *
 242  * clientq:                   Queue the client wants to schedule the callback on (Note: Must not be NULL)
 243  *
 244  * callback:                  CallBack function for the client that indicates success or failure.
 245  *                            Callback is not called until either the command has failed, or has completed.
 246  *
 247  * return value:              Returns kDNSSDAdvertisingProxy_NoError when no error otherwise returns an
 248  *                            error code indicating the error that occurred. Note: A return value of
 249  *                            kDNSSDAdvertisingProxy_NoError does not mean that DNSSD Advertising Proxy host
 250  *                            table was successfully flushed. The callback may asynchronously return an
 251  *                            error (such as kDNSSDAdvertisingProxy_DaemonNotRunning)
 252  *
 253  */
 254
 255 DNS_SERVICES_EXPORT
 256 advertising_proxy_error_type advertising_proxy_regenerate_ula
 257 (
 258     advertising_proxy_conn_ref *conn_ref,
 259     dispatch_queue_t            clientq,
 260     advertising_proxy_reply     callback
 261 );
 262
 263 /* advertising_proxy_ref_dealloc()
 264  *
 265  * Terminate a connection with the daemon and free memory associated with the advertising_proxy_conn_ref.
 266  * When used on a advertising_proxy_conn_ref returned by advertising_proxy_enable, terminates the advertising
 267  * proxy.  When used on a call that subscribes to notifications about objects managed by the advertising proxy,
 268  * discontinues those notifications.
 269  *
 270  * conn_ref:        A advertising_proxy_conn_ref initialized by any of the advertising_proxy_*() calls.
 271  *
 272  */
 273 DNS_SERVICES_EXPORT
 274 void advertising_proxy_ref_dealloc(advertising_proxy_conn_ref conn_ref);
 275 #endif /* DNSSD_PROXY_SERVICES_H */
 276 #endif // defined(TARGET_OS_TV)
 277
 278
 279 // Local Variables:
 280 // mode: C
 281 // tab-width: 4
 282 // c-file-style: "bsd"
 283 // c-basic-offset: 4
 284 // fill-column: 108
 285 // indent-tabs-mode: nil
 286 // End: