1 /* Copyright (c) 2011, The Linux Foundation. All rights reserved. 2 * 3 * Redistribution and use in source and binary forms, with or without 4 * modification, are permitted provided that the following conditions are 5 * met: 6 * * Redistributions of source code must retain the above copyright 7 * notice, this list of conditions and the following disclaimer. 8 * * Redistributions in binary form must reproduce the above 9 * copyright notice, this list of conditions and the following 10 * disclaimer in the documentation and/or other materials provided 11 * with the distribution. 12 * * Neither the name of The Linux Foundation nor the names of its 13 * contributors may be used to endorse or promote products derived 14 * from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED 17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS 20 * BE 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 23 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 25 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 26 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 #ifndef __MSG_Q_H__ 30 #define __MSG_Q_H__ 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif /* __cplusplus */ 35 36 #include <stdlib.h> 37 38 /** Linked List Return Codes */ 39 typedef enum 40 { 41 eMSG_Q_SUCCESS = 0, 42 /**< Request was successful. */ 43 eMSG_Q_FAILURE_GENERAL = -1, 44 /**< Failed because of a general failure. */ 45 eMSG_Q_INVALID_PARAMETER = -2, 46 /**< Failed because the request contained invalid parameters. */ 47 eMSG_Q_INVALID_HANDLE = -3, 48 /**< Failed because an invalid handle was specified. */ 49 eMSG_Q_UNAVAILABLE_RESOURCE = -4, 50 /**< Failed because an there were not enough resources. */ 51 eMSG_Q_INSUFFICIENT_BUFFER = -5, 52 /**< Failed because an the supplied buffer was too small. */ 53 }msq_q_err_type; 54 55 /*=========================================================================== 56 FUNCTION msg_q_init 57 58 DESCRIPTION 59 Initializes internal structures for message queue. 60 61 msg_q_data: pointer to an opaque Q handle to be returned; NULL if fails 62 63 DEPENDENCIES 64 N/A 65 66 RETURN VALUE 67 Look at error codes above. 68 69 SIDE EFFECTS 70 N/A 71 72 ===========================================================================*/ 73 msq_q_err_type msg_q_init(void** msg_q_data); 74 75 /*=========================================================================== 76 FUNCTION msg_q_init2 77 78 DESCRIPTION 79 Initializes internal structures for message queue. 80 81 DEPENDENCIES 82 N/A 83 84 RETURN VALUE 85 opaque handle to the Q created; NULL if create fails 86 87 SIDE EFFECTS 88 N/A 89 90 ===========================================================================*/ 91 const void* msg_q_init2(); 92 93 /*=========================================================================== 94 FUNCTION msg_q_destroy 95 96 DESCRIPTION 97 Releases internal structures for message queue. 98 99 msg_q_data: State of message queue to be released. 100 101 DEPENDENCIES 102 N/A 103 104 RETURN VALUE 105 Look at error codes above. 106 107 SIDE EFFECTS 108 N/A 109 110 ===========================================================================*/ 111 msq_q_err_type msg_q_destroy(void** msg_q_data); 112 113 /*=========================================================================== 114 FUNCTION msg_q_snd 115 116 DESCRIPTION 117 Sends data to the message queue. The passed in data pointer 118 is not modified or freed. Passed in msg_obj is expected to live throughout 119 the use of the msg_q (i.e. data is not allocated internally) 120 121 msg_q_data: Message Queue to add the element to. 122 msgp: Pointer to data to add into message queue. 123 dealloc: Function used to deallocate memory for this element. Pass NULL 124 if you do not want data deallocated during a flush operation 125 126 DEPENDENCIES 127 N/A 128 129 RETURN VALUE 130 Look at error codes above. 131 132 SIDE EFFECTS 133 N/A 134 135 ===========================================================================*/ 136 msq_q_err_type msg_q_snd(void* msg_q_data, void* msg_obj, void (*dealloc)(void*)); 137 138 /*=========================================================================== 139 FUNCTION msg_q_rcv 140 141 DESCRIPTION 142 Retrieves data from the message queue. msg_obj is the oldest message received 143 and pointer is simply removed from message queue. 144 145 msg_q_data: Message Queue to copy data from into msgp. 146 msg_obj: Pointer to space to copy msg_q contents to. 147 148 DEPENDENCIES 149 N/A 150 151 RETURN VALUE 152 Look at error codes above. 153 154 SIDE EFFECTS 155 N/A 156 157 ===========================================================================*/ 158 msq_q_err_type msg_q_rcv(void* msg_q_data, void** msg_obj); 159 160 /*=========================================================================== 161 FUNCTION msg_q_flush 162 163 DESCRIPTION 164 Function removes all elements from the message queue. 165 166 msg_q_data: Message Queue to remove elements from. 167 168 DEPENDENCIES 169 N/A 170 171 RETURN VALUE 172 Look at error codes above. 173 174 SIDE EFFECTS 175 N/A 176 177 ===========================================================================*/ 178 msq_q_err_type msg_q_flush(void* msg_q_data); 179 180 /*=========================================================================== 181 FUNCTION msg_q_unblock 182 183 DESCRIPTION 184 This function will stop use of the message queue. All waiters will wake up 185 and likely receive nothing from the queue resulting in a negative return 186 value. The message queue can no longer be used until it is destroyed 187 and initialized again after calling this function. 188 189 msg_q_data: Message queue to unblock. 190 191 DEPENDENCIES 192 N/A 193 194 RETURN VALUE 195 Look at error codes above. 196 197 SIDE EFFECTS 198 N/A 199 200 ===========================================================================*/ 201 msq_q_err_type msg_q_unblock(void* msg_q_data); 202 203 #ifdef __cplusplus 204 } 205 #endif /* __cplusplus */ 206 207 #endif /* __MSG_Q_H__ */ 208