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 * An opaque representation of an OpenThread message buffer. 57 * 58 */ 59 typedef struct otMessage otMessage; 60 61 /** 62 * 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 * Defines the OpenThread message origins. 74 * 75 */ 76 typedef enum otMessageOrigin 77 { 78 OT_MESSAGE_ORIGIN_THREAD_NETIF = 0, ///< Message from Thread Netif. 79 OT_MESSAGE_ORIGIN_HOST_TRUSTED = 1, ///< Message from a trusted source on host. 80 OT_MESSAGE_ORIGIN_HOST_UNTRUSTED = 2, ///< Message from an untrusted source on host. 81 } otMessageOrigin; 82 83 /** 84 * Represents a message settings. 85 * 86 */ 87 typedef struct otMessageSettings 88 { 89 bool mLinkSecurityEnabled; ///< TRUE if the message should be secured at Layer 2. 90 uint8_t mPriority; ///< Priority level (MUST be a `OT_MESSAGE_PRIORITY_*` from `otMessagePriority`). 91 } otMessageSettings; 92 93 /** 94 * Free an allocated message buffer. 95 * 96 * @param[in] aMessage A pointer to a message buffer. 97 * 98 * @sa otMessageAppend 99 * @sa otMessageGetLength 100 * @sa otMessageSetLength 101 * @sa otMessageGetOffset 102 * @sa otMessageSetOffset 103 * @sa otMessageRead 104 * @sa otMessageWrite 105 * 106 */ 107 void otMessageFree(otMessage *aMessage); 108 109 /** 110 * Get the message length in bytes. 111 * 112 * @param[in] aMessage A pointer to a message buffer. 113 * 114 * @returns The message length in bytes. 115 * 116 * @sa otMessageFree 117 * @sa otMessageAppend 118 * @sa otMessageSetLength 119 * @sa otMessageGetOffset 120 * @sa otMessageSetOffset 121 * @sa otMessageRead 122 * @sa otMessageWrite 123 * @sa otMessageSetLength 124 * 125 */ 126 uint16_t otMessageGetLength(const otMessage *aMessage); 127 128 /** 129 * Set the message length in bytes. 130 * 131 * @param[in] aMessage A pointer to a message buffer. 132 * @param[in] aLength A length in bytes. 133 * 134 * @retval OT_ERROR_NONE Successfully set the message length. 135 * @retval OT_ERROR_NO_BUFS No available buffers to grow the message. 136 * 137 * @sa otMessageFree 138 * @sa otMessageAppend 139 * @sa otMessageGetLength 140 * @sa otMessageGetOffset 141 * @sa otMessageSetOffset 142 * @sa otMessageRead 143 * @sa otMessageWrite 144 * 145 */ 146 otError otMessageSetLength(otMessage *aMessage, uint16_t aLength); 147 148 /** 149 * Get the message offset in bytes. 150 * 151 * @param[in] aMessage A pointer to a message buffer. 152 * 153 * @returns The message offset value. 154 * 155 * @sa otMessageFree 156 * @sa otMessageAppend 157 * @sa otMessageGetLength 158 * @sa otMessageSetLength 159 * @sa otMessageSetOffset 160 * @sa otMessageRead 161 * @sa otMessageWrite 162 * 163 */ 164 uint16_t otMessageGetOffset(const otMessage *aMessage); 165 166 /** 167 * Set the message offset in bytes. 168 * 169 * @param[in] aMessage A pointer to a message buffer. 170 * @param[in] aOffset An offset in bytes. 171 * 172 * @sa otMessageFree 173 * @sa otMessageAppend 174 * @sa otMessageGetLength 175 * @sa otMessageSetLength 176 * @sa otMessageGetOffset 177 * @sa otMessageRead 178 * @sa otMessageWrite 179 * 180 */ 181 void otMessageSetOffset(otMessage *aMessage, uint16_t aOffset); 182 183 /** 184 * Indicates whether or not link security is enabled for the message. 185 * 186 * @param[in] aMessage A pointer to a message buffer. 187 * 188 * @retval TRUE If link security is enabled. 189 * @retval FALSE If link security is not enabled. 190 * 191 */ 192 bool otMessageIsLinkSecurityEnabled(const otMessage *aMessage); 193 194 /** 195 * Indicates whether or not the message is allowed to be looped back to host. 196 * 197 * @param[in] aMessage A pointer to a message buffer. 198 * 199 * @retval TRUE If the message is allowed to be looped back to host. 200 * @retval FALSE If the message is not allowed to be looped back to host. 201 * 202 */ 203 bool otMessageIsLoopbackToHostAllowed(const otMessage *aMessage); 204 205 /** 206 * Sets whether or not the message is allowed to be looped back to host. 207 * 208 * @param[in] aMessage A pointer to a message buffer. 209 * @param[in] aAllowLoopbackToHost Whether to allow the message to be looped back to host. 210 * 211 */ 212 void otMessageSetLoopbackToHostAllowed(otMessage *aMessage, bool aAllowLoopbackToHost); 213 214 /** 215 * Indicates whether the given message may be looped back in a case of a multicast destination address. 216 * 217 * If @p aMessage is used along with an `otMessageInfo`, the `mMulticastLoop` field from `otMessageInfo` structure 218 * takes precedence and will be used instead of the the value set on @p aMessage. 219 * 220 * This API is mainly intended for use along with `otIp6Send()` which expects an already prepared IPv6 message. 221 * 222 * @param[in] aMessage A pointer to the message. 223 * 224 */ 225 bool otMessageIsMulticastLoopEnabled(otMessage *aMessage); 226 227 /** 228 * Controls whether the given message may be looped back in a case of a multicast destination address. 229 * 230 * @param[in] aMessage A pointer to the message. 231 * @param[in] aEnabled The configuration value. 232 * 233 */ 234 void otMessageSetMulticastLoopEnabled(otMessage *aMessage, bool aEnabled); 235 236 /** 237 * Gets the message origin. 238 * 239 * @param[in] aMessage A pointer to a message buffer. 240 * 241 * @returns The message origin. 242 * 243 */ 244 otMessageOrigin otMessageGetOrigin(const otMessage *aMessage); 245 246 /** 247 * Sets the message origin. 248 * 249 * @param[in] aMessage A pointer to a message buffer. 250 * @param[in] aOrigin The message origin. 251 * 252 */ 253 void otMessageSetOrigin(otMessage *aMessage, otMessageOrigin aOrigin); 254 255 /** 256 * Sets/forces the message to be forwarded using direct transmission. 257 * Default setting for a new message is `false`. 258 * 259 * @param[in] aMessage A pointer to a message buffer. 260 * @param[in] aEnabled If `true`, the message is forced to use direct transmission. If `false`, the message follows 261 * the normal procedure. 262 * 263 */ 264 void otMessageSetDirectTransmission(otMessage *aMessage, bool aEnabled); 265 266 /** 267 * Returns the average RSS (received signal strength) associated with the message. 268 * 269 * @returns The average RSS value (in dBm) or OT_RADIO_RSSI_INVALID if no average RSS is available. 270 * 271 */ 272 int8_t otMessageGetRss(const otMessage *aMessage); 273 274 /** 275 * Append bytes to a message. 276 * 277 * @param[in] aMessage A pointer to a message buffer. 278 * @param[in] aBuf A pointer to the data to append. 279 * @param[in] aLength Number of bytes to append. 280 * 281 * @retval OT_ERROR_NONE Successfully appended to the message 282 * @retval OT_ERROR_NO_BUFS No available buffers to grow the message. 283 * 284 * @sa otMessageFree 285 * @sa otMessageGetLength 286 * @sa otMessageSetLength 287 * @sa otMessageGetOffset 288 * @sa otMessageSetOffset 289 * @sa otMessageRead 290 * @sa otMessageWrite 291 * 292 */ 293 otError otMessageAppend(otMessage *aMessage, const void *aBuf, uint16_t aLength); 294 295 /** 296 * Read bytes from a message. 297 * 298 * @param[in] aMessage A pointer to a message buffer. 299 * @param[in] aOffset An offset in bytes. 300 * @param[in] aBuf A pointer to a buffer that message bytes are read to. 301 * @param[in] aLength Number of bytes to read. 302 * 303 * @returns The number of bytes read. 304 * 305 * @sa otMessageFree 306 * @sa otMessageAppend 307 * @sa otMessageGetLength 308 * @sa otMessageSetLength 309 * @sa otMessageGetOffset 310 * @sa otMessageSetOffset 311 * @sa otMessageWrite 312 * 313 */ 314 uint16_t otMessageRead(const otMessage *aMessage, uint16_t aOffset, void *aBuf, uint16_t aLength); 315 316 /** 317 * Write bytes to a message. 318 * 319 * @param[in] aMessage A pointer to a message buffer. 320 * @param[in] aOffset An offset in bytes. 321 * @param[in] aBuf A pointer to a buffer that message bytes are written from. 322 * @param[in] aLength Number of bytes to write. 323 * 324 * @returns The number of bytes written. 325 * 326 * @sa otMessageFree 327 * @sa otMessageAppend 328 * @sa otMessageGetLength 329 * @sa otMessageSetLength 330 * @sa otMessageGetOffset 331 * @sa otMessageSetOffset 332 * @sa otMessageRead 333 * 334 */ 335 int otMessageWrite(otMessage *aMessage, uint16_t aOffset, const void *aBuf, uint16_t aLength); 336 337 /** 338 * Represents an OpenThread message queue. 339 */ 340 typedef struct 341 { 342 void *mData; ///< Opaque data used by the implementation. 343 } otMessageQueue; 344 345 /** 346 * Represents information about a message queue. 347 * 348 */ 349 typedef struct otMessageQueueInfo 350 { 351 uint16_t mNumMessages; ///< Number of messages in the queue. 352 uint16_t mNumBuffers; ///< Number of data buffers used by messages in the queue. 353 uint32_t mTotalBytes; ///< Total number of bytes used by all messages in the queue. 354 } otMessageQueueInfo; 355 356 /** 357 * Represents the message buffer information for different queues used by OpenThread stack. 358 * 359 */ 360 typedef struct otBufferInfo 361 { 362 uint16_t mTotalBuffers; ///< The total number of buffers in the messages pool (0xffff if unknown). 363 uint16_t mFreeBuffers; ///< The number of free buffers (0xffff if unknown). 364 365 /** 366 * The maximum number of used buffers at the same time since OT stack initialization or last call to 367 * `otMessageResetBufferInfo()`. 368 * 369 */ 370 uint16_t mMaxUsedBuffers; 371 372 otMessageQueueInfo m6loSendQueue; ///< Info about 6LoWPAN send queue. 373 otMessageQueueInfo m6loReassemblyQueue; ///< Info about 6LoWPAN reassembly queue. 374 otMessageQueueInfo mIp6Queue; ///< Info about IPv6 send queue. 375 otMessageQueueInfo mMplQueue; ///< Info about MPL send queue. 376 otMessageQueueInfo mMleQueue; ///< Info about MLE delayed message queue. 377 otMessageQueueInfo mCoapQueue; ///< Info about CoAP/TMF send queue. 378 otMessageQueueInfo mCoapSecureQueue; ///< Info about CoAP secure send queue. 379 otMessageQueueInfo mApplicationCoapQueue; ///< Info about application CoAP send queue. 380 } otBufferInfo; 381 382 /** 383 * Initialize the message queue. 384 * 385 * MUST be called once and only once for a `otMessageQueue` instance before any other `otMessageQueue` 386 * functions. The behavior is undefined if other queue APIs are used with an `otMessageQueue` before it being 387 * initialized or if it is initialized more than once. 388 * 389 * @param[in] aQueue A pointer to a message queue. 390 * 391 */ 392 void otMessageQueueInit(otMessageQueue *aQueue); 393 394 /** 395 * Adds a message to the end of the given message queue. 396 * 397 * @param[in] aQueue A pointer to the message queue. 398 * @param[in] aMessage The message to add. 399 * 400 */ 401 void otMessageQueueEnqueue(otMessageQueue *aQueue, otMessage *aMessage); 402 403 /** 404 * Adds a message at the head/front of the given message queue. 405 * 406 * @param[in] aQueue A pointer to the message queue. 407 * @param[in] aMessage The message to add. 408 * 409 */ 410 void otMessageQueueEnqueueAtHead(otMessageQueue *aQueue, otMessage *aMessage); 411 412 /** 413 * Removes a message from the given message queue. 414 * 415 * @param[in] aQueue A pointer to the message queue. 416 * @param[in] aMessage The message to remove. 417 * 418 */ 419 void otMessageQueueDequeue(otMessageQueue *aQueue, otMessage *aMessage); 420 421 /** 422 * Returns a pointer to the message at the head of the queue. 423 * 424 * @param[in] aQueue A pointer to a message queue. 425 * 426 * @returns A pointer to the message at the head of queue or NULL if queue is empty. 427 * 428 */ 429 otMessage *otMessageQueueGetHead(otMessageQueue *aQueue); 430 431 /** 432 * Returns a pointer to the next message in the queue by iterating forward (from head to tail). 433 * 434 * @param[in] aQueue A pointer to a message queue. 435 * @param[in] aMessage A pointer to current message buffer. 436 * 437 * @returns A pointer to the next message in the queue after `aMessage` or NULL if `aMessage is the tail of queue. 438 * NULL is returned if `aMessage` is not in the queue `aQueue`. 439 * 440 */ 441 otMessage *otMessageQueueGetNext(otMessageQueue *aQueue, const otMessage *aMessage); 442 443 /** 444 * Get the Message Buffer information. 445 * 446 * @param[in] aInstance A pointer to the OpenThread instance. 447 * @param[out] aBufferInfo A pointer where the message buffer information is written. 448 * 449 */ 450 void otMessageGetBufferInfo(otInstance *aInstance, otBufferInfo *aBufferInfo); 451 452 /** 453 * Reset the Message Buffer information counter tracking the maximum number buffers in use at the same time. 454 * 455 * This resets `mMaxUsedBuffers` in `otBufferInfo`. 456 * 457 * @param[in] aInstance A pointer to the OpenThread instance. 458 * 459 */ 460 void otMessageResetBufferInfo(otInstance *aInstance); 461 462 /** 463 * @} 464 * 465 */ 466 467 #ifdef __cplusplus 468 } // extern "C" 469 #endif 470 471 #endif // OPENTHREAD_MESSAGE_H_ 472
