/* cti-services.h * * Copyright (c) 2020-2024 Apple Inc. All rights reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * * This code adds border router support to 3rd party HomeKit Routers as part of Apple’s commitment to the CHIP project. * * Concise Thread Interface for Thread Border router control. */ #ifndef __CTI_SERVICES_H__ #define __CTI_SERVICES_H__ #include #include typedef void *run_context_t; #include "srp.h" #if (defined(__GNUC__) && (__GNUC__ >= 4)) #define DNS_SERVICES_EXPORT __attribute__((visibility("default"))) #else #define DNS_SERVICES_EXPORT #endif #include "cti-common.h" typedef enum _offmesh_route_origin { offmesh_route_origin_user, offmesh_route_origin_ncp, } offmesh_route_origin_t; typedef enum _offmesh_route_preference { offmesh_route_preference_low = -1, offmesh_route_preference_medium, offmesh_route_preference_high, } offmesh_route_preference_t; typedef struct _cti_service { uint64_t enterprise_number; uint16_t service_type; uint16_t service_version; uint16_t rloc16; uint16_t service_id; uint8_t *NONNULL service; uint8_t *NONNULL server; size_t service_length; size_t server_length; int ref_count; int flags; // E.g., kCTIFlag_NCP } cti_service_t; typedef struct _cti_service_vec { size_t num; int ref_count; cti_service_t *NULLABLE *NONNULL services; } cti_service_vec_t; typedef struct _cti_prefix { struct in6_addr prefix; int prefix_length; int metric; int flags; int rloc; bool stable; bool ncp; int ref_count; } cti_prefix_t; // Bits in the prefix flags #define kCTIPriorityShift 14 #define kCTIPreferredShift 13 #define kCTISLAACShift 12 #define kCTIDHCPShift 11 #define kCTIConfigureShift 10 #define kCTIDefaultRouteShift 9 #define kCTIOnMeshShift 8 #define kCTIDNSShift 7 #define kCTIDPShift 6 // Priority values #define kCTIPriorityMedium 0 #define kCTIPriorityHigh 1 #define kCTIPriorityReserved 2 #define kCTIPriorityLow 3 // Macros to fetch values from the prefix flags #define CTI_PREFIX_FLAGS_PRIORITY(flags) (((flags) >> kCTIPriorityShift) & 3) #define CTI_PREFIX_FLAGS_PREFERRED(flags) (((flags) >> kCTIPreferredShift) & 1) #define CTI_PREFIX_FLAGS_SLAAC(flags) (((flags) >> kCTISLAACShift) & 1) #define CTI_PREFIX_FLAGS_DHCP(flags) (((flags) >> kCTIDHCPShift) & 1) #define CTI_PREFIX_FLAGS_CONFIGURE(flags) (((flags) >> kCTIConfigureShift) & 1) #define CTI_PREFIX_FLAGS_DEFAULT_ROUTE(flags) (((flags) >> kCTIDefaultRouteShift) & 1) #define CTI_PREFIX_FLAGS_ON_MESH(flags) (((flags) >> kCTIOnMeshShift) & 1) #define CTI_PREFIX_FLAGS_DNS(flags) (((flags) >> kCTIDNSShift) & 1) #define CTI_PREFIX_DLAGS_DP(flags) (((flags) >> kCTIDPShift) & 1) // Macros to set values in the prefix flags #define CTI_PREFIX_FLAGS_PRIORITY_SET(flags, value) ((flags) = \ (((flags) & ~(3 << kCTIPriorityShift)) | \ (((value) & 3) << kCTIPriorityShift))) #define CTI_PREFIX_FLAGS_PREFERRED_SET(flags, value) ((flags) = \ (((flags) & ~(1 << kCTIPreferredShift)) | \ (((value) & 1) << kCTIPreferredShift))) #define CTI_PREFIX_FLAGS_SLAAC_SET(flags, value) ((flags) = \ (((flags) & ~(1 << kCTISLAACShift)) | \ (((value) & 1) << kCTISLAACShift))) #define CTI_PREFIX_FLAGS_DHCP_SET(flags, value) ((flags) = \ (((flags) & ~(1 << kCTIDHCPShift)) | \ (((value) & 1) << kCTIDHCPShift))) #define CTI_PREFIX_FLAGS_CONFIGURE_SET(flags, value) ((flags) = \ (((flags) & ~(1 << kCTIConfigureShift)) | \ (((value) & 1) << kCTIConfigureShift))) #define CTI_PREFIX_FLAGS_DEFAULT_ROUTE_SET(flags, value) ((flags) = \ (((flags) & ~(1 << kCTIDefaultRouteShift)) | \ (((value) & 1) << kCTIDefaultRouteShift))) #define CTI_PREFIX_FLAGS_ON_MESH_SET(flags, value) ((flags) = \ (((flags) & ~(1 << kCTIOnMeshShift)) | \ (((value) & 1) << kCTIOnMeshShift))) #define CTI_PREFIX_FLAGS_DNS_SET(flags, value) ((flags) = \ (((flags) & ~(1 << kCTIDNSShift)) | \ (((value) & 1) << kCTIDNSShift))) #define CTI_PREFIX_DLAGS_DP_SET(flags, value) ((flags) = \ (((flags) & ~(1 << kCTIDPShift)) | \ (((value) & 1) << kCTIDPShift))) typedef struct _cti_prefix_vec { size_t num; int ref_count; cti_prefix_t *NULLABLE *NONNULL prefixes; } cti_prefix_vec_t; typedef struct _cti_route { struct in6_addr prefix; int prefix_length; offmesh_route_origin_t origin; bool nat64; bool stable; offmesh_route_preference_t preference; int rloc; bool next_hop_is_host; int ref_count; } cti_route_t; typedef struct _cti_route_vec { size_t num; int ref_count; cti_route_t *NULLABLE *NONNULL routes; } cti_route_vec_t; typedef struct srp_server_state srp_server_t; /* cti_reply: * * A general reply mechanism to indicate success or failure for a cti call that doesn't * return any data. * * cti_reply parameters: * * context: The context that was passed to the cti service call to which this is a callback. * * status: Will be kCTIStatus_NoError on success, otherwise will indicate the * failure that occurred. */ typedef void (*cti_reply_t)(void *NULLABLE context, cti_status_t status); /* cti_string_property_reply: Callback for get calls that fetch a string property * * Called exactly once in response to (for example) a cti_get_tunnel_name() or cti_get_on_link_prefix() call, either * with an error or with a string containing the response. * * cti_reply parameters: * * context: The context that was passed to the cti service call to which this is a callback. * * tunnel_name: If error is kCTIStatus_NoError, a string containing the name of the Thread * interface. * * status: Will be kCTIStatus_NoError on success, otherwise will indicate the * failure that occurred. */ typedef void (*cti_string_property_reply_t)(void *NULLABLE context, const char *NONNULL string, cti_status_t status); /* cti_get_tunnel_name * * Get the name of the tunnel that wpantund is presenting as the Thread network interface. * The tunnel name is passed to the reply callback if the request succeeds; otherwise an error * is either returned immediately or returned to the callback. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating the * error that occurred. Note: A return value of kCTIStatus_NoError does not mean that the * request succeeded, merely that it was successfully started. */ #define cti_get_tunnel_name(server, context, callback, client_queue) \ cti_get_tunnel_name_(server, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_get_tunnel_name_(srp_server_t *NULLABLE server, void *NULLABLE context, cti_string_property_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* cti_track_neighbor_ml_eid * * Track changes in our neighbor's mesh-local address (ML-EID). This makes sense when acting as an end device, not as a * router. The ML-EID tunnel is passed to the reply callback if the request succeeds; otherwise an error is either * returned immediately or returned to the callback. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating the * error that occurred. Note: A return value of kCTIStatus_NoError does not mean that the * request succeeded, merely that it was successfully started. */ #define cti_track_neighbor_ml_eid(server, ref, context, callback, client_queue) \ cti_track_neighbor_ml_eid_(server, ref, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_track_neighbor_ml_eid_(srp_server_t *NULLABLE server, cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_string_property_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* cti_get_mesh_local_prefix * * Get the mesh_local IPv6 prefix that is in use on the Thread mesh. The prefix is passed to the reply callback if the * request succeeds; otherwise an error is either returned immediately or returned to the callback. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating the * error that occurred. Note: A return value of kCTIStatus_NoError does not mean that the * request succeeded, merely that it was successfully started. */ #define cti_get_mesh_local_prefix(server, context, callback, client_queue) \ cti_get_mesh_local_prefix_(server, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_get_mesh_local_prefix_(srp_server_t *NULLABLE server, void *NULLABLE context, cti_string_property_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* cti_get_mesh_local_address * * Get the mesh_local IPv6 address that is in use on this device on the Thread mesh. The address is passed to the reply * callback if the request succeeds; otherwise an error is either returned immediately or returned to the callback. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating the * error that occurred. Note: A return value of kCTIStatus_NoError does not mean that the * request succeeded, merely that it was successfully started. */ #define cti_get_mesh_local_address(server, context, callback, client_queue) \ cti_get_mesh_local_address_(server, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_get_mesh_local_address_(srp_server_t *NULLABLE server, void *NULLABLE context, cti_string_property_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* * cti_service_vec_create * * creates a service array vector of specified length * * num_services: Number of service slots available in the service vector. * * return value: NULL, if the call failed; otherwise a service vector capable of containing the requested number of * services. */ cti_service_vec_t *NULLABLE cti_service_vec_create_(size_t num_services, const char *NONNULL file, int line); #define cti_service_vec_create(num_services) cti_service_vec_create_(num_services, __FILE__, __LINE__) /* * cti_service_vec_release * * decrements the reference count on the provided service vector and, if it reaches zero, finalizes the service vector, * which calls cti_service_release on each service in the vector, potentially also finalizing them. * * num_services: Number of service slots available in the service vector. * * return value: NULL, if the call failed; otherwise a service vector capable of containing the requested number of * services. */ void cti_service_vec_release_(cti_service_vec_t *NONNULL services, const char *NONNULL file, int line); #define cti_service_vec_release(services) cti_service_vec_release_(services, __FILE__, __LINE__) /* * cti_service_create * * Creates a service containing the specified information. service and server are retained, and will be * freed using free() when the service object is finalized. Caller must not retain or free these values, and * they must be allocated on the malloc heap. * * enterprise_number: The enterprise number for this service. * * service_type: The service type, from the service data. * * service_version: The service version, from the service data. * * server: Server information for this service, stored in network byte order. Format depends on service type. * * server_length: Length of server information in bytes. * * flags: Thread network status flags, e.g. NCP versue User * * return value: NULL, if the call failed; otherwise a service object containing the specified state. */ cti_service_t *NULLABLE cti_service_create_(uint64_t enterprise_number, uint16_t rloc16, uint16_t service_type, uint16_t service_version, uint8_t *NONNULL service, size_t service_length, uint8_t *NONNULL server, size_t server_length, uint16_t service_id, int flags, const char *NONNULL file, int line); #define cti_service_create(enterprise_number, rloc16, service_type, service_version, service, service_length, \ server, server_length, service_id, flags) \ cti_service_create_(enterprise_number, rloc16, service_type, service_version, service, service_length, \ server, server_length, service_id, flags, __FILE__, __LINE__) /* * cti_service_vec_release * * decrements the reference count on the provided service vector and, if it reaches zero, finalizes the service vector, * which calls cti_service_release on each service in the vector, potentially also finalizing them. * * services: The service vector to release * * return value: NULL, if the call failed; otherwise a service vector capable of containing the requested number of * services. */ void cti_service_release_(cti_service_t *NONNULL service, const char *NONNULL file, int line); #define cti_service_release(services) cti_service_release(service, __FILE__, __LINE__) /* cti_service_reply: Callback from cti_get_service_list() * * Called when an error occurs during processing of the cti_get_service_list call, or when data * is available in response to the call. * * In the case of an error, the callback will not be called again, and the caller is responsible for * releasing the connection state and restarting if needed. * * The callback will be called once immediately upon success, and once again each time the service list * is updated. If the callback wishes to retain either the cti_service_vec_t or any of the elements * of that vector, the appropriate retain function should be called; when the object is no longer needed, * the corresponding release call must be called. * * cti_reply parameters: * * context: The context that was passed to the cti service call to which this is a callback. * * services: If status is kCTIStatus_NoError, a cti_service_vec_t containing the list of services * provided in the update. * * status: Will be kCTIStatus_NoError if the service list request is successful, or * will indicate the failure that occurred. */ typedef void (*cti_service_reply_t)(void *NULLABLE context, cti_service_vec_t *NULLABLE services, cti_status_t status); /* cti_get_service_list * * Requests wpantund to immediately send the current list of services published in the Thread network data. * Whenever the service list is updated, the callback will be called again with the new information. A * return value of kCTIStatus_NoError means that the caller can expect the reply callback to be called at least * once. Any other error status means that the request could not be sent, and the callback will never be * called. * * To discontinue receiving service add/remove callbacks, the calling program should call * cti_connection_ref_deallocate on the conn_ref returned by a successful call to get_service_list(); * * ref: A pointer to a reference to the connection is stored through ref if ref is not NULL. * When events are no longer needed, call cti_discontinue_events() on the returned pointer. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure. * If the get_services call fails, response will be NULL and status * will indicate what went wrong. No further callbacks can be expected * after this. If the request succeeds, then the callback will be called * once immediately with the current service list, and then again whenever * the service list is updated. * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_get_service_list(server, ref, context, callback, client_queue) \ cti_get_service_list_(server, ref, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_get_service_list_(srp_server_t *NULLABLE server, cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_service_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* * cti_service_vec_create * * creates a service array vector of specified length * * num_prefixes: Number of prefix slots available in the prefix vector. * * return value: NULL, if the call failed; otherwise a prefix vector capable of containing the requested number of * prefixes. */ cti_prefix_vec_t *NULLABLE cti_prefix_vec_create_(size_t num_prefixes, const char *NONNULL file, int line); #define cti_prefix_vec_create(num_prefixes) cti_prefix_vec_create_(num_prefixes, __FILE__, __LINE__) /* * cti_prefix_vec_release * * decrements the reference count on the provided prefix vector and, if it reaches zero, finalizes the prefix vector, * which calls cti_prefix_release on each prefix in the vector, potentially also finalizing them. * * num_prefixes: Number of prefix slots available in the prefix vector. * * return value: NULL, if the call failed; otherwise a prefix vector capable of containing the requested number of * prefixes. */ void cti_prefix_vec_release_(cti_prefix_vec_t *NONNULL prefixes, const char *NONNULL file, int line); #define cti_prefix_vec_release(prefixes) cti_prefix_vec_release_(prefixes, __FILE__, __LINE__) /* * cti_prefix_create * * Creates a prefix containing the specified information. prefix and server are retained, and will be * freed using free() when the prefix object is finalized. Caller must not retain or free these values, and * they must be allocated on the malloc heap. * * enterprise_number: The enterprise number for this prefix. * * prefix_type: The prefix type, from the prefix data. * * prefix_version: The prefix version, from the prefix data. * * server: Server information for this prefix, stored in network byte order. Format depends on prefix type. * * server_length: Length of server information in bytes. * * flags: Thread network status flags, e.g. NCP versue User * * return value: NULL, if the call failed; otherwise a prefix object containing the specified state. */ cti_prefix_t *NULLABLE cti_prefix_create_(struct in6_addr *NONNULL prefix, int prefix_length, int metric, int flags, int rloc, bool stable, bool ncp, const char *NONNULL file, int line); #define cti_prefix_create(prefix, prefix_length, metric, flags, rloc, stable, ncp) \ cti_prefix_create_(prefix, prefix_length, metric, flags, rloc, stable, ncp, __FILE__, __LINE__) /* * cti_prefix_vec_release * * decrements the reference count on the provided prefix vector and, if it reaches zero, finalizes the prefix vector, * which calls cti_prefix_release on each prefix in the vector, potentially also finalizing them. * * prefixes: The prefix vector to release. * * return value: NULL, if the call failed; otherwise a prefix vector capable of containing the requested number of * prefixes. */ void cti_prefix_release_(cti_prefix_t *NONNULL prefix, const char *NONNULL file, int line); #define cti_prefix_release(prefixes) cti_prefix_release(prefix, __FILE__, __LINE__) /* cti_prefix_reply: Callback from cti_get_prefix_list() * * Called when an error occurs during processing of the cti_get_prefix_list call, or when a prefix * is added or removed. * * In the case of an error, the callback will not be called again, and the caller is responsible for * releasing the connection state and restarting if needed. * * The callback will be called once for each prefix present on the Thread network at the time * get_prefix_list() is first called, and then again whenever a prefix is added or removed. * * cti_reply parameters: * * context: The context that was passed to the cti prefix call to which this is a callback. * * prefix_vec: If status is kCTIStatus_NoError, a vector containing all of the prefixes that were reported in * this event. * * status: Will be kCTIStatus_NoError if the prefix list request is successful, or * will indicate the failure that occurred. */ typedef void (*cti_prefix_reply_t)(void *NULLABLE context, cti_prefix_vec_t *NULLABLE prefixes, cti_status_t status); /* cti_get_prefix_list * * Requests wpantund to immediately send the current list of off-mesh prefixes configured in the Thread * network data. Whenever the prefix list is updated, the callback will be called again with the new * information. A return value of kCTIStatus_NoError means that the caller can expect the reply callback to be * called at least once. Any other error means that the request could not be sent, and the callback will * never be called. * * To discontinue receiving prefix add/remove callbacks, the calling program should call * cti_connection_ref_deallocate on the conn_ref returned by a successful call to get_prefix_list(); * * ref: A pointer to a reference to the connection is stored through ref if ref is not NULL. * When events are no longer needed, call cti_discontinue_events() on the returned pointer. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_get_prefix_list(server, ref, context, callback, client_queue) \ cti_get_prefix_list_(server, ref, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_get_prefix_list_(srp_server_t *NULLABLE server, cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_prefix_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* cti_state_reply: Callback from cti_get_state() * * Called when an error occurs during processing of the cti_get_state call, or when network state * information is available. * * In the case of an error, the callback will not be called again, and the caller is responsible for * releasing the connection state and restarting if needed. * * The callback will be called initially to report the network state, and subsequently whenever the * network state changes. * * cti_reply parameters: * * context: The context that was passed to the cti state call to which this is a callback. * * state: The network state. * * status: Will be kCTIStatus_NoError if the prefix list request is successful, or * will indicate the failure that occurred. */ typedef void (*cti_state_reply_t)(void *NULLABLE context, cti_network_state_t state, cti_status_t status); /* cti_get_state * * Requests wpantund to immediately send the current state of the thread network. Whenever the thread * network state changes, the callback will be called again with the new state. A return value of * kCTIStatus_NoError means that the caller can expect the reply callback to be called at least once. Any * other error means that the request could not be sent, and the callback will never be called. * * To discontinue receiving state change callbacks, the calling program should call * cti_connection_ref_deallocate on the conn_ref returned by a successful call to cti_get_state(); * * ref: A pointer to a reference to the connection is stored through ref if ref is not NULL. * When events are no longer needed, call cti_discontinue_events() on the returned pointer. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_get_state(server, ref, context, callback, client_queue) \ cti_get_state_(server, ref, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_get_state_(srp_server_t *NULLABLE server, cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_state_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* cti_uint64_property_reply: Callback from cti_get_partition_id() or cti_get_xpanid() * * Called when an error occurs during processing of the cti_get_* call, or when a new value for the requested property * is available. * * In the case of an error, the callback will not be called again, and the caller is responsible for * releasing the connection and restarting if needed. * * The callback will be called initially to report the current value for the property, and subsequently whenever the * property changes. * * cti_uint64_property_reply parameters: * * context: The context that was passed to the cti prefix call to which this is a callback. * * property_value The value of the property (only valid if status is kCTIStatus_NoError). * * status: Will be kCTIStatus_NoError if the partition ID request is successful, or will indicate the failure * that occurred. */ typedef void (*cti_uint64_property_reply_t)(void *NULLABLE context, uint64_t property_value, cti_status_t status); /* cti_get_partition_id * * Requests wpantund to immediately send the current partition_id of the thread network. Whenever the thread * network partition_id changes, the callback will be called again with the new partition_id. A return value of * kCTIStatus_NoError means that the caller can expect the reply callback to be called at least once. Any * other error means that the request could not be sent, and the callback will never be called. * * To discontinue receiving partition_id change callbacks, the calling program should call * cti_connection_ref_deallocate on the conn_ref returned by a successful call to cti_get_partition_id(); * * ref: A pointer to a reference to the connection is stored through ref if ref is not NULL. * When events are no longer needed, call cti_discontinue_events() on the returned pointer. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_get_partition_id(server, ref, context, callback, client_queue) \ cti_get_partition_id_(server, ref, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_get_partition_id_(srp_server_t *NULLABLE server, cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_uint64_property_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* cti_get_extended_pan_id * * Requests wpantund to immediately send the current extended_pan_id of the thread network. Whenever the thread * network extended_pan_id changes, the callback will be called again with the new extended_pan_id. A return value of * kCTIStatus_NoError means that the caller can expect the reply callback to be called at least once. Any * other error means that the request could not be sent, and the callback will never be called. * * To discontinue receiving extended_pan_id change callbacks, the calling program should call * cti_connection_ref_deallocate on the conn_ref returned by a successful call to cti_get_extended_pan_id(); * * ref: A pointer to a reference to the connection is stored through ref if ref is not NULL. * When events are no longer needed, call cti_discontinue_events() on the returned pointer. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_get_extended_pan_id(server, ref, context, callback, client_queue) \ cti_get_extended_pan_id_(server, ref, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_get_extended_pan_id_(srp_server_t *NULLABLE server, cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_uint64_property_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* cti_network_node_type_reply: Callback from cti_get_network_node_type() * * Called when an error occurs during processing of the cti_get_network_node_type call, or when network partition ID * information is available. * * In the case of an error, the callback will not be called again, and the caller is responsible for releasing the * connection network_node_type and restarting if needed. * * The callback will be called initially to report the network partition ID, and subsequently whenever the network * partition ID changes. * * cti_reply parameters: * * context: The context that was passed to the cti prefix call to which this is a callback. * * network_node_type: The network node type, kCTI_NetworkNodeType_Unknown if it is not known. * * status: Will be kCTIStatus_NoError if the partition ID request is successful, or will indicate the failure * that occurred. */ typedef void (*cti_network_node_type_reply_t)(void *NULLABLE context, cti_network_node_type_t network_node_type, cti_status_t status); /* cti_get_network_node_type * * Requests wpantund to immediately send the current network_node_type of the thread network. Whenever the thread * network network_node_type changes, the callback will be called again with the new network_node_type. A return value of * kCTIStatus_NoError means that the caller can expect the reply callback to be called at least once. Any * other error means that the request could not be sent, and the callback will never be called. * * To discontinue receiving network_node_type change callbacks, the calling program should call * cti_connection_ref_deallocate on the conn_ref returned by a successful call to cti_get_network_node_type(); * * ref: A pointer to a reference to the connection is stored through ref if ref is not NULL. * When events are no longer needed, call cti_discontinue_events() on the returned pointer. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_get_network_node_type(server, ref, context, callback, client_queue) \ cti_get_network_node_type_(server, ref, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_get_network_node_type_(srp_server_t *NULLABLE server, cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_network_node_type_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* cti_add_service * * Requests wpantund to add the specified service to the thread network data. A return value of * kCTIStatus_NoError means that the caller can expect the reply callback to be called with a success or fail * status exactly one time. Any other error means that the request could not be sent, and the callback will * never be called. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * enterprise_number: Contains the enterprise number of the service. * * service_data: Typically four bytes, in network byte order, the first two bytes indicate * the type of service within the enterprise' number space, and the second * two bytes indicate the version number. * * service_data_len: The length of the service data in bytes. * * server_data: Typically four bytes, in network byte order, the first two bytes indicate * the type of service within the enterprise' number space, and the second * two bytes indicate the version number. * * server_data_len: The length of the service data in bytes. * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_add_service(server, context, callback, client_queue, \ enterprise_number, service_data, service_data_length, server_data, server_data_length) \ cti_add_service_(server, context, callback, client_queue, enterprise_number, \ service_data, service_data_length, server_data, server_data_length, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_add_service_(srp_server_t *NULLABLE server, void *NULLABLE context, cti_reply_t NONNULL callback, run_context_t NULLABLE client_queue, uint32_t enterprise_number, const uint8_t *NONNULL service_data, size_t service_data_length, const uint8_t *NULLABLE server_data, size_t server_data_length, const char *NONNULL file, int line); /* cti_remove_service * * Requests wpantund to remove the specified service from the thread network data. A return value of * kCTIStatus_NoError means that the caller can expect the reply callback to be called with a success or fail * status exactly one time. Any other error means that the request could not be sent, and the callback will * never be called. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: callback function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * enterprise_number: Contains the enterprise number of the service. * * service_data: Typically four bytes, in network byte order, the first two bytes indicate * the type of service within the enterprise' number space, and the second * two bytes indicate the version number. * * service_data_len: The length of the service data in bytes. * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_remove_service(server, context, callback, client_queue, \ enterprise_number, service_data, service_data_length) \ cti_remove_service_(server, context, callback, client_queue, \ enterprise_number, service_data, service_data_length, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_remove_service_(srp_server_t *NULLABLE server, void *NULLABLE context, cti_reply_t NONNULL callback, run_context_t NULLABLE client_queue, uint32_t enterprise_number, const uint8_t *NONNULL service_data, size_t service_data_length, const char *NONNULL file, int line); /* cti_add_prefix * * Requests wpantund to add the specified prefix to the set of off-mesh prefixes configured on the thread * network. A return value of kCTIStatus_NoError means that the caller can expect the reply callback to be * called with a success or fail status exactly one time. Any other error means that the request could not * be sent, and the callback will never be called. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * prefix: A pointer to a struct in6_addr. Must not be reatained by the callback. * * prefix_len: The length of the prefix in bits. * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_add_prefix(server, context, callback, client_queue, \ prefix, prefix_length, on_mesh, preferred, slaac, stable, priority) \ cti_add_prefix_(server, context, callback, client_queue, prefix, prefix_length, \ on_mesh, preferred, slaac, stable, priority, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_add_prefix_(srp_server_t *NULLABLE server, void *NULLABLE context, cti_reply_t NONNULL callback, run_context_t NULLABLE client_queue, struct in6_addr *NONNULL prefix, int prefix_length, bool on_mesh, bool preferred, bool slaac, bool stable, int priority, const char *NONNULL file, int line); /* cti_remove_prefix * * Requests wpantund to remove the specified prefix from the set of off-mesh prefixes configured on the thread network. * A return value of kCTIStatus_NoError means that the caller can expect the reply callback to be called with a success * or fail status exactly one time. Any other error means that the request could not be sent, and the callback will * never be called. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * prefix: A pointer to a struct in6_addr. Must not be reatained by the callback. * * prefix_len: The length of the prefix in bits. * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_remove_prefix(server, context, callback, client_queue, prefix, prefix_length) \ cti_remove_prefix_(server, context, callback, client_queue, prefix, prefix_length, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_remove_prefix_(srp_server_t *NULLABLE server, void *NULLABLE context, cti_reply_t NONNULL callback, run_context_t NULLABLE client_queue, struct in6_addr *NONNULL prefix, int prefix_length, const char *NONNULL file, int line); /* cti_add_route * * Requests wpantund to add the specified route on the thread network. * A return value of kCTIStatus_NoError means that the caller can expect the reply callback to be * called with a success or fail status exactly one time. Any other error means that the request could not * be sent, and the callback will never be called. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * prefix: A pointer to a struct in6_addr. * * prefix_len: The length of the prefix in bits. * * priority: Route priority (>0 for high, 0 for medium, <0 for low). * * domain_id: Domain id for the route (default is zero). * * stable: True if the route is part of stable network data. * * nat64: True if this is NAT64 prefix. * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_add_route(server, context, callback, client_queue, \ prefix, prefix_length, priority, domain_id, stable, nat64) \ cti_add_route_(server, context, callback, client_queue, prefix, prefix_length, \ priority, domain_id, stable, nat64, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_add_route_(srp_server_t *NULLABLE server, void *NULLABLE context, cti_reply_t NONNULL callback, run_context_t NULLABLE client_queue, struct in6_addr *NONNULL prefix, int prefix_length, int priority, int domain_id, bool stable, bool nat64, const char *NONNULL file, int line); /* cti_remove_route * * Requests wpantund to remove the specified route on the thread network. * A return value of kCTIStatus_NoError means that the caller can expect the reply callback to be called with a success * or fail status exactly one time. Any other error means that the request could not be sent, and the callback will * never be called. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * prefix: A pointer to a struct in6_addr. * * prefix_len: The length of the prefix in bits. * * domain_id: Domain id for the route (default is zero). * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_remove_route(server, context, callback, client_queue, prefix, prefix_length, domain_id) \ cti_remove_route_(server, context, callback, client_queue, prefix, prefix_length, domain_id, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_remove_route_(srp_server_t *NULLABLE server, void *NULLABLE context, cti_reply_t NONNULL callback, run_context_t NULLABLE client_queue, struct in6_addr *NONNULL prefix, int prefix_length, int domain_id, const char *NONNULL file, int line); /* * cti_route_vec_create * * creates a route array vector of specified length * * num_routes: Number of route slots available in the route vector. * * return value: NULL, if the call failed; otherwise a prefix vector capable of containing the * requested number of routes. */ cti_route_vec_t *NULLABLE cti_route_vec_create_(size_t num_routes, const char *NONNULL file, int line); #define cti_route_vec_create(num_routes) cti_route_vec_create_(num_routes, __FILE__, __LINE__) /* * cti_route_vec_release * * decrements the reference count on the provided route vector and, if it reaches zero, finalizes the route vector, * which calls cti_route_release on each route in the vector, potentially also finalizing them. * * num_routes: Number of route slots available in the route vector. * * return value: NULL, if the call failed; otherwise a route vector capable of containing the * requested number of routes. */ void cti_route_vec_release_(cti_route_vec_t *NONNULL routes, const char *NONNULL file, int line); #define cti_route_vec_release(routes) cti_route_vec_release_(routes, __FILE__, __LINE__) /* * cti_route_create * * Creates a cti_route_t containing the specified information. The route is retained, and will be * freed using free() when the route object is finalized. Caller must not retain or free these values, and * they must be allocated on the malloc heap. * * prefix: A pointer to a struct in6_addr. * * prefix_len: The length of the prefix in bits. * * origin: User or ncp. * * nat64: True if this is NAT64 prefix. * * stable: True if the route is part of stable network data. * * preference: Route priority. * * rloc: Routing locator. * * next_hop_is_host: True if next hop is host. * * return value: NULL, if the call failed; otherwise a route object containing the specified state. */ cti_route_t *NULLABLE cti_route_create_(struct in6_addr *NONNULL prefix, int prefix_length, offmesh_route_origin_t origin, bool nat64, bool stable, offmesh_route_preference_t preference, int rloc, bool next_hop_is_host, const char *NONNULL file, int line); #define cti_route_create(prefix, prefix_length, origin, nat64, stable, preference, rloc, next_hop_is_host) \ cti_route_create_(prefix, prefix_length, origin, nat64, stable, preference, rloc, next_hop_is_host, __FILE__, __LINE__) /* * cti_route_release * * Decrements the reference count on the provided route vector and, if it reaches zero, finalizes the route vector, * which calls cti_route_release on each route in the vector, potentially also finalizing them. * * routes: The route vector to release. * * return value: NULL, if the call failed; otherwise a route vector capable of containing the requested number of * routes. */ void cti_route_release_(cti_route_t *NONNULL route, const char *NONNULL file, int line); #define cti_route_release(routes) cti_route_release(route, __FILE__, __LINE__) /* cti_offmesh_route_reply: Callback from cti_get_offmesh_route_list() * * Called when an error occurs during processing of the cti_get_offmesh_route_list call, or when a route * is added or removed. * * In the case of an error, the callback will not be called again, and the caller is responsible for * releasing the connection state and restarting if needed. * * The callback will be called once for each offmesh route present on the Thread network at the time * cti_get_offmesh_prefix_list() is first called, and then again whenever a route is added or removed. * * cti_offmesh_route_reply parameters: * * context: The context that was passed to the cti_get_offmesh_route_list call to which this is a callback. * * route_vec: If status is kCTIStatus_NoError, a vector containing all of the routes that were reported in * this event. * * status: Will be kCTIStatus_NoError if the offmesh route list request is successful, or * will indicate the failure that occurred. */ typedef void (*cti_offmesh_route_reply_t)(void *NULLABLE context, cti_route_vec_t *NULLABLE routes, cti_status_t status); /* cti_get_offmesh_route_list * * Requests wpantund to immediately send the current list of off-mesh routes configured in the Thread * network data. Whenever the route list is updated, the callback will be called again with the new * information. A return value of kCTIStatus_NoError means that the caller can expect the reply callback to be * called at least once. Any other error means that the request could not be sent, and the callback will * never be called. * * ref: A pointer to a reference to the connection is stored through ref if ref is not NULL. * When events are no longer needed, call cti_discontinue_events() on the returned pointer. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_get_offmesh_route_list(server, ref, context, callback, client_queue) \ cti_get_offmesh_route_list_(server, ref, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_get_offmesh_route_list_(srp_server_t *NULLABLE server, cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_offmesh_route_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* cti_onmesh_prefix_reply: Callback from cti_get_onmesh_prefix_list() * * Called when an error occurs during processing of the cti_get_onmesh_prefix_list call, or when a route * is added or removed. * * In the case of an error, the callback will not be called again, and the caller is responsible for * releasing the connection state and restarting if needed. * * The callback will be called once for each offmesh route present on the Thread network at the time * cti_get_offmesh_prefix_list() is first called, and then again whenever a route is added or removed. * * cti_onmesh_prefix_reply parameters: * * context: The context that was passed to the cti_get_onmesh_prefix_list call to which this is a callback. * * prefix_vec: If status is kCTIStatus_NoError, a vector containing all of the prefixes that were reported in * this event. * * status: Will be kCTIStatus_NoError if the onmesh prefix list request is successful, or * will indicate the failure that occurred. */ typedef void (*cti_onmesh_prefix_reply_t)(void *NULLABLE context, cti_prefix_vec_t *NULLABLE routes, cti_status_t status); /* cti_get_onmesh_prefix_list * * Requests wpantund to immediately send the current list of on-mesh prefixes configured in the Thread * network data. Whenever the prefix list is updated, the callback will be called again with the new * information. A return value of kCTIStatus_NoError means that the caller can expect the reply callback to be * called at least once. Any other error means that the request could not be sent, and the callback will * never be called. * * ref: A pointer to a reference to the connection is stored through ref if ref is not NULL. * When events are no longer needed, call cti_discontinue_events() on the returned pointer. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_get_onmesh_prefix_list(server, ref, context, callback, client_queue) \ cti_get_onmesh_prefix_list_(server, ref, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_get_onmesh_prefix_list_(srp_server_t *NULLABLE server, cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_onmesh_prefix_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* cti_rloc16_reply: Callback from cti_get_rloc16() * * Called when an error occurs during processing of the cti_get_rloc16 call, or when rloc16 * is updated. * * In the case of an error, the callback will not be called again, and the caller is responsible for * releasing the connection state and restarting if needed. * * The callback will be called initially to report the current value for the property, and subsequently * whenever the property changes. * * cti_rloc16_reply parameters: * * context: The context that was passed to the cti call to which this is a callback. * * rloc16: The rloc16 value(only valid if status is kCTIStatus_NoError). * * status: Will be kCTIStatus_NoError if the rloc16 request is successful, or will indicate the failure * that occurred. */ typedef void (*cti_rloc16_reply_t)(void *NULLABLE context, uint16_t rloc16, cti_status_t status); /* cti_get_rloc16 * * Requests wpantund to immediately send the rloc16 of the local device. Whenever the RLOC16 * changes, the callback will be called again with the new RLOC16. A return value of * kCTIStatus_NoError means that the caller can expect the reply callback to be called at least once. Any * other error means that the request could not be sent, and the callback will never be called. * * ref: A pointer to a reference to the connection is stored through ref if ref is not NULL. * When events are no longer needed, call cti_discontinue_events() on the returned pointer. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_get_rloc16(server, ref, context, callback, client_queue) \ cti_get_rloc16_(server, ref, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_get_rloc16_(srp_server_t *NULLABLE server, cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_rloc16_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* cti_active_data_set_change_reply: Callback from cti_get_active_data_set_change() * * Called when an error occurs during processing of the cti_get_active_data_set_change call, or when the active data set * is updated. * * In the case of an error, the callback will not be called again, and the caller is responsible for * releasing the connection state and restarting if needed. * * The callback will be called whenever the active data set changes. * * cti_active_data_set_change_reply parameters: * * context: The context that was passed to the cti call to which this is a callback. * * status: Will be kCTIStatus_NoError if the active_data_set_change request is successful, or will indicate the failure * that occurred. */ typedef void (*cti_reply_t)(void *NULLABLE context, cti_status_t status); /* cti_get_active_data_set_change * * Requests wpantund to immediately send the active_data_set_change of the local device. Whenever the ACTIVE_DATA_SET_CHANGE * changes, the callback will be called again with the new ACTIVE_DATA_SET_CHANGE. A return value of * kCTIStatus_NoError means that the caller can expect the reply callback to be called at least once. Any * other error means that the request could not be sent, and the callback will never be called. * * ref: A pointer to a reference to the connection is stored through ref if ref is not NULL. * When events are no longer needed, call cti_discontinue_events() on the returned pointer. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * callback: CallBack function for the client that indicates success or failure. * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_track_active_data_set(server, ref, context, callback, client_queue) \ cti_track_active_data_set_(server, ref, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_track_active_data_set_(srp_server_t *NULLABLE server, cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* cti_wed_change_reply: Callback from cti_get_wed_change() * * Called when an error occurs during processing of the cti_get_wed_change call, or when the active data set * is updated. * * In the case of an error, the callback will not be called again, and the caller is responsible for * releasing the connection state and restarting if needed. * * The callback will be called whenever the active data set changes. * * cti_wed_change_reply parameters: * * context: The context that was passed to the cti call to which this is a callback. * * status: Will be kCTIStatus_NoError if the wed_change request is successful, or will indicate the failure * that occurred. */ typedef void (*cti_reply_t)(void *NULLABLE context, cti_status_t status); /* cti_wed_reply: Callback for get calls that fetch the current WED status * * Called one or more times in response to a cti_track_wed_status() call, either with an error or with the current WED status. * * cti_wed_reply parameters: * * context: The context that was passed to the cti service call to which this is a callback. * * ext_address: If error is kCTIStatus_NoError, a string containing the name of the ext address. * * ml_eid: If error is kCTIStatus_NoError, a string containing the ML-EID * * added: If true, this was added; otherwise it was removed. * * status: Will be kCTIStatus_NoError on success, otherwise will indicate the * failure that occurred. */ typedef void (*cti_wed_reply_t)(void *NULLABLE context, const char *NULLABLE ext_address, const char *NULLABLE ml_eid, bool added, cti_status_t status); /* cti_get_wed_change * * Requests wpantund to immediately send the WED attachment status of the local device. Whenever the WED attachment * status changes, the callback will be called again with the new status. A return value of kCTIStatus_NoError means * that the caller can expect the reply callback to be called at least once. Any other error means that the request * could not be sent, and the callback will never be called. * * ref: A pointer to a reference to the connection is stored through ref if ref is not NULL. * When events are no longer needed, call cti_discontinue_events() on the returned pointer. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure, and on success * indicates attachment to a Wake-on End Device (WED). * * client_queue: Queue the client wants to schedule the callback on * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_track_wed_status(server, ref, context, callback, client_queue) \ cti_track_wed_status_(server, ref, context, callback, client_queue, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_track_wed_status_(srp_server_t *NULLABLE server, cti_connection_t NULLABLE *NULLABLE ref, void *NULLABLE context, cti_wed_reply_t NONNULL callback, run_context_t NULLABLE client_queue, const char *NONNULL file, int line); /* cti_add_ml_eid_mapping * * Provides the thread daemon with a mapping between an IP address registered by an SRP client and * the source address from which the registration was received, which will be the client's ml-eid. * Additionally provides the client's hostname. * * context: An anonymous pointer that will be passed along to the callback when * an event occurs. * * callback: CallBack function for the client that indicates success or failure, and on success * indicates that the update was accepted by the thread daemon. * * omr_addr: IP address on the OMR prefix registered by the client. * * ml_eid: IP address on the mesh-local prefix of the client. * * client_queue: Queue the client wants to schedule the callback on * * * return value: Returns kCTIStatus_NoError when no error otherwise returns an error code indicating * the error that occurred. Note: A return value of kCTIStatus_NoError does not mean * that the request succeeded, merely that it was successfully started. */ #define cti_add_ml_eid_mapping(server, context, callback, client_queue, omr_addr, ml_eid, hostname) \ cti_add_ml_eid_mapping_(server, context, callback, client_queue, omr_addr, ml_eid, hostname, __FILE__, __LINE__) DNS_SERVICES_EXPORT cti_status_t cti_add_ml_eid_mapping_(srp_server_t *NULLABLE server, void *NULLABLE context, cti_reply_t NONNULL callback, run_context_t NULLABLE client_queue, struct in6_addr *NONNULL omr_addr, struct in6_addr *NONNULL ml_eid, const char *NONNULL hostname, const char *NONNULL file, int line); /* cti_events_discontinue * * Requests that the CTI library stop delivering events on the specified connection. The connection will have * been returned by a CTI library call that subscribes to events. */ DNS_SERVICES_EXPORT cti_status_t cti_events_discontinue(cti_connection_t NONNULL ref); typedef union cti_callback { cti_reply_t NULLABLE reply; cti_string_property_reply_t NONNULL string_property_reply; cti_service_reply_t NONNULL service_reply; cti_prefix_reply_t NONNULL prefix_reply; cti_state_reply_t NONNULL state_reply; cti_uint64_property_reply_t NONNULL uint64_property_reply; cti_network_node_type_reply_t NONNULL network_node_type_reply; cti_offmesh_route_reply_t NONNULL offmesh_route_reply; cti_onmesh_prefix_reply_t NONNULL onmesh_prefix_reply; cti_rloc16_reply_t NONNULL rloc16_reply; cti_wed_reply_t NONNULL wed_reply; } cti_callback_t; #endif /* __CTI_SERVICES_H__ */ // Local Variables: // mode: C // tab-width: 4 // c-file-style: "bsd" // c-basic-offset: 4 // fill-column: 120 // indent-tabs-mode: nil // End: