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 otMessageQueueInfo m6loSendQueue; ///< Info about 6LoWPAN send queue. 293 otMessageQueueInfo m6loReassemblyQueue; ///< Info about 6LoWPAN reassembly queue. 294 otMessageQueueInfo mIp6Queue; ///< Info about IPv6 send queue. 295 otMessageQueueInfo mMplQueue; ///< Info about MPL send queue. 296 otMessageQueueInfo mMleQueue; ///< Info about MLE delayed message queue. 297 otMessageQueueInfo mCoapQueue; ///< Info about CoAP/TMF send queue. 298 otMessageQueueInfo mCoapSecureQueue; ///< Info about CoAP secure send queue. 299 otMessageQueueInfo mApplicationCoapQueue; ///< Info about application CoAP send queue. 300 } otBufferInfo; 301 302 /** 303 * Initialize the message queue. 304 * 305 * This function MUST be called once and only once for a `otMessageQueue` instance before any other `otMessageQueue` 306 * functions. The behavior is undefined if other queue APIs are used with an `otMessageQueue` before it being 307 * initialized or if it is initialized more than once. 308 * 309 * @param[in] aQueue A pointer to a message queue. 310 * 311 */ 312 void otMessageQueueInit(otMessageQueue *aQueue); 313 314 /** 315 * This function adds a message to the end of the given message queue. 316 * 317 * @param[in] aQueue A pointer to the message queue. 318 * @param[in] aMessage The message to add. 319 * 320 */ 321 void otMessageQueueEnqueue(otMessageQueue *aQueue, otMessage *aMessage); 322 323 /** 324 * This function adds a message at the head/front of the given message queue. 325 * 326 * @param[in] aQueue A pointer to the message queue. 327 * @param[in] aMessage The message to add. 328 * 329 */ 330 void otMessageQueueEnqueueAtHead(otMessageQueue *aQueue, otMessage *aMessage); 331 332 /** 333 * This function removes a message from the given message queue. 334 * 335 * @param[in] aQueue A pointer to the message queue. 336 * @param[in] aMessage The message to remove. 337 * 338 */ 339 void otMessageQueueDequeue(otMessageQueue *aQueue, otMessage *aMessage); 340 341 /** 342 * This function returns a pointer to the message at the head of the queue. 343 * 344 * @param[in] aQueue A pointer to a message queue. 345 * 346 * @returns A pointer to the message at the head of queue or NULL if queue is empty. 347 * 348 */ 349 otMessage *otMessageQueueGetHead(otMessageQueue *aQueue); 350 351 /** 352 * This function returns a pointer to the next message in the queue by iterating forward (from head to tail). 353 * 354 * @param[in] aQueue A pointer to a message queue. 355 * @param[in] aMessage A pointer to current message buffer. 356 * 357 * @returns A pointer to the next message in the queue after `aMessage` or NULL if `aMessage is the tail of queue. 358 * NULL is returned if `aMessage` is not in the queue `aQueue`. 359 * 360 */ 361 otMessage *otMessageQueueGetNext(otMessageQueue *aQueue, const otMessage *aMessage); 362 363 /** 364 * Get the Message Buffer information. 365 * 366 * @param[in] aInstance A pointer to the OpenThread instance. 367 * @param[out] aBufferInfo A pointer where the message buffer information is written. 368 * 369 */ 370 void otMessageGetBufferInfo(otInstance *aInstance, otBufferInfo *aBufferInfo); 371 372 /** 373 * @} 374 * 375 */ 376 377 #ifdef __cplusplus 378 } // extern "C" 379 #endif 380 381 #endif // OPENTHREAD_MESSAGE_H_ 382