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