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 /** 58 * This struct represents a SRP client service pool entry. 59 * 60 */ 61 typedef struct otSrpClientBuffersServiceEntry 62 { 63 otSrpClientService mService; ///< The SRP client service structure. 64 otDnsTxtEntry mTxtEntry; ///< The SRP client TXT entry. 65 } otSrpClientBuffersServiceEntry; 66 67 /** 68 * This function gets the string buffer to use for SRP client host name. 69 * 70 * @param[in] aInstance A pointer to the OpenThread instance. 71 * @param[out] aSize Pointer to a variable to return the size (number of bytes) of the string buffer (MUST NOT be 72 * NULL). 73 * 74 * @returns A pointer to char buffer to use for SRP client host name. 75 * 76 */ 77 char *otSrpClientBuffersGetHostNameString(otInstance *aInstance, uint16_t *aSize); 78 79 /** 80 * This function gets the array of IPv6 address entries to use as SRP client host address list. 81 * 82 * @param[in] aInstance A pointer to the OpenThread instance. 83 * @param[out] aArrayLength Pointer to a variable to return the array length i.e., number of IPv6 address entries in 84 * the array (MUST NOT be NULL). 85 * 86 * @returns A pointer to an array of `otIp6Address` entries (number of entries is returned in @p aArrayLength). 87 * 88 */ 89 otIp6Address *otSrpClientBuffersGetHostAddressesArray(otInstance *aInstance, uint8_t *aArrayLength); 90 91 /** 92 * This function allocates a new service entry from the pool. 93 * 94 * The returned service entry instance will be initialized as follows: 95 * 96 * - `mService.mName` will point to an allocated string buffer which can be retrieved using the function 97 * `otSrpClientBuffersGetServiceEntryServiceNameString()`. 98 * - `mService.mInstanceName` will point to an allocated string buffer which can be retrieved using the function 99 * `otSrpClientBuffersGetServiceEntryInstanceNameString()`. 100 * - `mService.mSubTypeLabels` points to an array that is returned from `otSrpClientBuffersGetSubTypeLabelsArray()`. 101 * - `mService.mTxtEntries` will point to `mTxtEntry`. 102 * - `mService.mNumTxtEntries` will be set to one. 103 * - Other `mService` fields (port, priority, weight) are set to zero. 104 * - `mTxtEntry.mKey` is set to NULL (value is treated as already encoded). 105 * - `mTxtEntry.mValue` will point to an allocated buffer which can be retrieved using the function 106 * `otSrpClientBuffersGetServiceEntryTxtBuffer()`. 107 * - `mTxtEntry.mValueLength` is set to zero. 108 * - All related data/string buffers and arrays are cleared to all zero. 109 * 110 * @param[in] aInstance A pointer to the OpenThread instance. 111 * 112 * @returns A pointer to the newly allocated service entry or NULL if not more entry available in the pool. 113 * 114 */ 115 otSrpClientBuffersServiceEntry *otSrpClientBuffersAllocateService(otInstance *aInstance); 116 117 /** 118 * This function frees a previously allocated service entry. 119 * 120 * The @p aService MUST be previously allocated using `otSrpClientBuffersAllocateService()` and not yet freed. Otherwise 121 * the behavior of this function is undefined. 122 * 123 * @param[in] aInstance A pointer to the OpenThread instance. 124 * @param[in] aSevice A pointer to the service entry to free (MUST NOT be NULL). 125 * 126 */ 127 void otSrpClientBuffersFreeService(otInstance *aInstance, otSrpClientBuffersServiceEntry *aService); 128 129 /** 130 * This function frees all previously allocated service entries. 131 * 132 * @param[in] aInstance A pointer to the OpenThread instance. 133 * 134 */ 135 void otSrpClientBuffersFreeAllServices(otInstance *aInstance); 136 137 /** 138 * This function gets the string buffer for service name from a service entry. 139 * 140 * @param[in] aEntry A pointer to a previously allocated service entry (MUST NOT be NULL). 141 * @param[out] aSize A pointer to a variable to return the size (number of bytes) of the string buffer (MUST NOT be 142 * NULL). 143 * 144 * @returns A pointer to the string buffer. 145 * 146 */ 147 char *otSrpClientBuffersGetServiceEntryServiceNameString(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aSize); 148 149 /** 150 * This function gets the string buffer for service instance name from a service entry. 151 * 152 * @param[in] aEntry A pointer to a previously allocated service entry (MUST NOT be NULL). 153 * @param[out] aSize A pointer to a variable to return the size (number of bytes) of the string buffer (MUST NOT be 154 * NULL). 155 * 156 * @returns A pointer to the string buffer. 157 * 158 */ 159 char *otSrpClientBuffersGetServiceEntryInstanceNameString(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aSize); 160 161 /** 162 * This function gets the buffer for TXT record from a service entry. 163 * 164 * @param[in] aEntry A pointer to a previously allocated service entry (MUST NOT be NULL). 165 * @param[out] aSize A pointer to a variable to return the size (number of bytes) of the buffer (MUST NOT be NULL). 166 * 167 * @returns A pointer to the buffer. 168 * 169 */ 170 uint8_t *otSrpClientBuffersGetServiceEntryTxtBuffer(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aSize); 171 172 /** 173 * This function gets the array for service subtype labels from the service entry. 174 * 175 * @param[in] aEntry A pointer to a previously allocated service entry (MUST NOT be NULL). 176 * @param[out] aArrayLength A pointer to a variable to return the array length (MUST NOT be NULL). 177 * 178 * @returns A pointer to the array. 179 * 180 */ 181 const char **otSrpClientBuffersGetSubTypeLabelsArray(otSrpClientBuffersServiceEntry *aEntry, uint16_t *aArrayLength); 182 183 /** 184 * @} 185 * 186 */ 187 188 #ifdef __cplusplus 189 } // extern "C" 190 #endif 191 192 #endif // OPENTHREAD_SRP_CLIENT_BUFFERS_H_ 193
