mDNSMacOSX/Private/cti-services.h

   1 /* cti_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 CoreThreadRadio
  18  * API on MacOS, which is private API used to control and manage the wpantund
  19  * and thereby manage the thread network.
  20  */
  21
  22 #ifndef CTI_SERVICES_H
  23 #define CTI_SERVICES_H
  24
  25 #include <netinet/in.h>
  26 #include <arpa/inet.h>
  27 #include <dispatch/dispatch.h>
  28 #include <xpc/xpc.h>
  29 #include "srp.h"
  30
  31 #if (defined(__GNUC__) && (__GNUC__ >= 4))
  32 #define DNS_SERVICES_EXPORT __attribute__((visibility("default")))
  33 #else
  34 #define DNS_SERVICES_EXPORT
  35 #endif
  36
  37 // cti_connection: Opaque internal data type
  38 typedef struct _cti_connection_t *cti_connection_t;
  39
  40 typedef enum
  41 {
  42     kCTIStatus_NoError                   =  0,
  43     kCTIStatus_UnknownError              = -65537,   /* 0xFFFE FFFF */
  44     kCTIStatus_NoMemory                  = -65539,   /* No Memory   */
  45     kCTIStatus_BadParam                  = -65540,   /* Client passed invalid arg */
  46     kCTIStatus_DaemonNotRunning          = -65563,   /* Daemon not running */
  47     kCTIStatus_Disconnected              = -65569    /* XPC connection disconnected. */
  48 } cti_status_t;
  49
  50 // Enum values for kWPANTUNDStateXXX (see wpan-properties.h)
  51 typedef enum {
  52     kCTI_NCPState_Uninitialized,
  53     kCTI_NCPState_Fault,
  54     kCTI_NCPState_Upgrading,
  55     kCTI_NCPState_DeepSleep,
  56     kCTI_NCPState_Offline,
  57     kCTI_NCPState_Commissioned,
  58     kCTI_NCPState_Associating,
  59     kCTI_NCPState_CredentialsNeeded,
  60     kCTI_NCPState_Associated,
  61     kCTI_NCPState_Isolated,
  62     kCTI_NCPState_NetWake_Asleep,
  63     kCTI_NCPState_NetWake_Waking,
  64     kCTI_NCPState_Unknown
  65 } cti_network_state_t;
  66
  67 typedef enum {
  68     kCTI_NetworkNodeType_Unknown,
  69     kCTI_NetworkNodeType_Router,
  70     kCTI_NetworkNodeType_EndDevice,
  71     kCTI_NetworkNodeType_SleepyEndDevice,
  72     kCTI_NetworkNodeType_NestLurker,
  73     kCTI_NetworkNodeType_Commissioner,
  74     kCTI_NetworkNodeType_Leader,
  75 } cti_network_node_type_t;
  76
  77 typedef struct _cti_service {
  78     uint64_t enterprise_number;
  79     uint16_t service_type;
  80     uint16_t service_version;
  81     uint8_t *NONNULL server;
  82     size_t server_length;
  83     int ref_count;
  84     int flags;      // E.g., kCTIFlag_NCP
  85 } cti_service_t;
  86
  87 typedef struct _cti_service_vec {
  88     size_t num;
  89     int ref_count;
  90     cti_service_t *NULLABLE *NONNULL services;
  91 } cti_service_vec_t;
  92
  93 typedef struct _cti_prefix {
  94     struct in6_addr prefix;
  95     int prefix_length;
  96     int metric;
  97     int flags;
  98     int ref_count;
  99 } cti_prefix_t;
 100
 101 typedef struct _cti_prefix_vec {
 102     size_t num;
 103     int ref_count;
 104     cti_prefix_t *NULLABLE *NONNULL prefixes;
 105 } cti_prefix_vec_t;
 106
 107 // CTI flags.
 108 #define kCTIFlag_Stable                1
 109 #define kCTIFlag_NCP                   2
 110
 111 /*********************************************************************************************
 112  *
 113  *  wpantund private SPI for use in SRP Advertising Proxy
 114  *
 115  *********************************************************************************************/
 116
 117 /* cti_reply:
 118  *
 119  * A general reply mechanism to indicate success or failure for a cti call that doesn't
 120  * return any data.
 121  *
 122  * cti_reply parameters:
 123  *
 124  * context:    The context that was passed to the cti service call to which this is a callback.
 125  *
 126  * status:         Will be kCTIStatus_NoError on success, otherwise will indicate the
 127  *                         failure that occurred.
 128  *
 129  */
 130
 131 typedef void
 132 (*cti_reply_t)(void *NULLABLE context, cti_status_t status);
 133
 134 /* cti_tunnel_reply: Callback for cti_get_tunnel_name()
 135  *
 136  * Called exactly once in response to a cti_get_tunnel_name() call, either with an error or with
 137  * the name of the tunnel that wpantund is using as the Thread network interface.   The invoking
 138  * program is responsible for releasing the connection state either during or after the callback.
 139  *
 140  * cti_reply parameters:
 141  *
 142  * context:       The context that was passed to the cti service call to which this is a callback.
 143  *
 144  * tunnel_name:   If error is kCTIStatus_NoError, this dictionary contains either the response to
 145  *                            a request, or else the content of a CTI event if this is an event callback.
 146  *
 147  * status:            Will be kCTIStatus_NoError on success, otherwise will indicate the
 148  *                            failure that occurred.
 149  *
 150  */
 151
 152 typedef void
 153 (*cti_tunnel_reply_t)(void *NULLABLE context, const char *NONNULL tunnel_name,
 154                       cti_status_t status);
 155
 156 /* cti_get_tunnel_name
 157  *
 158  * Get the name of the tunnel that wpantund is presenting as the Thread network interface.
 159  * The tunnel name is passed to the reply callback if the request succeeds; otherwise an error
 160  * is either returned immediately or returned to the callback.
 161  *
 162  * context:        An anonymous pointer that will be passed along to the callback when
 163  *                 an event occurs.
 164  *
 165  * client_queueq:  Queue the client wants to schedule the callback on (Note: Must not be NULL)
 166  *
 167  * callback:       CallBack function for the client that indicates success or failure.
 168  *
 169  * return value:   Returns kCTIStatus_NoError when no error otherwise returns an error code indicating the
 170  *                 error that occurred. Note: A return value of kCTIStatus_NoError does not mean that the
 171  *                 request succeeded, merely that it was successfully started.
 172  *
 173  */
 174
 175 DNS_SERVICES_EXPORT cti_status_t
 176 cti_get_tunnel_name(void *NULLABLE context, cti_tunnel_reply_t NONNULL callback, dispatch_queue_t NONNULL client_queue);
 177
 178 /*
 179  * cti_service_vec_create
 180  *
 181  * creates a service array vector of specified length
 182  *
 183  * num_services:     Number of service slots available in the service vector.
 184  *
 185  * return value:     NULL, if the call failed; otherwise a service vector capable of containing the requested number of
 186  *                   services.
 187  */
 188 cti_service_vec_t *NULLABLE
 189 cti_service_vec_create_(size_t num_services, const char *NONNULL file, int line);
 190 #define cti_service_vec_create(num_services) cti_service_vec_create_(num_services, __FILE__, __LINE__)
 191
 192 /*
 193  * cti_service_vec_release
 194  *
 195  * decrements the reference count on the provided service vector and, if it reaches zero, finalizes the service vector,
 196  * which calls cti_service_release on each service in the vector, potentially also finalizing them.
 197  *
 198  * num_services:     Number of service slots available in the service vector.
 199  *
 200  * return value:     NULL, if the call failed; otherwise a service vector capable of containing the requested number of
 201  *                   services.
 202  */
 203
 204 void
 205 cti_service_vec_release_(cti_service_vec_t *NONNULL services, const char *NONNULL file, int line);
 206 #define cti_service_vec_release(services) cti_service_vec_release_(services, __FILE__, __LINE__)
 207
 208 /*
 209  * cti_service_create
 210  *
 211  * Creates a service containing the specified information.   service and server are retained, and will be
 212  * freed using free() when the service object is finalized.   Caller must not retain or free these values, and
 213  * they must be allocated on the malloc heap.
 214  *
 215  * enterprise_number: The enterprise number for this service.
 216  *
 217  * service_type:      The service type, from the service data.
 218  *
 219  * service_version:   The service version, from the service data.
 220  *
 221  * server:            Server information for this service, stored in network byte order.   Format depends on service type.
 222  *
 223  * server_length:     Length of server information in bytes.
 224  *
 225  * flags:             Thread network status flags, e.g. NCP versue User
 226  *
 227  * return value:     NULL, if the call failed; otherwise a service object containing the specified state.
 228  */
 229
 230 cti_service_t *NULLABLE
 231 cti_service_create_(uint64_t enterprise_number, uint16_t service_type, uint16_t service_version,
 232                     uint8_t *NONNULL server, size_t server_length, int flags,
 233                     const char *NONNULL file, int line);
 234 #define cti_service_create(enterprise_number, service_type, service_version, server, server_length, flags) \
 235     cti_service_create_(enterprise_number, service_type, service_version, server, server_length, flags, \
 236                         __FILE__, __LINE__)
 237
 238 /*
 239  * cti_service_vec_release
 240  *
 241  * decrements the reference count on the provided service vector and, if it reaches zero, finalizes the service vector,
 242  * which calls cti_service_release on each service in the vector, potentially also finalizing them.
 243  *
 244  * services:         The service vector to release
 245  *
 246  * return value:     NULL, if the call failed; otherwise a service vector capable of containing the requested number of
 247  *                   services.
 248  */
 249
 250 void
 251 cti_service_release_(cti_service_t *NONNULL service, const char *NONNULL file, int line);
 252 #define cti_service_release(services) cti_service_release(service, __FILE__, __LINE__)
 253
 254 /* cti_service_reply: Callback from cti_get_service_list()
 255  *
 256  * Called when an error occurs during processing of the cti_get_service_list call, or when data
 257  * is available in response to the call.
 258  *
 259  * In the case of an error, the callback will not be called again, and the caller is responsible for
 260  * releasing the connection state and restarting if needed.
 261  *
 262  * The callback will be called once immediately upon success, and once again each time the service list
 263  * is updated.   If the callback wishes to retain either the cti_service_vec_t or any of the elements
 264  * of that vector, the appropriate retain function should be called; when the object is no longer needed,
 265  * the corresponding release call must be called.
 266  *
 267  * cti_reply parameters:
 268  *
 269  * context:           The context that was passed to the cti service call to which this is a callback.
 270  *
 271  * services:          If status is kCTIStatus_NoError, a cti_service_vec_t containing the list of services
 272  *                    provided in the update.
 273  *
 274  * status:                Will be kCTIStatus_NoError if the service list request is successful, or
 275  *                    will indicate the failure that occurred.
 276  *
 277  */
 278
 279 typedef void
 280 (*cti_service_reply_t)(void *NULLABLE context, cti_service_vec_t *NULLABLE services, cti_status_t status);
 281
 282 /* cti_get_service_list
 283  *
 284  * Requests wpantund to immediately send the current list of services published in the Thread network data.
 285  * Whenever the service list is updated, the callback will be called again with the new information.  A
 286  * return value of kCTIStatus_NoError means that the caller can expect the reply callback to be called at least
 287  * once.  Any other error status means that the request could not be sent, and the callback will never be
 288  * called.
 289  *
 290  * To discontinue receiving service add/remove callbacks, the calling program should call
 291  * cti_connection_ref_deallocate on the conn_ref returned by a successful call to get_service_list();
 292  *
 293  * ref:            A pointer to a reference to the connection is stored through ref if ref is not NULL.
 294  *                 When events are no longer needed, call cti_discontinue_events() on the returned pointer.
 295  *
 296  * context:        An anonymous pointer that will be passed along to the callback when
 297  *                 an event occurs.
 298  *
 299  * client_queue:   Queue the client wants to schedule the callback on (Note: Must not be NULL)
 300  *
 301  * callback:       CallBack function for the client that indicates success or failure.
 302  *                 If the get_services call fails, response will be NULL and status
 303  *                 will indicate what went wrong.  No further callbacks can be expected
 304  *                 after this.   If the request succeeds, then the callback will be called
 305  *                 once immediately with the current service list, and then again whenever
 306  *                 the service list is updated.
 307  *
 308  * return value:   Returns kCTIStatus_NoError when no error otherwise returns an error code indicating
 309  *                 the error that occurred. Note: A return value of kCTIStatus_NoError does not mean
 310  *                 that the request succeeded, merely that it was successfully started.
 311  *
 312  */
 313
 314 DNS_SERVICES_EXPORT cti_status_t
 315 cti_get_service_list(cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_service_reply_t NONNULL callback,
 316                      dispatch_queue_t NONNULL client_queue);
 317
 318 /*
 319  * cti_service_vec_create
 320  *
 321  * creates a service array vector of specified length
 322  *
 323  * num_prefixes:     Number of prefix slots available in the prefix vector.
 324  *
 325  * return value:     NULL, if the call failed; otherwise a prefix vector capable of containing the requested number of
 326  *                   prefixes.
 327  */
 328 cti_prefix_vec_t *NULLABLE
 329 cti_prefix_vec_create_(size_t num_prefixes, const char *NONNULL file, int line);
 330 #define cti_prefix_vec_create(num_prefixes) cti_prefix_vec_create_(num_prefixes, __FILE__, __LINE__)
 331
 332 /*
 333  * cti_prefix_vec_release
 334  *
 335  * decrements the reference count on the provided prefix vector and, if it reaches zero, finalizes the prefix vector,
 336  * which calls cti_prefix_release on each prefix in the vector, potentially also finalizing them.
 337  *
 338  * num_prefixes:     Number of prefix slots available in the prefix vector.
 339  *
 340  * return value:     NULL, if the call failed; otherwise a prefix vector capable of containing the requested number of
 341  *                   prefixes.
 342  */
 343
 344 void
 345 cti_prefix_vec_release_(cti_prefix_vec_t *NONNULL prefixes, const char *NONNULL file, int line);
 346 #define cti_prefix_vec_release(prefixes) cti_prefix_vec_release(prefixes, __FILE__, __LINE__)
 347
 348 /*
 349  * cti_prefix_create
 350  *
 351  * Creates a prefix containing the specified information.   prefix and server are retained, and will be
 352  * freed using free() when the prefix object is finalized.   Caller must not retain or free these values, and
 353  * they must be allocated on the malloc heap.
 354  *
 355  * enterprise_number: The enterprise number for this prefix.
 356  *
 357  * prefix_type:      The prefix type, from the prefix data.
 358  *
 359  * prefix_version:   The prefix version, from the prefix data.
 360  *
 361  * server:            Server information for this prefix, stored in network byte order.   Format depends on prefix type.
 362  *
 363  * server_length:     Length of server information in bytes.
 364  *
 365  * flags:             Thread network status flags, e.g. NCP versue User
 366  *
 367  * return value:     NULL, if the call failed; otherwise a prefix object containing the specified state.
 368  */
 369
 370 cti_prefix_t *NULLABLE
 371 cti_prefix_create_(struct in6_addr *NONNULL prefix, int prefix_length, int metric, int flags,
 372                    const char *NONNULL file, int line);
 373 #define cti_prefix_create(prefix, prefix_length, metric, flags) \
 374     cti_prefix_create_(prefix, prefix_length, metric, flags, __FILE__, __LINE__)
 375
 376 /*
 377  * cti_prefix_vec_release
 378  *
 379  * decrements the reference count on the provided prefix vector and, if it reaches zero, finalizes the prefix vector,
 380  * which calls cti_prefix_release on each prefix in the vector, potentially also finalizing them.
 381  *
 382  * prefixes:         The prefix vector to release.
 383  *
 384  * return value:     NULL, if the call failed; otherwise a prefix vector capable of containing the requested number of
 385  *                   prefixes.
 386  */
 387
 388 void
 389 cti_prefix_release_(cti_prefix_t *NONNULL prefix, const char *NONNULL file, int line);
 390 #define cti_prefix_release(prefixes) cti_prefix_release(prefix, __FILE__, __LINE__)
 391
 392 /* cti_prefix_reply: Callback from cti_get_prefix_list()
 393  *
 394  * Called when an error occurs during processing of the cti_get_prefix_list call, or when a prefix
 395  * is added or removed.
 396  *
 397  * In the case of an error, the callback will not be called again, and the caller is responsible for
 398  * releasing the connection state and restarting if needed.
 399  *
 400  * The callback will be called once for each prefix present on the Thread network at the time
 401  * get_prefix_list() is first called, and then again whenever a prefix is added or removed.
 402  *
 403  * cti_reply parameters:
 404  *
 405  * context:           The context that was passed to the cti prefix call to which this is a callback.
 406  *
 407  * prefix_vec:        If status is kCTIStatus_NoError, a vector containing all of the prefixes that were reported in
 408  *                    this event.
 409  *
 410  * status:                Will be kCTIStatus_NoError if the prefix list request is successful, or
 411  *                    will indicate the failure that occurred.
 412  *
 413  */
 414
 415 typedef void
 416 (*cti_prefix_reply_t)(void *NULLABLE context, cti_prefix_vec_t *NONNULL prefixes, cti_status_t status);
 417
 418 /* cti_get_prefix_list
 419  *
 420  * Requests wpantund to immediately send the current list of off-mesh prefixes configured in the Thread
 421  * network data.  Whenever the prefix list is updated, the callback will be called again with the new
 422  * information.  A return value of kCTIStatus_NoError means that the caller can expect the reply callback to be
 423  * called at least once.  Any other error means that the request could not be sent, and the callback will
 424  * never be called.
 425  *
 426  * To discontinue receiving prefix add/remove callbacks, the calling program should call
 427  * cti_connection_ref_deallocate on the conn_ref returned by a successful call to get_prefix_list();
 428  *
 429  * ref:            A pointer to a reference to the connection is stored through ref if ref is not NULL.
 430  *                 When events are no longer needed, call cti_discontinue_events() on the returned pointer.
 431  *
 432  * context:        An anonymous pointer that will be passed along to the callback when
 433  *                 an event occurs.
 434  *
 435  * client_queue:   Queue the client wants to schedule the callback on (Note: Must not be NULL)
 436  *
 437  * callback:       CallBack function for the client that indicates success or failure.
 438  *
 439  * return value:   Returns kCTIStatus_NoError when no error otherwise returns an error code indicating
 440  *                 the error that occurred. Note: A return value of kCTIStatus_NoError does not mean
 441  *                 that the request succeeded, merely that it was successfully started.
 442  *
 443  */
 444
 445 DNS_SERVICES_EXPORT cti_status_t
 446 cti_get_prefix_list(cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_prefix_reply_t NONNULL callback,
 447                     dispatch_queue_t NONNULL client_queue);
 448
 449 /* cti_state_reply: Callback from cti_get_state()
 450  *
 451  * Called when an error occurs during processing of the cti_get_state call, or when network state
 452  * information is available.
 453  *
 454  * In the case of an error, the callback will not be called again, and the caller is responsible for
 455  * releasing the connection state and restarting if needed.
 456  *
 457  * The callback will be called initially to report the network state, and subsequently whenever the
 458  * network state changes.
 459  *
 460  * cti_reply parameters:
 461  *
 462  * context:           The context that was passed to the cti state call to which this is a callback.
 463  *
 464  * state:             The network state.
 465  *
 466  * status:                Will be kCTIStatus_NoError if the prefix list request is successful, or
 467  *                    will indicate the failure that occurred.
 468  *
 469  */
 470
 471 typedef void
 472 (*cti_state_reply_t)(void *NULLABLE context, cti_network_state_t state, cti_status_t status);
 473
 474 /* cti_get_state
 475  *
 476  * Requests wpantund to immediately send the current state of the thread network.  Whenever the thread
 477  * network state changes, the callback will be called again with the new state.  A return value of
 478  * kCTIStatus_NoError means that the caller can expect the reply callback to be called at least once.  Any
 479  * other error means that the request could not be sent, and the callback will never be called.
 480  *
 481  * To discontinue receiving state change callbacks, the calling program should call
 482  * cti_connection_ref_deallocate on the conn_ref returned by a successful call to cti_get_state();
 483  *
 484  * ref:            A pointer to a reference to the connection is stored through ref if ref is not NULL.
 485  *                 When events are no longer needed, call cti_discontinue_events() on the returned pointer.
 486  *
 487  * context:        An anonymous pointer that will be passed along to the callback when
 488  *                 an event occurs.
 489  * client_queue:   Queue the client wants to schedule the callback on (Note: Must not be NULL)
 490  *
 491  * callback:       CallBack function for the client that indicates success or failure.
 492  *
 493  * return value:   Returns kCTIStatus_NoError when no error otherwise returns an error code indicating
 494  *                 the error that occurred. Note: A return value of kCTIStatus_NoError does not mean
 495  *                 that the request succeeded, merely that it was successfully started.
 496  *
 497  */
 498
 499 DNS_SERVICES_EXPORT cti_status_t
 500 cti_get_state(cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_state_reply_t NONNULL callback,
 501               dispatch_queue_t NONNULL client_queue);
 502
 503 /* cti_partition_id_reply: Callback from cti_get_partition_id()
 504  *
 505  * Called when an error occurs during processing of the cti_get_partition_id call, or when network partition ID
 506  * information is available.
 507  *
 508  * In the case of an error, the callback will not be called again, and the caller is responsible for
 509  * releasing the connection partition_id and restarting if needed.
 510  *
 511  * The callback will be called initially to report the network partition ID, and subsequently whenever the
 512  * network partition ID changes.
 513  *
 514  * cti_reply parameters:
 515  *
 516  * context:           The context that was passed to the cti prefix call to which this is a callback.
 517  *
 518  * partition_id:      The network partition ID, or -1 if it is not known.
 519  *
 520  * status:                Will be kCTIStatus_NoError if the partition ID request is successful, or will indicate the failure
 521  *                    that occurred.
 522  *
 523  */
 524
 525 typedef void
 526 (*cti_partition_id_reply_t)(void *NULLABLE context, int32_t partition_id, cti_status_t status);
 527
 528 /* cti_get_partition_id
 529  *
 530  * Requests wpantund to immediately send the current partition_id of the thread network.  Whenever the thread
 531  * network partition_id changes, the callback will be called again with the new partition_id.  A return value of
 532  * kCTIStatus_NoError means that the caller can expect the reply callback to be called at least once.  Any
 533  * other error means that the request could not be sent, and the callback will never be called.
 534  *
 535  * To discontinue receiving partition_id change callbacks, the calling program should call
 536  * cti_connection_ref_deallocate on the conn_ref returned by a successful call to cti_get_partition_id();
 537  *
 538  * ref:            A pointer to a reference to the connection is stored through ref if ref is not NULL.
 539  *                 When events are no longer needed, call cti_discontinue_events() on the returned pointer.
 540  *
 541  * context:        An anonymous pointer that will be passed along to the callback when
 542  *                 an event occurs.
 543  * client_queue:   Queue the client wants to schedule the callback on (Note: Must not be NULL)
 544  *
 545  * callback:       CallBack function for the client that indicates success or failure.
 546  *
 547  * return value:   Returns kCTIStatus_NoError when no error otherwise returns an error code indicating
 548  *                 the error that occurred. Note: A return value of kCTIStatus_NoError does not mean
 549  *                 that the request succeeded, merely that it was successfully started.
 550  *
 551  */
 552
 553 DNS_SERVICES_EXPORT cti_status_t
 554 cti_get_partition_id(cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context,
 555                      cti_partition_id_reply_t NONNULL callback, dispatch_queue_t NONNULL client_queue);
 556
 557 /* cti_network_node_type_reply: Callback from cti_get_network_node_type()
 558  *
 559  * Called when an error occurs during processing of the cti_get_network_node_type call, or when network partition ID
 560  * information is available.
 561  *
 562  * In the case of an error, the callback will not be called again, and the caller is responsible for releasing the
 563  * connection network_node_type and restarting if needed.
 564  *
 565  * The callback will be called initially to report the network partition ID, and subsequently whenever the network
 566  * partition ID changes.
 567  *
 568  * cti_reply parameters:
 569  *
 570  * context:           The context that was passed to the cti prefix call to which this is a callback.
 571  *
 572  * network_node_type: The network node type, kCTI_NetworkNodeType_Unknown if it is not known.
 573  *
 574  * status:                Will be kCTIStatus_NoError if the partition ID request is successful, or will indicate the failure
 575  *                    that occurred.
 576  *
 577  */
 578
 579 typedef void
 580 (*cti_network_node_type_reply_t)(void *NULLABLE context, cti_network_node_type_t network_node_type, cti_status_t status);
 581
 582 /* cti_get_network_node_type
 583  *
 584  * Requests wpantund to immediately send the current network_node_type of the thread network.  Whenever the thread
 585  * network network_node_type changes, the callback will be called again with the new network_node_type.  A return value of
 586  * kCTIStatus_NoError means that the caller can expect the reply callback to be called at least once.  Any
 587  * other error means that the request could not be sent, and the callback will never be called.
 588  *
 589  * To discontinue receiving network_node_type change callbacks, the calling program should call
 590  * cti_connection_ref_deallocate on the conn_ref returned by a successful call to cti_get_network_node_type();
 591  *
 592  * ref:            A pointer to a reference to the connection is stored through ref if ref is not NULL.
 593  *                 When events are no longer needed, call cti_discontinue_events() on the returned pointer.
 594  *
 595  * context:        An anonymous pointer that will be passed along to the callback when
 596  *                 an event occurs.
 597  * client_queue:   Queue the client wants to schedule the callback on (Note: Must not be NULL)
 598  *
 599  * callback:       CallBack function for the client that indicates success or failure.
 600  *
 601  * return value:   Returns kCTIStatus_NoError when no error otherwise returns an error code indicating
 602  *                 the error that occurred. Note: A return value of kCTIStatus_NoError does not mean
 603  *                 that the request succeeded, merely that it was successfully started.
 604  *
 605  */
 606
 607 DNS_SERVICES_EXPORT cti_status_t
 608 cti_get_network_node_type(cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context,
 609                           cti_network_node_type_reply_t NONNULL callback, dispatch_queue_t NONNULL client_queue);
 610
 611 /* cti_add_service
 612  *
 613  * Requests wpantund to add the specified service to the thread network data.  A return value of
 614  * kCTIStatus_NoError means that the caller can expect the reply callback to be called with a success or fail
 615  * status exactly one time.  Any other error means that the request could not be sent, and the callback will
 616  * never be called.
 617  *
 618  * context:           An anonymous pointer that will be passed along to the callback when
 619  *                    an event occurs.
 620  *
 621  * client_queue:      Queue the client wants to schedule the callback on (Note: Must not be NULL)
 622  *
 623  * callback:          CallBack function for the client that indicates success or failure.
 624  *
 625  * enterprise_number: Contains the enterprise number of the service.
 626  *
 627  * service_data:      Typically four bytes, in network byte order, the first two bytes indicate
 628  *                    the type of service within the enterprise' number space, and the second
 629  *                    two bytes indicate the version number.
 630  *
 631  * service_data_len:  The length of the service data in bytes.
 632  *
 633  * server_data:       Typically four bytes, in network byte order, the first two bytes indicate
 634  *                    the type of service within the enterprise' number space, and the second
 635  *                    two bytes indicate the version number.
 636  *
 637  * server_data_len:   The length of the service data in bytes.
 638  *
 639  * return value:      Returns kCTIStatus_NoError when no error otherwise returns an error code indicating
 640  *                    the error that occurred. Note: A return value of kCTIStatus_NoError does not mean
 641  *                    that the request succeeded, merely that it was successfully started.
 642  *
 643  */
 644
 645 DNS_SERVICES_EXPORT cti_status_t
 646 cti_add_service(void *NULLABLE context, cti_reply_t NONNULL callback, dispatch_queue_t NONNULL client_queue,
 647                 uint32_t enterprise_number, const uint8_t *NONNULL service_data, size_t service_data_length,
 648                 const uint8_t *NONNULL server_data, size_t server_data_length);
 649
 650 /* cti_remove_service
 651  *
 652  * Requests wpantund to remove the specified service from the thread network data.  A return value of
 653  * kCTIStatus_NoError means that the caller can expect the reply callback to be called with a success or fail
 654  * status exactly one time.  Any other error means that the request could not be sent, and the callback will
 655  * never be called.
 656  *
 657  * context:           An anonymous pointer that will be passed along to the callback when
 658  *                    an event occurs.
 659  *
 660  * client_queue:      Queue the client wants to schedule the callback on (Note: Must not be NULL)
 661  *
 662  * enterprise_number: Contains the enterprise number of the service.
 663  *
 664  * service_data:      Typically four bytes, in network byte order, the first two bytes indicate
 665  *                    the type of service within the enterprise' number space, and the second
 666  *                    two bytes indicate the version number.
 667  *
 668  * service_data_len:  The length of the service data in bytes.
 669  *
 670  * callback:          callback function for the client that indicates success or failure.
 671  *
 672  * return value:      Returns kCTIStatus_NoError when no error otherwise returns an error code indicating
 673  *                    the error that occurred. Note: A return value of kCTIStatus_NoError does not mean
 674  *                    that the request succeeded, merely that it was successfully started.
 675  */
 676
 677 DNS_SERVICES_EXPORT cti_status_t
 678 cti_remove_service(void *NULLABLE context, cti_reply_t NONNULL callback, dispatch_queue_t NONNULL client_queue,
 679                    uint32_t enterprise_number, const uint8_t *NONNULL service_data,
 680                    size_t service_data_length);
 681
 682 /* cti_add_prefix
 683  *
 684  * Requests wpantund to add the specified prefix to the set of off-mesh prefixes configured on the thread
 685  * network.  A return value of kCTIStatus_NoError means that the caller can expect the reply callback to be
 686  * called with a success or fail status exactly one time.  Any other error means that the request could not
 687  * be sent, and the callback will never be called.
 688  *
 689  * context:        An anonymous pointer that will be passed along to the callback when
 690  *                 an event occurs.
 691  * client_queue:   Queue the client wants to schedule the callback on (Note: Must not be NULL)
 692  *
 693  * prefix:         A pointer to a struct in6_addr.  Must not be reatained by the callback.
 694  *
 695  * prefix_len:     The length of the prefix in bits.
 696  *
 697  * callback:       CallBack function for the client that indicates success or failure.
 698  *
 699  * return value:   Returns kCTIStatus_NoError when no error otherwise returns an error code indicating
 700  *                 the error that occurred. Note: A return value of kCTIStatus_NoError does not mean
 701  *                 that the request succeeded, merely that it was successfully started.
 702  *
 703  */
 704
 705 DNS_SERVICES_EXPORT cti_status_t
 706 cti_add_prefix(void *NULLABLE context, cti_reply_t NONNULL callback, dispatch_queue_t NONNULL client_queue,
 707                struct in6_addr *NONNULL prefix, int prefix_length, bool on_mesh, bool preferred, bool slaac,
 708                bool stable);
 709
 710 /* cti_remove_prefix
 711  *
 712  * Requests wpantund to remove the specified prefix from the set of off-mesh prefixes configured on the thread network.
 713  * A return value of kCTIStatus_NoError means that the caller can expect the reply callback to be called with a success
 714  * or fail status exactly one time.  Any other error means that the request could not be sent, and the callback will
 715  * never be called.
 716  *
 717  * context:        An anonymous pointer that will be passed along to the callback when
 718  *                 an event occurs.
 719  *
 720  * client_queue:   Queue the client wants to schedule the callback on (Note: Must not be NULL)
 721  *
 722  * prefix:         A pointer to a struct in6_addr.  Must not be reatained by the callback.
 723  *
 724  * prefix_len:     The length of the prefix in bits.
 725  *
 726  * callback:       CallBack function for the client that indicates success or failure.
 727  *
 728  * return value:   Returns kCTIStatus_NoError when no error otherwise returns an error code indicating
 729  *                 the error that occurred. Note: A return value of kCTIStatus_NoError does not mean
 730  *                 that the request succeeded, merely that it was successfully started.
 731  *
 732  */
 733
 734 DNS_SERVICES_EXPORT cti_status_t
 735 cti_remove_prefix(void *NULLABLE context, cti_reply_t NONNULL callback, dispatch_queue_t NONNULL client_queue,
 736                   struct in6_addr *NONNULL prefix, int prefix_length);
 737
 738 /* cti_events_discontinue
 739  *
 740  * Requests that the CTI library stop delivering events on the specified connection.   The connection will have
 741  * been returned by a CTI library call that subscribes to events.
 742  */
 743 DNS_SERVICES_EXPORT cti_status_t
 744 cti_events_discontinue(cti_connection_t NONNULL ref);
 745
 746 #endif /* CTI_SERVICES_H */
 747
 748 // Local Variables:
 749 // mode: C
 750 // tab-width: 4
 751 // c-file-style: "bsd"
 752 // c-basic-offset: 4
 753 // fill-column: 120
 754 // indent-tabs-mode: nil
 755 // End: