← Back to branch summary

~matttbe/ubuntu/raring/geis/lp1077376

« back to all changes in this revision

Viewing changes to libs/geis-dbus/geis_dbus_dispatcher.h

  • Committer: Package Import Robot
  • Author(s): Chase Douglas
  • Date: 2012-07-30 08:51:42 UTC
  • Revision ID: package-import@ubuntu.com-20120730085142-jrc33ygjvt0ob1wl
Tags: upstream-2.2.11
Import upstream version 2.2.11

Show diffs side-by-side

added added

removed removed

Lines of Context:
libs/geis-dbus/geis_dbus_dispatcher.h
 
1
/**
 
2
 * @file geis_dbus_dispatcher.h
 
3
 * @brief Interface for the GEIS DBus dispatcher.
 
4
 *
 
5
 * The GEIS DBus dispatcher provides a central dispatch point for all DBus
 
6
 * events used internally by GEIS.
 
7
 *
 
8
 * This header is for internal GEIS use only and contains no client
 
9
 * (externally-visible) symbols.
 
10
 */
 
11
 
 
12
/*
 
13
 * Copyright 2011 Canonical Ltd.
 
14
 *
 
15
 * This library is free software; you can redistribute it and/or modify it under
 
16
 * the terms of the GNU Lesser General Public License as published by the Free
 
17
 * Software Foundation; either version 3 of the License, or (at your option) any
 
18
 * later version.
 
19
 *
 
20
 * This library is distributed in the hope that it will be useful, but WITHOUT
 
21
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 
22
 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
 
23
 * details.
 
24
 *
 
25
 * You should have received a copy of the GNU General Public License
 
26
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
27
 */
 
28
#ifndef GEIS_DBUS_DISPATCHER_H_
 
29
#define GEIS_DBUS_DISPATCHER_H_
 
30
 
 
31
#include <dbus/dbus.h>
 
32
#include "geis/geis.h"
 
33
 
 
34
 
 
35
/**
 
36
 * The %GeisDBusDispatcher centralizes all dispatch for all DBus events used
 
37
 * internally by the GEIS client-server mechanism.
 
38
 *
 
39
 * Geis implements single-threaded ansynchronous dispatch for DBus events, in
 
40
 * case a single-threaded client is making use of GEIS.  This also simplifies a
 
41
 * lot of the internal design of the GEIS DBus service, since no locking or
 
42
 * other forms of synchronization are required.
 
43
 */
 
44
typedef struct GeisDBusDispatcher *GeisDBusDispatcher;
 
45
 
 
46
/**
 
47
 * A callback type for the handler function dispatched on DBus events.
 
48
 *
 
49
 * @todo the parameters of the GeisDispatchCallback must be defined.
 
50
 */
 
51
typedef void (*GeisDispatchCallback)(void *context);
 
52
 
 
53
 
 
54
/**
 
55
 * Creates a new GEIS DBus dispatcher.
 
56
 *
 
57
 * @param[in] geis  A GEIS instance.
 
58
 *
 
59
 * Creates a new %GeisDBusDispatcher and registers it with the GEIS API instance
 
60
 * so it will be multiplexed and receive event notification.
 
61
 *
 
62
 * @returns a new %GeisDBusDispatcher object or NULL on failure.
 
63
 */
 
64
GeisDBusDispatcher
 
65
geis_dbus_dispatcher_new(Geis geis);
 
66
 
 
67
/**
 
68
 * Destroys an existing %GeisDBusDispatcher object.
 
69
 *
 
70
 * @param[in] dispatcher  A %GeisDBusDispatcher object.
 
71
 */
 
72
void
 
73
geis_dbus_dispatcher_delete(GeisDBusDispatcher dispatcher);
 
74
 
 
75
/**
 
76
 * Registers a new DBusWatch with a %GeisDBusDispatcher object.
 
77
 *
 
78
 * @param[in] dispatcher  A %GeisDBusDispatcher object.
 
79
 * @param[in] connection  A DBus connection.
 
80
 * @param[in] watch       A DBusWatch om the connection.
 
81
 *
 
82
 * The @p watch will be registered with the @p dispatcher for future DBus
 
83
 * events.  The @p watch may or may not be activated, depending on its @a
 
84
 * enabled state at the time of registration.
 
85
 */
 
86
void
 
87
geis_dbus_dispatcher_register(GeisDBusDispatcher  dispatcher,
 
88
                              DBusConnection     *connection,
 
89
                              DBusWatch          *watch);
 
90
 
 
91
/**
 
92
 * Unregisters a DBusWatch for events.
 
93
 *
 
94
 * @param[in] dispatcher  A %GeisDBusDispatcher object.
 
95
 * @param[in] watch       A DBusWatch.
 
96
 */
 
97
void
 
98
geis_dbus_dispatcher_unregister(GeisDBusDispatcher  dispatcher,
 
99
                                DBusWatch          *watch);
 
100
 
 
101
/**
 
102
 * Marks a DBusWatch as active or not, depending on its state.
 
103
 *
 
104
 * @param[in] dispatcher  A %GeisDBusDispatcher object.
 
105
 * @param[in] watch       A pointer to a DBusWatch object.
 
106
 *
 
107
 * The @p dispatcher will listen for events on the @p watch if its @a is_enabled
 
108
 * state is true or not.
 
109
 */
 
110
void
 
111
geis_dbus_dispatcher_toggle_watch(GeisDBusDispatcher  dispatcher,
 
112
                                  DBusWatch          *watch);
 
113
 
 
114
 
 
115
 
 
116
#endif /* GEIS_DBUS_DISPATCHER_H_ */