1 /* -*- mode: C; c-file-style: "gnu" -*- */
2 /* dbus-message-handler.c Sender/receiver of messages.
4 * Copyright (C) 2002, 2003 Red Hat Inc.
6 * Licensed under the Academic Free License version 1.2
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU General Public License as published by
10 * the Free Software Foundation; either version 2 of the License, or
11 * (at your option) any later version.
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 #include "dbus-internals.h"
25 #include "dbus-message-handler.h"
26 #include "dbus-list.h"
27 #include "dbus-threads.h"
28 #include "dbus-test.h"
29 #include "dbus-connection-internal.h"
32 * @defgroup DBusMessageHandlerInternals DBusMessageHandler implementation details
33 * @ingroup DBusInternals
34 * @brief DBusMessageHandler private implementation details.
36 * The guts of DBusMessageHandler and its methods.
41 _DBUS_DEFINE_GLOBAL_LOCK (message_handler);
44 * @brief Internals of DBusMessageHandler
46 * Object that can send and receive messages.
48 struct DBusMessageHandler
50 DBusAtomic refcount; /**< reference count */
52 DBusHandleMessageFunction function; /**< handler function */
53 void *user_data; /**< user data for function */
54 DBusFreeFunction free_user_data; /**< free the user data */
56 DBusList *connections; /**< connections we're registered with */
60 * Add this connection to the list used by this message handler.
61 * When the message handler goes away, the connection
64 * @param handler the message handler
65 * @param connection the connection
66 * @returns #FALSE if not enough memory
69 _dbus_message_handler_add_connection (DBusMessageHandler *handler,
70 DBusConnection *connection)
74 _DBUS_LOCK (message_handler);
75 /* This is a bit wasteful - we just put the connection in the list
76 * once per time it's added. :-/
78 if (!_dbus_list_prepend (&handler->connections, connection))
83 _DBUS_UNLOCK (message_handler);
89 * Reverses the effect of _dbus_message_handler_add_connection().
90 * @param handler the message handler
91 * @param connection the connection
94 _dbus_message_handler_remove_connection (DBusMessageHandler *handler,
95 DBusConnection *connection)
97 _DBUS_LOCK (message_handler);
98 if (!_dbus_list_remove (&handler->connections, connection))
99 _dbus_warn ("Function _dbus_message_handler_remove_connection() called when the connection hadn't been added\n");
100 _DBUS_UNLOCK (message_handler);
105 * Handles the given message, by dispatching the handler function
106 * for this DBusMessageHandler, if any.
108 * @param handler the handler
109 * @param connection the connection that received the message
110 * @param message the message
112 * @returns what to do with the message
115 _dbus_message_handler_handle_message (DBusMessageHandler *handler,
116 DBusConnection *connection,
117 DBusMessage *message)
119 DBusHandleMessageFunction function;
122 _DBUS_LOCK (message_handler);
123 function = handler->function;
124 user_data = handler->user_data;
125 _DBUS_UNLOCK (message_handler);
127 /* This function doesn't ref handler/connection/message
128 * since that's done in dbus_connection_dispatch().
130 if (function != NULL)
131 return (* function) (handler, connection, message, user_data);
133 return DBUS_HANDLER_RESULT_ALLOW_MORE_HANDLERS;
139 * @defgroup DBusMessageHandler DBusMessageHandler
141 * @brief Message processor
143 * A DBusMessageHandler is an object that can send and receive
144 * messages. Typically the handler is registered with one or
145 * more DBusConnection objects and processes some types of
146 * messages received from the connection.
152 * @typedef DBusMessageHandler
154 * Opaque data type representing a message handler.
158 * Creates a new message handler. The handler function
159 * may be #NULL for a no-op handler or a handler to
160 * be assigned a function later.
162 * @param function function to call to handle a message
163 * @param user_data data to pass to the function
164 * @param free_user_data function to call to free the user data
165 * @returns a new DBusMessageHandler or #NULL if no memory.
168 dbus_message_handler_new (DBusHandleMessageFunction function,
170 DBusFreeFunction free_user_data)
172 DBusMessageHandler *handler;
174 handler = dbus_new (DBusMessageHandler, 1);
179 handler->refcount.value = 1;
180 handler->function = function;
181 handler->user_data = user_data;
182 handler->free_user_data = free_user_data;
183 handler->connections = NULL;
189 * Increments the reference count on a message handler.
191 * @param handler the handler
194 dbus_message_handler_ref (DBusMessageHandler *handler)
196 _dbus_return_if_fail (handler != NULL);
198 _dbus_atomic_inc (&handler->refcount);
202 * Decrements the reference count on a message handler,
203 * freeing the handler if the count reaches 0.
205 * @param handler the handler
208 dbus_message_handler_unref (DBusMessageHandler *handler)
210 dbus_bool_t last_unref;
212 _dbus_return_if_fail (handler != NULL);
214 last_unref = (_dbus_atomic_dec (&handler->refcount) == 1);
220 if (handler->free_user_data)
221 (* handler->free_user_data) (handler->user_data);
223 link = _dbus_list_get_first_link (&handler->connections);
226 DBusConnection *connection = link->data;
228 _dbus_connection_handler_destroyed_locked (connection, handler);
230 link = _dbus_list_get_next_link (&handler->connections, link);
233 _dbus_list_clear (&handler->connections);
240 * Gets the user data for the handler (the same user data
241 * passed to the handler function.)
243 * @param handler the handler
244 * @returns the user data
247 dbus_message_handler_get_data (DBusMessageHandler *handler)
251 _dbus_return_val_if_fail (handler != NULL, NULL);
253 _DBUS_LOCK (message_handler);
254 user_data = handler->user_data;
255 _DBUS_UNLOCK (message_handler);
260 * Sets the user data for the handler (the same user data
261 * to be passed to the handler function). Frees any previously-existing
262 * user data with the previous free_user_data function.
264 * @param handler the handler
265 * @param user_data the user data
266 * @param free_user_data free function for the data
269 dbus_message_handler_set_data (DBusMessageHandler *handler,
271 DBusFreeFunction free_user_data)
273 DBusFreeFunction old_free_func;
276 _dbus_return_if_fail (handler != NULL);
278 _DBUS_LOCK (message_handler);
279 old_free_func = handler->free_user_data;
280 old_user_data = handler->user_data;
282 handler->user_data = user_data;
283 handler->free_user_data = free_user_data;
284 _DBUS_UNLOCK (message_handler);
287 (* old_free_func) (old_user_data);
292 * Sets the handler function. Call dbus_message_handler_set_data()
293 * to set the user data for the function.
295 * @param handler the handler
296 * @param function the function
299 dbus_message_handler_set_function (DBusMessageHandler *handler,
300 DBusHandleMessageFunction function)
302 _dbus_return_if_fail (handler != NULL);
304 _DBUS_LOCK (message_handler);
305 handler->function = function;
306 _DBUS_UNLOCK (message_handler);
311 #ifdef DBUS_BUILD_TESTS
312 static DBusHandlerResult
313 test_handler (DBusMessageHandler *handler,
314 DBusConnection *connection,
315 DBusMessage *message,
318 return DBUS_HANDLER_RESULT_ALLOW_MORE_HANDLERS;
322 free_test_data (void *data)
328 * @ingroup DBusMessageInternals
329 * Unit test for DBusMessageHandler.
331 * @returns #TRUE on success.
334 _dbus_message_handler_test (const char *test_data_dir)
336 DBusMessageHandler *handler;
338 #define TEST_DATA ((void*) 0xcafebabe)
340 handler = dbus_message_handler_new (test_handler,
344 _dbus_assert (handler != NULL);
345 _dbus_assert (handler->function == test_handler);
347 if (dbus_message_handler_get_data (handler) != TEST_DATA)
348 _dbus_assert_not_reached ("got wrong data");
350 dbus_message_handler_set_data (handler, NULL, NULL);
351 if (dbus_message_handler_get_data (handler) != NULL)
352 _dbus_assert_not_reached ("got wrong data after set");
354 dbus_message_handler_set_function (handler, NULL);
355 _dbus_assert (handler->function == NULL);
357 dbus_message_handler_ref (handler);
358 dbus_message_handler_unref (handler);
359 dbus_message_handler_unref (handler);
363 #endif /* DBUS_BUILD_TESTS */