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
33extern "C" {
34#endif /* __cplusplus */
35
36#include <stdlib.h>
37
38/** Linked List Return Codes */
39typedef 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/*===========================================================================
56FUNCTION    msg_q_init
57
58DESCRIPTION
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
63DEPENDENCIES
64   N/A
65
66RETURN VALUE
67   Look at error codes above.
68
69SIDE EFFECTS
70   N/A
71
72===========================================================================*/
73msq_q_err_type msg_q_init(void** msg_q_data);
74
75/*===========================================================================
76FUNCTION    msg_q_init2
77
78DESCRIPTION
79   Initializes internal structures for message queue.
80
81DEPENDENCIES
82   N/A
83
84RETURN VALUE
85   opaque handle to the Q created; NULL if create fails
86
87SIDE EFFECTS
88   N/A
89
90===========================================================================*/
91const void* msg_q_init2();
92
93/*===========================================================================
94FUNCTION    msg_q_destroy
95
96DESCRIPTION
97   Releases internal structures for message queue.
98
99   msg_q_data: State of message queue to be released.
100
101DEPENDENCIES
102   N/A
103
104RETURN VALUE
105   Look at error codes above.
106
107SIDE EFFECTS
108   N/A
109
110===========================================================================*/
111msq_q_err_type msg_q_destroy(void** msg_q_data);
112
113/*===========================================================================
114FUNCTION    msg_q_snd
115
116DESCRIPTION
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
126DEPENDENCIES
127   N/A
128
129RETURN VALUE
130   Look at error codes above.
131
132SIDE EFFECTS
133   N/A
134
135===========================================================================*/
136msq_q_err_type msg_q_snd(void* msg_q_data, void* msg_obj, void (*dealloc)(void*));
137
138/*===========================================================================
139FUNCTION    msg_q_rcv
140
141DESCRIPTION
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
148DEPENDENCIES
149   N/A
150
151RETURN VALUE
152   Look at error codes above.
153
154SIDE EFFECTS
155   N/A
156
157===========================================================================*/
158msq_q_err_type msg_q_rcv(void* msg_q_data, void** msg_obj);
159
160/*===========================================================================
161FUNCTION    msg_q_flush
162
163DESCRIPTION
164   Function removes all elements from the message queue.
165
166   msg_q_data: Message Queue to remove elements from.
167
168DEPENDENCIES
169   N/A
170
171RETURN VALUE
172   Look at error codes above.
173
174SIDE EFFECTS
175   N/A
176
177===========================================================================*/
178msq_q_err_type msg_q_flush(void* msg_q_data);
179
180/*===========================================================================
181FUNCTION    msg_q_unblock
182
183DESCRIPTION
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
191DEPENDENCIES
192   N/A
193
194RETURN VALUE
195   Look at error codes above.
196
197SIDE EFFECTS
198   N/A
199
200===========================================================================*/
201msq_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