1 /* 2 * Copyright (c) 2020, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file defines the API for server of the Service Registration Protocol (SRP). 33 */ 34 35 #ifndef OPENTHREAD_SRP_SERVER_H_ 36 #define OPENTHREAD_SRP_SERVER_H_ 37 38 #include <stdint.h> 39 40 #include <openthread/dns.h> 41 #include <openthread/instance.h> 42 #include <openthread/ip6.h> 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @addtogroup api-srp 50 * 51 * @brief 52 * This module includes functions of the Service Registration Protocol. 53 * 54 * @{ 55 * 56 */ 57 58 /** 59 * This opaque type represents a SRP service host. 60 * 61 */ 62 typedef void otSrpServerHost; 63 64 /** 65 * This opaque type represents a SRP service. 66 * 67 */ 68 typedef void otSrpServerService; 69 70 /** 71 * The ID of a SRP service update transaction on the SRP Server. 72 * 73 */ 74 typedef uint32_t otSrpServerServiceUpdateId; 75 76 /** 77 * The service flag type to indicate which services to include or exclude when searching in (or iterating over) the 78 * list of SRP services. 79 * 80 * This is a combination of bit-flags. The specific bit-flags are defined in the enumeration `OT_SRP_SERVER_FLAG_*`. 81 * 82 */ 83 typedef uint8_t otSrpServerServiceFlags; 84 85 enum 86 { 87 OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE = 1 << 0, ///< Include base services (not a sub-type). 88 OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE = 1 << 1, ///< Include sub-type services. 89 OT_SRP_SERVER_SERVICE_FLAG_ACTIVE = 1 << 2, ///< Include active (not deleted) services. 90 OT_SRP_SERVER_SERVICE_FLAG_DELETED = 1 << 3, ///< Include deleted services. 91 }; 92 93 enum 94 { 95 /** 96 * This constant defines an `otSrpServerServiceFlags` combination accepting any service (base/sub-type, 97 * active/deleted). 98 * 99 */ 100 OT_SRP_SERVER_FLAGS_ANY_SERVICE = (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE | 101 OT_SRP_SERVER_SERVICE_FLAG_ACTIVE | OT_SRP_SERVER_SERVICE_FLAG_DELETED), 102 103 /** 104 * This constant defines an `otSrpServerServiceFlags` combination accepting base service only. 105 * 106 */ 107 OT_SRP_SERVER_FLAGS_BASE_TYPE_SERVICE_ONLY = 108 (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_ACTIVE | OT_SRP_SERVER_SERVICE_FLAG_DELETED), 109 110 /** 111 * This constant defines an `otSrpServerServiceFlags` combination accepting sub-type service only. 112 * 113 */ 114 OT_SRP_SERVER_FLAGS_SUB_TYPE_SERVICE_ONLY = 115 (OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE | OT_SRP_SERVER_SERVICE_FLAG_ACTIVE | OT_SRP_SERVER_SERVICE_FLAG_DELETED), 116 117 /** 118 * This constant defines an `otSrpServerServiceFlags` combination accepting any active service (not deleted). 119 * 120 */ 121 OT_SRP_SERVER_FLAGS_ANY_TYPE_ACTIVE_SERVICE = 122 (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE | 123 OT_SRP_SERVER_SERVICE_FLAG_ACTIVE), 124 125 /** 126 * This constant defines an `otSrpServerServiceFlags` combination accepting any deleted service. 127 * 128 */ 129 OT_SRP_SERVER_FLAGS_ANY_TYPE_DELETED_SERVICE = 130 (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE | 131 OT_SRP_SERVER_SERVICE_FLAG_ACTIVE), 132 }; 133 134 /** 135 * Represents the state of an SRP server 136 * 137 */ 138 typedef enum 139 { 140 OT_SRP_SERVER_STATE_DISABLED = 0, ///< The SRP server is disabled. 141 OT_SRP_SERVER_STATE_RUNNING = 1, ///< The SRP server is running. 142 OT_SRP_SERVER_STATE_STOPPED = 2, ///< The SRP server is stopped. 143 } otSrpServerState; 144 145 /** 146 * This structure includes SRP server LEASE and KEY-LEASE configurations. 147 * 148 */ 149 typedef struct otSrpServerLeaseConfig 150 { 151 uint32_t mMinLease; ///< The minimum LEASE interval in seconds. 152 uint32_t mMaxLease; ///< The maximum LEASE interval in seconds. 153 uint32_t mMinKeyLease; ///< The minimum KEY-LEASE interval in seconds. 154 uint32_t mMaxKeyLease; ///< The maximum KEY-LEASE interval in seconds. 155 } otSrpServerLeaseConfig; 156 157 /** 158 * This function returns the domain authorized to the SRP server. 159 * 160 * If the domain if not set by SetDomain, "default.service.arpa." will be returned. 161 * A trailing dot is always appended even if the domain is set without it. 162 * 163 * @param[in] aInstance A pointer to an OpenThread instance. 164 * 165 * @returns A pointer to the dot-joined domain string. 166 * 167 */ 168 const char *otSrpServerGetDomain(otInstance *aInstance); 169 170 /** 171 * This function sets the domain on the SRP server. 172 * 173 * A trailing dot will be appended to @p aDomain if it is not already there. 174 * This function should only be called before the SRP server is enabled. 175 * 176 * @param[in] aInstance A pointer to an OpenThread instance. 177 * @param[in] aDomain The domain to be set. MUST NOT be NULL. 178 * 179 * @retval OT_ERROR_NONE Successfully set the domain to @p aDomain. 180 * @retval OT_ERROR_INVALID_STATE The SRP server is already enabled and the Domain cannot be changed. 181 * @retval OT_ERROR_INVALID_ARGS The argument @p aDomain is not a valid DNS domain name. 182 * @retval OT_ERROR_NO_BUFS There is no memory to store content of @p aDomain. 183 * 184 */ 185 otError otSrpServerSetDomain(otInstance *aInstance, const char *aDomain); 186 187 /** 188 * This function returns the state of the SRP server. 189 * 190 * @param[in] aInstance A pointer to an OpenThread instance. 191 * 192 * @returns The current state of the SRP server. 193 * 194 */ 195 otSrpServerState otSrpServerGetState(otInstance *aInstance); 196 197 /** 198 * This function enables/disables the SRP server. 199 * 200 * @param[in] aInstance A pointer to an OpenThread instance. 201 * @param[in] aEnabled A boolean to enable/disable the SRP server. 202 * 203 */ 204 void otSrpServerSetEnabled(otInstance *aInstance, bool aEnabled); 205 206 /** 207 * This function returns SRP server LEASE and KEY-LEASE configurations. 208 * 209 * @param[in] aInstance A pointer to an OpenThread instance. 210 * @param[out] aLeaseConfig A pointer to an `otSrpServerLeaseConfig` instance. 211 * 212 */ 213 void otSrpServerGetLeaseConfig(otInstance *aInstance, otSrpServerLeaseConfig *aLeaseConfig); 214 215 /** 216 * This function sets SRP server LEASE and KEY-LEASE configurations. 217 * 218 * When a non-zero LEASE time is requested from a client, the granted value will be 219 * limited in range [aMinLease, aMaxLease]; and a non-zero KEY-LEASE will be granted 220 * in range [aMinKeyLease, aMaxKeyLease]. For zero LEASE or KEY-LEASE time, zero will 221 * be granted. 222 * 223 * @param[in] aInstance A pointer to an OpenThread instance. 224 * @param[in] aLeaseConfig A pointer to an `otSrpServerLeaseConfig` instance. 225 * 226 * @retval OT_ERROR_NONE Successfully set the LEASE and KEY-LEASE ranges. 227 * @retval OT_ERROR_INVALID_ARGS The LEASE or KEY-LEASE range is not valid. 228 * 229 */ 230 otError otSrpServerSetLeaseConfig(otInstance *aInstance, const otSrpServerLeaseConfig *aLeaseConfig); 231 232 /** 233 * This function handles SRP service updates. 234 * 235 * This function is called by the SRP server to notify that a SRP host and possibly SRP services 236 * are being updated. It is important that the SRP updates are not committed until the handler 237 * returns the result by calling otSrpServerHandleServiceUpdateResult or times out after @p aTimeout. 238 * 239 * A SRP service observer should always call otSrpServerHandleServiceUpdateResult with error code 240 * OT_ERROR_NONE immediately after receiving the update events. 241 * 242 * A more generic handler may perform validations on the SRP host/services and rejects the SRP updates 243 * if any validation fails. For example, an Advertising Proxy should advertise (or remove) the host and 244 * services on a multicast-capable link and returns specific error code if any failure occurs. 245 * 246 * @param[in] aId The service update transaction ID. This ID must be passed back with 247 * `otSrpServerHandleServiceUpdateResult`. 248 * @param[in] aHost A pointer to the otSrpServerHost object which contains the SRP updates. The 249 * handler should publish/un-publish the host and each service points to this 250 * host with below rules: 251 * 1. If the host is not deleted (indicated by `otSrpServerHostIsDeleted`), 252 * then it should be published or updated with mDNS. Otherwise, the host 253 * should be un-published (remove AAAA RRs). 254 * 2. For each service points to this host, it must be un-published if the host 255 * is to be un-published. Otherwise, the handler should publish or update the 256 * service when it is not deleted (indicated by `otSrpServerServiceIsDeleted`) 257 * and un-publish it when deleted. 258 * @param[in] aTimeout The maximum time in milliseconds for the handler to process the service event. 259 * @param[in] aContext A pointer to application-specific context. 260 * 261 * @sa otSrpServerSetServiceUpdateHandler 262 * @sa otSrpServerHandleServiceUpdateResult 263 * 264 */ 265 typedef void (*otSrpServerServiceUpdateHandler)(otSrpServerServiceUpdateId aId, 266 const otSrpServerHost * aHost, 267 uint32_t aTimeout, 268 void * aContext); 269 270 /** 271 * This function sets the SRP service updates handler on SRP server. 272 * 273 * @param[in] aInstance A pointer to an OpenThread instance. 274 * @param[in] aServiceHandler A pointer to a service handler. Use NULL to remove the handler. 275 * @param[in] aContext A pointer to arbitrary context information. 276 * May be NULL if not used. 277 * 278 */ 279 void otSrpServerSetServiceUpdateHandler(otInstance * aInstance, 280 otSrpServerServiceUpdateHandler aServiceHandler, 281 void * aContext); 282 283 /** 284 * This function reports the result of processing a SRP update to the SRP server. 285 * 286 * The Service Update Handler should call this function to return the result of its 287 * processing of a SRP update. 288 * 289 * @param[in] aInstance A pointer to an OpenThread instance. 290 * @param[in] aId The service update transaction ID. This should be the same ID 291 * provided via `otSrpServerServiceUpdateHandler`. 292 * @param[in] aError An error to be returned to the SRP server. Use OT_ERROR_DUPLICATED 293 * to represent DNS name conflicts. 294 * 295 */ 296 void otSrpServerHandleServiceUpdateResult(otInstance *aInstance, otSrpServerServiceUpdateId aId, otError aError); 297 298 /** 299 * This function returns the next registered host on the SRP server. 300 * 301 * @param[in] aInstance A pointer to an OpenThread instance. 302 * @param[in] aHost A pointer to current host; use NULL to get the first host. 303 * 304 * @returns A pointer to the registered host. NULL, if no more hosts can be found. 305 * 306 */ 307 const otSrpServerHost *otSrpServerGetNextHost(otInstance *aInstance, const otSrpServerHost *aHost); 308 309 /** 310 * This function tells if the SRP service host has been deleted. 311 * 312 * A SRP service host can be deleted but retains its name for future uses. 313 * In this case, the host instance is not removed from the SRP server/registry. 314 * 315 * @param[in] aHost A pointer to the SRP service host. 316 * 317 * @returns TRUE if the host has been deleted, FALSE if not. 318 * 319 */ 320 bool otSrpServerHostIsDeleted(const otSrpServerHost *aHost); 321 322 /** 323 * This function returns the full name of the host. 324 * 325 * @param[in] aHost A pointer to the SRP service host. 326 * 327 * @returns A pointer to the null-terminated host name string. 328 * 329 */ 330 const char *otSrpServerHostGetFullName(const otSrpServerHost *aHost); 331 332 /** 333 * This function returns the addresses of given host. 334 * 335 * @param[in] aHost A pointer to the SRP service host. 336 * @param[out] aAddressesNum A pointer to where we should output the number of the addresses to. 337 * 338 * @returns A pointer to the array of IPv6 Address. 339 * 340 */ 341 const otIp6Address *otSrpServerHostGetAddresses(const otSrpServerHost *aHost, uint8_t *aAddressesNum); 342 343 /** 344 * This function returns the next service (excluding any sub-type services) of given host. 345 * 346 * @note This function is being deprecated and will be removed. `otSrpServerHostFindNextService()` can be used 347 * instead. 348 * 349 * @param[in] aHost A pointer to the SRP service host. 350 * @param[in] aService A pointer to current SRP service instance; use NULL to get the first service. 351 * 352 * @returns A pointer to the next service or NULL if there is no more services. 353 * 354 */ 355 const otSrpServerService *otSrpServerHostGetNextService(const otSrpServerHost * aHost, 356 const otSrpServerService *aService); 357 358 /** 359 * This function finds the next matching service on the host. 360 * 361 * The combination of flags and service and instance names enables iterating over the full list of services and/or a 362 * subset of them matching certain conditions, or finding a specific service. 363 * 364 * To iterate over all services of a host: 365 * service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_ANY_SERVICE, NULL, NULL); 366 * 367 * To iterate over base services only (exclude sub-types): 368 * service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_BASE_TYPE_SERVICE_ONLY, NULL, NULL); 369 * 370 * To iterate over sub-types of a specific instance name `instanceName`: 371 * service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_SUB_TYPE_SERVICE_ONLY, NULL, 372 * insatnceName); 373 * 374 * To find a specific service with service name `serviceName` and service instance name `instanceName`: 375 * service = otSrpServerHostFindNextService(host, NULL, OT_SRP_SERVER_FLAGS_ANY_SERVICE, serviceName, instanceName); 376 * 377 * To find the base type service with a given service instance name `instanceName`: 378 * service = otSrpServerHostFindNextService(host, NULL, OT_SRP_SERVER_FLAGS_BASE_TYPE_SERVICE_ONLY, NULL, 379 * instanceName); 380 * 381 * @param[in] aHost A pointer to the SRP service host (MUST NOT be NULL). 382 * @param[in] aPrevService A pointer to the previous service or NULL to start from the beginning of the list. 383 * @param[in] aFlags Flags indicating which services to include (base/sub-type, active/deleted). 384 * @param[in] aServiceName The service name to match. Set to NULL to accept any name. 385 * @param[in] aInstanceName The service instance name to match. Set to NULL to accept any name. 386 * 387 * @returns A pointer to the next matching service or NULL if no matching service could be found. 388 * 389 */ 390 const otSrpServerService *otSrpServerHostFindNextService(const otSrpServerHost * aHost, 391 const otSrpServerService *aPrevService, 392 otSrpServerServiceFlags aFlags, 393 const char * aServiceName, 394 const char * aInstanceName); 395 396 /** 397 * This function indicates whether or not the SRP service has been deleted. 398 * 399 * A SRP service can be deleted but retains its name for future uses. 400 * In this case, the service instance is not removed from the SRP server/registry. 401 * It is guaranteed that all services are deleted if the host is deleted. 402 * 403 * @param[in] aService A pointer to the SRP service. 404 * 405 * @returns TRUE if the service has been deleted, FALSE if not. 406 * 407 */ 408 bool otSrpServerServiceIsDeleted(const otSrpServerService *aService); 409 410 /** 411 * This function indicates whether or not the SRP service is sub-type. 412 * 413 * @param[in] aService A pointer to the SRP service. 414 * 415 * @returns TRUE if the service is a sub-type, FALSE if not. 416 * 417 */ 418 bool otSrpServerServiceIsSubType(const otSrpServerService *aService); 419 420 /** 421 * This function returns the full service instance name of the service. 422 * 423 * @note This function is being deprecated and will be removed. `otSrpServerServiceGetInstanceName()` can be used 424 * instead. 425 * 426 * @param[in] aService A pointer to the SRP service. 427 * 428 * @returns A pointer to the null-terminated service instance name string. 429 * 430 */ 431 const char *otSrpServerServiceGetFullName(const otSrpServerService *aService); 432 433 /** 434 * This function returns the full service instance name of the service. 435 * 436 * @param[in] aService A pointer to the SRP service. 437 * 438 * @returns A pointer to the null-terminated service instance name string. 439 * 440 */ 441 const char *otSrpServerServiceGetInstanceName(const otSrpServerService *aService); 442 443 /** 444 * This function returns the full service name of the service. 445 * 446 * @param[in] aService A pointer to the SRP service. 447 * 448 * @returns A pointer to the null-terminated service name string. 449 * 450 */ 451 const char *otSrpServerServiceGetServiceName(const otSrpServerService *aService); 452 453 /** 454 * This function gets the sub-type label from service name. 455 * 456 * This function is intended to be used when the @p aService is a sub-type, i.e., `otSrpServerServiceIsSubType()` for 457 * the service returns TRUE. If it is not a sub-type this function returns `OT_ERROR_INVALID_ARGS`. 458 * 459 * The full service name for a sub-type service follows "<sub-label>._sub.<service-labels>.<domain>.". This function 460 * copies the `<sub-label>` into the @p aLabel buffer. 461 * 462 * The @p aLabel is ensured to always be null-terminated after returning even in case of failure. 463 * 464 * @param[in] aService A pointer to the SRP service. 465 * @param[out] aLabel A pointer to a buffer to copy the sub-type label name into. 466 * @param[in] aMaxSize Maximum size of @p aLabel buffer. 467 * 468 * @retval OT_ERROR_NONE @p aLabel was updated successfully. 469 * @retval OT_ERROR_NO_BUFS The sub-type label could not fit in @p aLabel buffer (number of chars from label 470 * that could fit are copied in @p aLabel ensuring it is null-terminated). 471 * @retval OT_ERROR_INVALID_ARGS SRP service is not a sub-type. 472 * 473 */ 474 otError otSrpServerServiceGetServiceSubTypeLabel(const otSrpServerService *aService, char *aLabel, uint8_t aMaxSize); 475 476 /** 477 * This function returns the port of the service instance. 478 * 479 * @param[in] aService A pointer to the SRP service. 480 * 481 * @returns The port of the service. 482 * 483 */ 484 uint16_t otSrpServerServiceGetPort(const otSrpServerService *aService); 485 486 /** 487 * This function returns the weight of the service instance. 488 * 489 * @param[in] aService A pointer to the SRP service. 490 * 491 * @returns The weight of the service. 492 * 493 */ 494 uint16_t otSrpServerServiceGetWeight(const otSrpServerService *aService); 495 496 /** 497 * This function returns the priority of the service instance. 498 * 499 * @param[in] aService A pointer to the SRP service. 500 * 501 * @returns The priority of the service. 502 * 503 */ 504 uint16_t otSrpServerServiceGetPriority(const otSrpServerService *aService); 505 506 /** 507 * This function returns the TXT record data of the service instance. 508 * 509 * @param[in] aService A pointer to the SRP service. 510 * @param[out] aDataLength A pointer to return the TXT record data length. MUST NOT be NULL. 511 * 512 * @returns A pointer to the buffer containing the TXT record data (the TXT data length is returned in @p aDataLength). 513 * 514 */ 515 const uint8_t *otSrpServerServiceGetTxtData(const otSrpServerService *aService, uint16_t *aDataLength); 516 517 /** 518 * This function returns the host which the service instance reside on. 519 * 520 * @param[in] aService A pointer to the SRP service. 521 * 522 * @returns A pointer to the host instance. 523 * 524 */ 525 const otSrpServerHost *otSrpServerServiceGetHost(const otSrpServerService *aService); 526 527 /** 528 * @} 529 * 530 */ 531 532 #ifdef __cplusplus 533 } // extern "C" 534 #endif 535 536 #endif // OPENTHREAD_SRP_SERVER_H_ 537