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