1 /* 2 * Copyright (c) 2021, 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 OpenThread SRP (Service Registration Protocol) client buffers and service pool. 33 */ 34 35 #ifndef OPENTHREAD_SRP_CLIENT_BUFFERS_H_ 36 #define OPENTHREAD_SRP_CLIENT_BUFFERS_H_ 37 38 #include <openthread/dns.h> 39 #include <openthread/srp_client.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @addtogroup api-srp 47 * 48 * @brief 49 * This module includes functions for SRP client buffers and service pool. 50 * 51 * @{ 52 * 53 * Functions in this module are only available when feature OPENTHREAD_CONFIG_SRP_CLIENT_BUFFERS_ENABLE is enabled. 54 */ 55 56 /** 57 * Represents a SRP client service pool entry. 58 */ 59 typedef struct otSrpClientBuffersServiceEntry 60 { 61 otSrpClientService mService; ///< The SRP client service structure. 62 otDnsTxtEntry mTxtEntry; ///< The SRP client TXT entry. 63 } otSrpClientBuffersServiceEntry; 64 65 /** 66 * Gets the string buffer to use for SRP client host name. 67 * 68 * @param[in] aInstance A pointer to the OpenThread instance. 69 * @param[out] aSize Pointer to a variable to return the size (number of bytes) of the string buffer (MUST NOT be 70 * NULL). 71 * 72 * @returns A pointer to char buffer to use for SRP client host name. 73 */ 74 char *otSrpClientBuffersGetHostNameString(otInstance *aInstance, uint16_t *aSize); 75 76 /** 77 * Gets the array of IPv6 address entries to use as SRP client host address list. 78 * 79 * @param[in] aInstance A pointer to the OpenThread instance. 80 * @param[out] aArrayLength Pointer to a variable to return the array length i.e., number of IPv6 address entries in 81 * the array (MUST NOT be NULL). 82 * 83 * @returns A pointer to an array of `otIp6Address` entries (number of entries is returned in @p aArrayLength). 84 */ 85 otIp6Address *otSrpClientBuffersGetHostAddressesArray(otInstance *aInstance, uint8_t *aArrayLength); 86 87 /** 88 * Allocates a new service entry from the pool. 89 * 90 * The returned service entry instance will be initialized as follows: 91 * 92 * - `mService.mName` will point to an allocated string buffer which can be retrieved using the function 93 * `otSrpClientBuffersGetServiceEntryServiceNameString()`. 94 * - `mService.mInstanceName` will point to an allocated string buffer which can be retrieved using the function 95 * `otSrpClientBuffersGetServiceEntryInstanceNameString()`. 96 * - `mService.mSubTypeLabels` points to an array that is returned from `otSrpClientBuffersGetSubTypeLabelsArray()`. 97 * - `mService.mTxtEntries` will point to `mTxtEntry`. 98 * - `mService.mNumTxtEntries` will be set to one. 99 * - Other `mService` fields (port, priority, weight) are set to zero. 100 * - `mTxtEntry.mKey` is set to NULL (value is treated as already encoded). 101 * - `mTxtEntry.mValue` will point to an allocated buffer which can be retrieved using the function 102 * `otSrpClientBuffersGetServiceEntryTxtBuffer()`. 103 * - `mTxtEntry.mValueLength` is set to zero. 104 * - All related data/string buffers and arrays are cleared to all zero. 105 * 106 * @param[in] aInstance A pointer to the OpenThread instance. 107 * 108 * @returns A pointer to the newly allocated service entry or NULL if not more entry available in the pool. 109 */ 110 otSrpClientBuffersServiceEntry *otSrpClientBuffersAllocateService(otInstance *aInstance); 111 112 /** 113 * Frees a previously allocated service entry. 114 * 115 * The @p aService MUST be previously allocated using `otSrpClientBuffersAllocateService()` and not yet freed. Otherwise 116 * the behavior of this function is undefined. 117 * 118 * @param[in] aInstance A pointer to the OpenThread instance. 119 * @param[in] aService A pointer to the service entry to free (MUST NOT be NULL). 120 */ 121 void otSrpClientBuffersFreeService(otInstance *aInstance, otSrpClientBuffersServiceEntry *aService); 122 123 /** 124 * Frees all previously allocated service entries. 125 * 126 * @param[in] aInstance A pointer to the OpenThread instance. 127 */ 128 void otSrpClientBuffersFreeAllServices(otInstance *aInstance); 129 130 /** 131 * Gets the string buffer for service name from a service entry. 132 * 133 * @param[in] aEntry A pointer to a previously allocated service entry (MUST NOT be NULL). 134 * @param[out] aSize A pointer to a variable to return the size (number of bytes) of the string buffer (MUST NOT be 135 * NULL). 136 * 137 * @returns A pointer to the string buffer. 138 */ 139 char *otSrpClientBuffersGetServiceEntryServiceNameString(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aSize); 140 141 /** 142 * Gets the string buffer for service instance name from a service entry. 143 * 144 * @param[in] aEntry A pointer to a previously allocated service entry (MUST NOT be NULL). 145 * @param[out] aSize A pointer to a variable to return the size (number of bytes) of the string buffer (MUST NOT be 146 * NULL). 147 * 148 * @returns A pointer to the string buffer. 149 */ 150 char *otSrpClientBuffersGetServiceEntryInstanceNameString(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aSize); 151 152 /** 153 * Gets the buffer for TXT record from a service entry. 154 * 155 * @param[in] aEntry A pointer to a previously allocated service entry (MUST NOT be NULL). 156 * @param[out] aSize A pointer to a variable to return the size (number of bytes) of the buffer (MUST NOT be NULL). 157 * 158 * @returns A pointer to the buffer. 159 */ 160 uint8_t *otSrpClientBuffersGetServiceEntryTxtBuffer(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aSize); 161 162 /** 163 * Gets the array for service subtype labels from the service entry. 164 * 165 * @param[in] aEntry A pointer to a previously allocated service entry (MUST NOT be NULL). 166 * @param[out] aArrayLength A pointer to a variable to return the array length (MUST NOT be NULL). 167 * 168 * @returns A pointer to the array. 169 */ 170 const char **otSrpClientBuffersGetSubTypeLabelsArray(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aArrayLength); 171 172 /** 173 * @} 174 */ 175 176 #ifdef __cplusplus 177 } // extern "C" 178 #endif 179 180 #endif // OPENTHREAD_SRP_CLIENT_BUFFERS_H_ 181