1/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2/* dbus-connection.h DBusConnection object
3 *
4 * Copyright (C) 2002, 2003 Red Hat Inc.
5 *
6 * Licensed under the Academic Free License version 2.1
7 *
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.
12 *
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.
17 *
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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
21 *
22 */
23#if !defined (DBUS_INSIDE_DBUS_H) && !defined (DBUS_COMPILATION)
24#error "Only <dbus/dbus.h> can be included directly, this file may disappear or change contents."
25#endif
26
27#ifndef DBUS_CONNECTION_H
28#define DBUS_CONNECTION_H
29
30#include <dbus/dbus-errors.h>
31#include <dbus/dbus-macros.h>
32#include <dbus/dbus-memory.h>
33#include <dbus/dbus-message.h>
34#include <dbus/dbus-shared.h>
35
36DBUS_BEGIN_DECLS
37
38/**
39 * @addtogroup DBusConnection
40 * @{
41 */
42
43/* documented in dbus-watch.c */
44typedef struct DBusWatch DBusWatch;
45/* documented in dbus-timeout.c */
46typedef struct DBusTimeout DBusTimeout;
47/** Opaque type representing preallocated resources so a message can be sent without further memory allocation. */
48typedef struct DBusPreallocatedSend DBusPreallocatedSend;
49/** Opaque type representing a method call that has not yet received a reply. */
50typedef struct DBusPendingCall DBusPendingCall;
51/** Opaque type representing a connection to a remote application and associated incoming/outgoing message queues. */
52typedef struct DBusConnection DBusConnection;
53/** Set of functions that must be implemented to handle messages sent to a particular object path. */
54typedef struct DBusObjectPathVTable DBusObjectPathVTable;
55
56/**
57 * Indicates the status of a #DBusWatch.
58 */
59typedef enum
60{
61 DBUS_WATCH_READABLE = 1 << 0, /**< As in POLLIN */
62 DBUS_WATCH_WRITABLE = 1 << 1, /**< As in POLLOUT */
63 DBUS_WATCH_ERROR = 1 << 2, /**< As in POLLERR (can't watch for
64 * this, but can be present in
65 * current state passed to
66 * dbus_watch_handle()).
67 */
68 DBUS_WATCH_HANGUP = 1 << 3 /**< As in POLLHUP (can't watch for
69 * it, but can be present in current
70 * state passed to
71 * dbus_watch_handle()).
72 */
73 /* Internal to libdbus, there is also _DBUS_WATCH_NVAL in dbus-watch.h */
74} DBusWatchFlags;
75
76/**
77 * Indicates the status of incoming data on a #DBusConnection. This determines whether
78 * dbus_connection_dispatch() needs to be called.
79 */
80typedef enum
81{
82 DBUS_DISPATCH_DATA_REMAINS, /**< There is more data to potentially convert to messages. */
83 DBUS_DISPATCH_COMPLETE, /**< All currently available data has been processed. */
84 DBUS_DISPATCH_NEED_MEMORY /**< More memory is needed to continue. */
85} DBusDispatchStatus;
86
87/** Called when libdbus needs a new watch to be monitored by the main
88 * loop. Returns #FALSE if it lacks enough memory to add the
89 * watch. Set by dbus_connection_set_watch_functions() or
90 * dbus_server_set_watch_functions().
91 */
92typedef dbus_bool_t (* DBusAddWatchFunction) (DBusWatch *watch,
93 void *data);
94/** Called when dbus_watch_get_enabled() may return a different value
95 * than it did before. Set by dbus_connection_set_watch_functions()
96 * or dbus_server_set_watch_functions().
97 */
98typedef void (* DBusWatchToggledFunction) (DBusWatch *watch,
99 void *data);
100/** Called when libdbus no longer needs a watch to be monitored by the
101 * main loop. Set by dbus_connection_set_watch_functions() or
102 * dbus_server_set_watch_functions().
103 */
104typedef void (* DBusRemoveWatchFunction) (DBusWatch *watch,
105 void *data);
106/** Called when libdbus needs a new timeout to be monitored by the main
107 * loop. Returns #FALSE if it lacks enough memory to add the
108 * watch. Set by dbus_connection_set_timeout_functions() or
109 * dbus_server_set_timeout_functions().
110 */
111typedef dbus_bool_t (* DBusAddTimeoutFunction) (DBusTimeout *timeout,
112 void *data);
113/** Called when dbus_timeout_get_enabled() may return a different
114 * value than it did before.
115 * Set by dbus_connection_set_timeout_functions() or
116 * dbus_server_set_timeout_functions().
117 */
118typedef void (* DBusTimeoutToggledFunction) (DBusTimeout *timeout,
119 void *data);
120/** Called when libdbus no longer needs a timeout to be monitored by the
121 * main loop. Set by dbus_connection_set_timeout_functions() or
122 * dbus_server_set_timeout_functions().
123 */
124typedef void (* DBusRemoveTimeoutFunction) (DBusTimeout *timeout,
125 void *data);
126/** Called when the return value of dbus_connection_get_dispatch_status()
127 * may have changed. Set with dbus_connection_set_dispatch_status_function().
128 */
129typedef void (* DBusDispatchStatusFunction) (DBusConnection *connection,
130 DBusDispatchStatus new_status,
131 void *data);
132/**
133 * Called when the main loop's thread should be notified that there's now work
134 * to do. Set with dbus_connection_set_wakeup_main_function().
135 */
136typedef void (* DBusWakeupMainFunction) (void *data);
137
138/**
139 * Called during authentication to check whether the given UNIX user
140 * ID is allowed to connect, if the client tried to auth as a UNIX
141 * user ID. Normally on Windows this would never happen. Set with
142 * dbus_connection_set_unix_user_function().
143 */
144typedef dbus_bool_t (* DBusAllowUnixUserFunction) (DBusConnection *connection,
145 unsigned long uid,
146 void *data);
147
148/**
149 * Called during authentication to check whether the given Windows user
150 * ID is allowed to connect, if the client tried to auth as a Windows
151 * user ID. Normally on UNIX this would never happen. Set with
152 * dbus_connection_set_windows_user_function().
153 */
154typedef dbus_bool_t (* DBusAllowWindowsUserFunction) (DBusConnection *connection,
155 const char *user_sid,
156 void *data);
157
158
159/**
160 * Called when a pending call now has a reply available. Set with
161 * dbus_pending_call_set_notify().
162 */
163typedef void (* DBusPendingCallNotifyFunction) (DBusPendingCall *pending,
164 void *user_data);
165
166/**
167 * Called when a message needs to be handled. The result indicates whether or
168 * not more handlers should be run. Set with dbus_connection_add_filter().
169 */
170typedef DBusHandlerResult (* DBusHandleMessageFunction) (DBusConnection *connection,
171 DBusMessage *message,
172 void *user_data);
173DBUS_EXPORT
174DBusConnection* dbus_connection_open (const char *address,
175 DBusError *error);
176DBUS_EXPORT
177DBusConnection* dbus_connection_open_private (const char *address,
178 DBusError *error);
179DBUS_EXPORT
180DBusConnection* dbus_connection_ref (DBusConnection *connection);
181DBUS_EXPORT
182void dbus_connection_unref (DBusConnection *connection);
183DBUS_EXPORT
184void dbus_connection_close (DBusConnection *connection);
185DBUS_EXPORT
186dbus_bool_t dbus_connection_get_is_connected (DBusConnection *connection);
187DBUS_EXPORT
188dbus_bool_t dbus_connection_get_is_authenticated (DBusConnection *connection);
189DBUS_EXPORT
190dbus_bool_t dbus_connection_get_is_anonymous (DBusConnection *connection);
191DBUS_EXPORT
192char* dbus_connection_get_server_id (DBusConnection *connection);
193DBUS_EXPORT
194dbus_bool_t dbus_connection_can_send_type (DBusConnection *connection,
195 int type);
196
197DBUS_EXPORT
198void dbus_connection_set_exit_on_disconnect (DBusConnection *connection,
199 dbus_bool_t exit_on_disconnect);
200DBUS_EXPORT
201void dbus_connection_flush (DBusConnection *connection);
202DBUS_EXPORT
203dbus_bool_t dbus_connection_read_write_dispatch (DBusConnection *connection,
204 int timeout_milliseconds);
205DBUS_EXPORT
206dbus_bool_t dbus_connection_read_write (DBusConnection *connection,
207 int timeout_milliseconds);
208DBUS_EXPORT
209DBusMessage* dbus_connection_borrow_message (DBusConnection *connection);
210DBUS_EXPORT
211void dbus_connection_return_message (DBusConnection *connection,
212 DBusMessage *message);
213DBUS_EXPORT
214void dbus_connection_steal_borrowed_message (DBusConnection *connection,
215 DBusMessage *message);
216DBUS_EXPORT
217DBusMessage* dbus_connection_pop_message (DBusConnection *connection);
218DBUS_EXPORT
219DBusDispatchStatus dbus_connection_get_dispatch_status (DBusConnection *connection);
220DBUS_EXPORT
221DBusDispatchStatus dbus_connection_dispatch (DBusConnection *connection);
222DBUS_EXPORT
223dbus_bool_t dbus_connection_has_messages_to_send (DBusConnection *connection);
224DBUS_EXPORT
225dbus_bool_t dbus_connection_send (DBusConnection *connection,
226 DBusMessage *message,
227 dbus_uint32_t *client_serial);
228DBUS_EXPORT
229dbus_bool_t dbus_connection_send_with_reply (DBusConnection *connection,
230 DBusMessage *message,
231 DBusPendingCall **pending_return,
232 int timeout_milliseconds);
233DBUS_EXPORT
234DBusMessage * dbus_connection_send_with_reply_and_block (DBusConnection *connection,
235 DBusMessage *message,
236 int timeout_milliseconds,
237 DBusError *error);
238DBUS_EXPORT
239dbus_bool_t dbus_connection_set_watch_functions (DBusConnection *connection,
240 DBusAddWatchFunction add_function,
241 DBusRemoveWatchFunction remove_function,
242 DBusWatchToggledFunction toggled_function,
243 void *data,
244 DBusFreeFunction free_data_function);
245DBUS_EXPORT
246dbus_bool_t dbus_connection_set_timeout_functions (DBusConnection *connection,
247 DBusAddTimeoutFunction add_function,
248 DBusRemoveTimeoutFunction remove_function,
249 DBusTimeoutToggledFunction toggled_function,
250 void *data,
251 DBusFreeFunction free_data_function);
252DBUS_EXPORT
253void dbus_connection_set_wakeup_main_function (DBusConnection *connection,
254 DBusWakeupMainFunction wakeup_main_function,
255 void *data,
256 DBusFreeFunction free_data_function);
257DBUS_EXPORT
258void dbus_connection_set_dispatch_status_function (DBusConnection *connection,
259 DBusDispatchStatusFunction function,
260 void *data,
261 DBusFreeFunction free_data_function);
262DBUS_EXPORT
263dbus_bool_t dbus_connection_get_unix_user (DBusConnection *connection,
264 unsigned long *uid);
265DBUS_EXPORT
266dbus_bool_t dbus_connection_get_unix_process_id (DBusConnection *connection,
267 unsigned long *pid);
268DBUS_EXPORT
269dbus_bool_t dbus_connection_get_adt_audit_session_data (DBusConnection *connection,
270 void **data,
271 dbus_int32_t *data_size);
272DBUS_EXPORT
273void dbus_connection_set_unix_user_function (DBusConnection *connection,
274 DBusAllowUnixUserFunction function,
275 void *data,
276 DBusFreeFunction free_data_function);
277DBUS_EXPORT
278dbus_bool_t dbus_connection_get_windows_user (DBusConnection *connection,
279 char **windows_sid_p);
280DBUS_EXPORT
281void dbus_connection_set_windows_user_function (DBusConnection *connection,
282 DBusAllowWindowsUserFunction function,
283 void *data,
284 DBusFreeFunction free_data_function);
285DBUS_EXPORT
286void dbus_connection_set_allow_anonymous (DBusConnection *connection,
287 dbus_bool_t value);
288DBUS_EXPORT
289void dbus_connection_set_route_peer_messages (DBusConnection *connection,
290 dbus_bool_t value);
291
292
293/* Filters */
294
295DBUS_EXPORT
296dbus_bool_t dbus_connection_add_filter (DBusConnection *connection,
297 DBusHandleMessageFunction function,
298 void *user_data,
299 DBusFreeFunction free_data_function);
300DBUS_EXPORT
301void dbus_connection_remove_filter (DBusConnection *connection,
302 DBusHandleMessageFunction function,
303 void *user_data);
304
305
306/* Other */
307DBUS_EXPORT
308dbus_bool_t dbus_connection_allocate_data_slot (dbus_int32_t *slot_p);
309DBUS_EXPORT
310void dbus_connection_free_data_slot (dbus_int32_t *slot_p);
311DBUS_EXPORT
312dbus_bool_t dbus_connection_set_data (DBusConnection *connection,
313 dbus_int32_t slot,
314 void *data,
315 DBusFreeFunction free_data_func);
316DBUS_EXPORT
317void* dbus_connection_get_data (DBusConnection *connection,
318 dbus_int32_t slot);
319
320DBUS_EXPORT
321void dbus_connection_set_change_sigpipe (dbus_bool_t will_modify_sigpipe);
322
323DBUS_EXPORT
324void dbus_connection_set_max_message_size (DBusConnection *connection,
325 long size);
326DBUS_EXPORT
327long dbus_connection_get_max_message_size (DBusConnection *connection);
328DBUS_EXPORT
329void dbus_connection_set_max_received_size (DBusConnection *connection,
330 long size);
331DBUS_EXPORT
332long dbus_connection_get_max_received_size (DBusConnection *connection);
333
334DBUS_EXPORT
335void dbus_connection_set_max_message_unix_fds (DBusConnection *connection,
336 long n);
337DBUS_EXPORT
338long dbus_connection_get_max_message_unix_fds (DBusConnection *connection);
339DBUS_EXPORT
340void dbus_connection_set_max_received_unix_fds(DBusConnection *connection,
341 long n);
342DBUS_EXPORT
343long dbus_connection_get_max_received_unix_fds(DBusConnection *connection);
344
345DBUS_EXPORT
346long dbus_connection_get_outgoing_size (DBusConnection *connection);
347DBUS_EXPORT
348long dbus_connection_get_outgoing_unix_fds (DBusConnection *connection);
349
350DBUS_EXPORT
351DBusPreallocatedSend* dbus_connection_preallocate_send (DBusConnection *connection);
352DBUS_EXPORT
353void dbus_connection_free_preallocated_send (DBusConnection *connection,
354 DBusPreallocatedSend *preallocated);
355DBUS_EXPORT
356void dbus_connection_send_preallocated (DBusConnection *connection,
357 DBusPreallocatedSend *preallocated,
358 DBusMessage *message,
359 dbus_uint32_t *client_serial);
360
361
362/* Object tree functionality */
363
364/**
365 * Called when a #DBusObjectPathVTable is unregistered (or its connection is freed).
366 * Found in #DBusObjectPathVTable.
367 */
368typedef void (* DBusObjectPathUnregisterFunction) (DBusConnection *connection,
369 void *user_data);
370/**
371 * Called when a message is sent to a registered object path. Found in
372 * #DBusObjectPathVTable which is registered with dbus_connection_register_object_path()
373 * or dbus_connection_register_fallback().
374 */
375typedef DBusHandlerResult (* DBusObjectPathMessageFunction) (DBusConnection *connection,
376 DBusMessage *message,
377 void *user_data);
378
379/**
380 * Virtual table that must be implemented to handle a portion of the
381 * object path hierarchy. Attach the vtable to a particular path using
382 * dbus_connection_register_object_path() or
383 * dbus_connection_register_fallback().
384 */
385struct DBusObjectPathVTable
386{
387 DBusObjectPathUnregisterFunction unregister_function; /**< Function to unregister this handler */
388 DBusObjectPathMessageFunction message_function; /**< Function to handle messages */
389
390 void (* dbus_internal_pad1) (void *); /**< Reserved for future expansion */
391 void (* dbus_internal_pad2) (void *); /**< Reserved for future expansion */
392 void (* dbus_internal_pad3) (void *); /**< Reserved for future expansion */
393 void (* dbus_internal_pad4) (void *); /**< Reserved for future expansion */
394};
395
396DBUS_EXPORT
397dbus_bool_t dbus_connection_try_register_object_path (DBusConnection *connection,
398 const char *path,
399 const DBusObjectPathVTable *vtable,
400 void *user_data,
401 DBusError *error);
402
403DBUS_EXPORT
404dbus_bool_t dbus_connection_register_object_path (DBusConnection *connection,
405 const char *path,
406 const DBusObjectPathVTable *vtable,
407 void *user_data);
408
409DBUS_EXPORT
410dbus_bool_t dbus_connection_try_register_fallback (DBusConnection *connection,
411 const char *path,
412 const DBusObjectPathVTable *vtable,
413 void *user_data,
414 DBusError *error);
415
416DBUS_EXPORT
417dbus_bool_t dbus_connection_register_fallback (DBusConnection *connection,
418 const char *path,
419 const DBusObjectPathVTable *vtable,
420 void *user_data);
421DBUS_EXPORT
422dbus_bool_t dbus_connection_unregister_object_path (DBusConnection *connection,
423 const char *path);
424
425DBUS_EXPORT
426dbus_bool_t dbus_connection_get_object_path_data (DBusConnection *connection,
427 const char *path,
428 void **data_p);
429
430DBUS_EXPORT
431dbus_bool_t dbus_connection_list_registered (DBusConnection *connection,
432 const char *parent_path,
433 char ***child_entries);
434
435DBUS_EXPORT
436dbus_bool_t dbus_connection_get_unix_fd (DBusConnection *connection,
437 int *fd);
438DBUS_EXPORT
439dbus_bool_t dbus_connection_get_socket (DBusConnection *connection,
440 int *fd);
441
442/**
443 * Clear a variable or struct member that contains a #DBusConnection.
444 * If it does not contain #NULL, the connection that was previously
445 * there is unreferenced with dbus_connection_unref().
446 *
447 * For example, this function and the similar functions for
448 * other reference-counted types can be used in code like this:
449 *
450 * @code
451 * DBusConnection *conn = NULL;
452 * struct { ...; DBusMessage *m; ... } *larger_structure = ...;
453 *
454 * ... code that might set conn or m to be non-NULL ...
455 *
456 * dbus_clear_connection (&conn);
457 * dbus_clear_message (&larger_structure->m);
458 * @endcode
459 *
460 * @param pointer_to_connection A pointer to a variable or struct member.
461 * pointer_to_connection must not be #NULL, but *pointer_to_connection
462 * may be #NULL.
463 */
464static inline void
465dbus_clear_connection (DBusConnection **pointer_to_connection)
466{
467 _dbus_clear_pointer_impl (DBusConnection, pointer_to_connection,
468 dbus_connection_unref);
469}
470
471/** @} */
472
473
474/**
475 * @addtogroup DBusWatch
476 * @{
477 */
478
479#ifndef DBUS_DISABLE_DEPRECATED
480DBUS_EXPORT
481DBUS_DEPRECATED int dbus_watch_get_fd (DBusWatch *watch);
482#endif
483
484DBUS_EXPORT
485int dbus_watch_get_unix_fd (DBusWatch *watch);
486DBUS_EXPORT
487int dbus_watch_get_socket (DBusWatch *watch);
488DBUS_EXPORT
489unsigned int dbus_watch_get_flags (DBusWatch *watch);
490DBUS_EXPORT
491void* dbus_watch_get_data (DBusWatch *watch);
492DBUS_EXPORT
493void dbus_watch_set_data (DBusWatch *watch,
494 void *data,
495 DBusFreeFunction free_data_function);
496DBUS_EXPORT
497dbus_bool_t dbus_watch_handle (DBusWatch *watch,
498 unsigned int flags);
499DBUS_EXPORT
500dbus_bool_t dbus_watch_get_enabled (DBusWatch *watch);
501
502/** @} */
503
504/**
505 * @addtogroup DBusTimeout
506 * @{
507 */
508
509DBUS_EXPORT
510int dbus_timeout_get_interval (DBusTimeout *timeout);
511DBUS_EXPORT
512void* dbus_timeout_get_data (DBusTimeout *timeout);
513DBUS_EXPORT
514void dbus_timeout_set_data (DBusTimeout *timeout,
515 void *data,
516 DBusFreeFunction free_data_function);
517DBUS_EXPORT
518dbus_bool_t dbus_timeout_handle (DBusTimeout *timeout);
519DBUS_EXPORT
520dbus_bool_t dbus_timeout_get_enabled (DBusTimeout *timeout);
521
522/** @} */
523
524DBUS_END_DECLS
525
526#endif /* DBUS_CONNECTION_H */
527