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