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