1 /* 2 * Copyright (c) 2016, 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 top-level OpenThread APIs related to message buffer and queues. 33 */ 34 35 #ifndef OPENTHREAD_MESSAGE_H_ 36 #define OPENTHREAD_MESSAGE_H_ 37 38 #include <openthread/instance.h> 39 #include <openthread/platform/toolchain.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @addtogroup api-message 47 * 48 * @brief 49 * This module includes functions that manipulate OpenThread message buffers. 50 * 51 * @{ 52 * 53 */ 54 55 /** 56 * This type is an opaque representation of an OpenThread message buffer. 57 * 58 */ 59 typedef struct otMessage otMessage; 60 61 /** 62 * This enumeration defines the OpenThread message priority levels. 63 * 64 */ 65 typedef enum otMessagePriority 66 { 67 OT_MESSAGE_PRIORITY_LOW = 0, ///< Low priority level. 68 OT_MESSAGE_PRIORITY_NORMAL = 1, ///< Normal priority level. 69 OT_MESSAGE_PRIORITY_HIGH = 2, ///< High priority level. 70 } otMessagePriority; 71 72 /** 73 * This structure represents a message settings. 74 * 75 */ 76 typedef struct otMessageSettings 77 { 78 bool mLinkSecurityEnabled; ///< TRUE if the message should be secured at Layer 2. 79 uint8_t mPriority; ///< Priority level (MUST be a `OT_MESSAGE_PRIORITY_*` from `otMessagePriority`). 80 } otMessageSettings; 81 82 /** 83 * Free an allocated message buffer. 84 * 85 * @param[in] aMessage A pointer to a message buffer. 86 * 87 * @sa otMessageAppend 88 * @sa otMessageGetLength 89 * @sa otMessageSetLength 90 * @sa otMessageGetOffset 91 * @sa otMessageSetOffset 92 * @sa otMessageRead 93 * @sa otMessageWrite 94 * 95 */ 96 void otMessageFree(otMessage *aMessage); 97 98 /** 99 * Get the message length in bytes. 100 * 101 * @param[in] aMessage A pointer to a message buffer. 102 * 103 * @returns The message length in bytes. 104 * 105 * @sa otMessageFree 106 * @sa otMessageAppend 107 * @sa otMessageSetLength 108 * @sa otMessageGetOffset 109 * @sa otMessageSetOffset 110 * @sa otMessageRead 111 * @sa otMessageWrite 112 * @sa otMessageSetLength 113 * 114 */ 115 uint16_t otMessageGetLength(const otMessage *aMessage); 116 117 /** 118 * Set the message length in bytes. 119 * 120 * @param[in] aMessage A pointer to a message buffer. 121 * @param[in] aLength A length in bytes. 122 * 123 * @retval OT_ERROR_NONE Successfully set the message length. 124 * @retval OT_ERROR_NO_BUFS No available buffers to grow the message. 125 * 126 * @sa otMessageFree 127 * @sa otMessageAppend 128 * @sa otMessageGetLength 129 * @sa otMessageGetOffset 130 * @sa otMessageSetOffset 131 * @sa otMessageRead 132 * @sa otMessageWrite 133 * 134 */ 135 otError otMessageSetLength(otMessage *aMessage, uint16_t aLength); 136 137 /** 138 * Get the message offset in bytes. 139 * 140 * @param[in] aMessage A pointer to a message buffer. 141 * 142 * @returns The message offset value. 143 * 144 * @sa otMessageFree 145 * @sa otMessageAppend 146 * @sa otMessageGetLength 147 * @sa otMessageSetLength 148 * @sa otMessageSetOffset 149 * @sa otMessageRead 150 * @sa otMessageWrite 151 * 152 */ 153 uint16_t otMessageGetOffset(const otMessage *aMessage); 154 155 /** 156 * Set the message offset in bytes. 157 * 158 * @param[in] aMessage A pointer to a message buffer. 159 * @param[in] aOffset An offset in bytes. 160 * 161 * @sa otMessageFree 162 * @sa otMessageAppend 163 * @sa otMessageGetLength 164 * @sa otMessageSetLength 165 * @sa otMessageGetOffset 166 * @sa otMessageRead 167 * @sa otMessageWrite 168 * 169 */ 170 void otMessageSetOffset(otMessage *aMessage, uint16_t aOffset); 171 172 /** 173 * This function indicates whether or not link security is enabled for the message. 174 * 175 * @param[in] aMessage A pointer to a message buffer. 176 * 177 * @retval TRUE If link security is enabled. 178 * @retval FALSE If link security is not enabled. 179 * 180 */ 181 bool otMessageIsLinkSecurityEnabled(const otMessage *aMessage); 182 183 /** 184 * This function sets/forces the message to be forwarded using direct transmission. 185 * Default setting for a new message is `false`. 186 * 187 * @param[in] aMessage A pointer to a message buffer. 188 * @param[in] aEnabled If `true`, the message is forced to use direct transmission. If `false`, the message follows 189 * the normal procedure. 190 * 191 */ 192 void otMessageSetDirectTransmission(otMessage *aMessage, bool aEnabled); 193 194 /** 195 * This function returns the average RSS (received signal strength) associated with the message. 196 * 197 * @returns The average RSS value (in dBm) or OT_RADIO_RSSI_INVALID if no average RSS is available. 198 * 199 */ 200 int8_t otMessageGetRss(const otMessage *aMessage); 201 202 /** 203 * Append bytes to a message. 204 * 205 * @param[in] aMessage A pointer to a message buffer. 206 * @param[in] aBuf A pointer to the data to append. 207 * @param[in] aLength Number of bytes to append. 208 * 209 * @retval OT_ERROR_NONE Successfully appended to the message 210 * @retval OT_ERROR_NO_BUFS No available buffers to grow the message. 211 * 212 * @sa otMessageFree 213 * @sa otMessageGetLength 214 * @sa otMessageSetLength 215 * @sa otMessageGetOffset 216 * @sa otMessageSetOffset 217 * @sa otMessageRead 218 * @sa otMessageWrite 219 * 220 */ 221 otError otMessageAppend(otMessage *aMessage, const void *aBuf, uint16_t aLength); 222 223 /** 224 * Read bytes from a message. 225 * 226 * @param[in] aMessage A pointer to a message buffer. 227 * @param[in] aOffset An offset in bytes. 228 * @param[in] aBuf A pointer to a buffer that message bytes are read to. 229 * @param[in] aLength Number of bytes to read. 230 * 231 * @returns The number of bytes read. 232 * 233 * @sa otMessageFree 234 * @sa otMessageAppend 235 * @sa otMessageGetLength 236 * @sa otMessageSetLength 237 * @sa otMessageGetOffset 238 * @sa otMessageSetOffset 239 * @sa otMessageWrite 240 * 241 */ 242 uint16_t otMessageRead(const otMessage *aMessage, uint16_t aOffset, void *aBuf, uint16_t aLength); 243 244 /** 245 * Write bytes to a message. 246 * 247 * @param[in] aMessage A pointer to a message buffer. 248 * @param[in] aOffset An offset in bytes. 249 * @param[in] aBuf A pointer to a buffer that message bytes are written from. 250 * @param[in] aLength Number of bytes to write. 251 * 252 * @returns The number of bytes written. 253 * 254 * @sa otMessageFree 255 * @sa otMessageAppend 256 * @sa otMessageGetLength 257 * @sa otMessageSetLength 258 * @sa otMessageGetOffset 259 * @sa otMessageSetOffset 260 * @sa otMessageRead 261 * 262 */ 263 int otMessageWrite(otMessage *aMessage, uint16_t aOffset, const void *aBuf, uint16_t aLength); 264 265 /** 266 * This structure represents an OpenThread message queue. 267 */ 268 typedef struct 269 { 270 void *mData; ///< Opaque data used by the implementation. 271 } otMessageQueue; 272 273 /** 274 * This structure represents information about a message queue. 275 * 276 */ 277 typedef struct otMessageQueueInfo 278 { 279 uint16_t mNumMessages; ///< Number of messages in the queue. 280 uint16_t mNumBuffers; ///< Number of data buffers used by messages in the queue. 281 uint32_t mTotalBytes; ///< Total number of bytes used by all messages in the queue. 282 } otMessageQueueInfo; 283 284 /** 285 * This structure represents the message buffer information for different queues used by OpenThread stack. 286 * 287 */ 288 typedef struct otBufferInfo 289 { 290 uint16_t mTotalBuffers; ///< The total number of buffers in the messages pool (0xffff if unknown). 291 uint16_t mFreeBuffers; ///< The number of free buffers (0xffff if unknown). 292 293 /** 294 * The maximum number of used buffers at the same time since OT stack initialization or last call to 295 * `otMessageResetBufferInfo()`. 296 * 297 */ 298 uint16_t mMaxUsedBuffers; 299 300 otMessageQueueInfo m6loSendQueue; ///< Info about 6LoWPAN send queue. 301 otMessageQueueInfo m6loReassemblyQueue; ///< Info about 6LoWPAN reassembly queue. 302 otMessageQueueInfo mIp6Queue; ///< Info about IPv6 send queue. 303 otMessageQueueInfo mMplQueue; ///< Info about MPL send queue. 304 otMessageQueueInfo mMleQueue; ///< Info about MLE delayed message queue. 305 otMessageQueueInfo mCoapQueue; ///< Info about CoAP/TMF send queue. 306 otMessageQueueInfo mCoapSecureQueue; ///< Info about CoAP secure send queue. 307 otMessageQueueInfo mApplicationCoapQueue; ///< Info about application CoAP send queue. 308 } otBufferInfo; 309 310 /** 311 * Initialize the message queue. 312 * 313 * This function MUST be called once and only once for a `otMessageQueue` instance before any other `otMessageQueue` 314 * functions. The behavior is undefined if other queue APIs are used with an `otMessageQueue` before it being 315 * initialized or if it is initialized more than once. 316 * 317 * @param[in] aQueue A pointer to a message queue. 318 * 319 */ 320 void otMessageQueueInit(otMessageQueue *aQueue); 321 322 /** 323 * This function adds a message to the end of the given message queue. 324 * 325 * @param[in] aQueue A pointer to the message queue. 326 * @param[in] aMessage The message to add. 327 * 328 */ 329 void otMessageQueueEnqueue(otMessageQueue *aQueue, otMessage *aMessage); 330 331 /** 332 * This function adds a message at the head/front of the given message queue. 333 * 334 * @param[in] aQueue A pointer to the message queue. 335 * @param[in] aMessage The message to add. 336 * 337 */ 338 void otMessageQueueEnqueueAtHead(otMessageQueue *aQueue, otMessage *aMessage); 339 340 /** 341 * This function removes a message from the given message queue. 342 * 343 * @param[in] aQueue A pointer to the message queue. 344 * @param[in] aMessage The message to remove. 345 * 346 */ 347 void otMessageQueueDequeue(otMessageQueue *aQueue, otMessage *aMessage); 348 349 /** 350 * This function returns a pointer to the message at the head of the queue. 351 * 352 * @param[in] aQueue A pointer to a message queue. 353 * 354 * @returns A pointer to the message at the head of queue or NULL if queue is empty. 355 * 356 */ 357 otMessage *otMessageQueueGetHead(otMessageQueue *aQueue); 358 359 /** 360 * This function returns a pointer to the next message in the queue by iterating forward (from head to tail). 361 * 362 * @param[in] aQueue A pointer to a message queue. 363 * @param[in] aMessage A pointer to current message buffer. 364 * 365 * @returns A pointer to the next message in the queue after `aMessage` or NULL if `aMessage is the tail of queue. 366 * NULL is returned if `aMessage` is not in the queue `aQueue`. 367 * 368 */ 369 otMessage *otMessageQueueGetNext(otMessageQueue *aQueue, const otMessage *aMessage); 370 371 /** 372 * Get the Message Buffer information. 373 * 374 * @param[in] aInstance A pointer to the OpenThread instance. 375 * @param[out] aBufferInfo A pointer where the message buffer information is written. 376 * 377 */ 378 void otMessageGetBufferInfo(otInstance *aInstance, otBufferInfo *aBufferInfo); 379 380 /** 381 * Reset the Message Buffer information counter tracking the maximum number buffers in use at the same time. 382 * 383 * This resets `mMaxUsedBuffers` in `otBufferInfo`. 384 * 385 * @param[in] aInstance A pointer to the OpenThread instance. 386 * 387 */ 388 void otMessageResetBufferInfo(otInstance *aInstance); 389 390 /** 391 * @} 392 * 393 */ 394 395 #ifdef __cplusplus 396 } // extern "C" 397 #endif 398 399 #endif // OPENTHREAD_MESSAGE_H_ 400
