1/* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
2/* vim:set et sts=4: */
3/* ibus - The Input Bus
4 * Copyright (C) 2008-2013 Peng Huang <shawn.p.huang@gmail.com>
5 * Copyright (C) 2008-2013 Red Hat, Inc.
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
20 * USA
21 */
22
23#if !defined (__IBUS_H_INSIDE__) && !defined (IBUS_COMPILATION)
24#error "Only <ibus.h> can be included directly"
25#endif
26
27#ifndef __IBUS_CONFIG_H_
28#define __IBUS_CONFIG_H_
29
30/**
31 * SECTION: ibusconfig
32 * @title: IBusConfig
33 * @short_description: IBus engine configuration module.
34 *
35 * An IBusConfig provides engine configuration methods
36 * such as get and set the configure settings to configuration file.
37 *
38 * Currently, IBusConfig supports gconf.
39 */
40
41#include "ibusproxy.h"
42
43/*
44 * Type macros.
45 */
46
47/* define GOBJECT macros */
48#define IBUS_TYPE_CONFIG \
49 (ibus_config_get_type ())
50#define IBUS_CONFIG(obj) \
51 (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_CONFIG, IBusConfig))
52#define IBUS_CONFIG_CLASS(klass) \
53 (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_CONFIG, IBusConfigClass))
54#define IBUS_IS_CONFIG(obj) \
55 (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_CONFIG))
56#define IBUS_IS_CONFIG_CLASS(klass) \
57 (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_CONFIG))
58#define IBUS_CONFIG_GET_CLASS(obj) \
59 (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_CONFIG, IBusConfigClass))
60
61G_BEGIN_DECLS
62
63typedef struct _IBusConfig IBusConfig;
64typedef struct _IBusConfigClass IBusConfigClass;
65typedef struct _IBusConfigPrivate IBusConfigPrivate;
66
67/**
68 * IBusConfig:
69 *
70 * An opaque data type representing an IBusConfig.
71 */
72struct _IBusConfig {
73 /*< private >*/
74 IBusProxy parent;
75 IBusConfigPrivate *priv;
76
77 /* instance members */
78};
79
80struct _IBusConfigClass {
81 /*< private >*/
82 IBusProxyClass parent;
83
84 /* class members */
85};
86
87GType ibus_config_get_type (void);
88
89/**
90 * ibus_config_new:
91 * @connection: A #GDBusConnection.
92 * @cancellable: A #GCancellable or %NULL.
93 * @error: Return location for error or %NULL.
94 *
95 * Create a new #IBusConfig from existing #GDBusConnection.
96 *
97 * Returns: A newly allocated #IBusConfig corresponding to @connection.
98 */
99IBusConfig *ibus_config_new (GDBusConnection *connection,
100 GCancellable *cancellable,
101 GError **error);
102
103/**
104 * ibus_config_new_async:
105 * @connection: An #GDBusConnection.
106 * @cancellable: A #GCancellable or %NULL.
107 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
108 * The callback should not be %NULL.
109 * @user_data: The data to pass to callback.
110 *
111 * New an #IBusConfig asynchronously.
112 */
113void ibus_config_new_async (GDBusConnection *connection,
114 GCancellable *cancellable,
115 GAsyncReadyCallback callback,
116 gpointer user_data);
117
118/**
119 * ibus_config_new_async_finish:
120 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback pass to
121 * ibus_config_new_async().
122 * @error: Return location for error or %NULL.
123 *
124 * Finishes an operation started with ibus_config_new_async().
125 *
126 * Returns: A newly allocated #IBusConfig.
127 */
128IBusConfig *ibus_config_new_async_finish
129 (GAsyncResult *res,
130 GError **error);
131
132/**
133 * ibus_config_get_value:
134 * @config: An #IBusConfig
135 * @section: Section name of the configuration option.
136 * @name: Name of the configure option.
137 *
138 * Get the value of a configuration option synchronously.
139 *
140 * GConf stores configure options in a tree-like structure,
141 * and the IBus related setting is at /desktop/ibus,
142 * thus, @section here is a path from there,
143 * while @name is the key of that configuration option.
144 *
145 * ibus-chewing, for example, stores its setting in /desktop/ibus/engine/Chewing,
146 * so the section name for it is "engine/Chewing".
147 * See also: ibus_config_set_value().
148 *
149 * Returns: A #GVariant or %NULL. Free with g_variant_unref().
150 */
151GVariant *ibus_config_get_value (IBusConfig *config,
152 const gchar *section,
153 const gchar *name);
154
155/**
156 * ibus_config_get_value_async:
157 * @config: An #IBusConfig
158 * @section: Section name of the configuration option.
159 * @name: Name of the configure option.
160 * @timeout_ms: The timeout in milliseconds or -1 to use the default timeout.
161 * @cancellable: A #GCancellable or %NULL.
162 * @callback: Callback function to invoke when the return value is ready.
163 * @user_data: The data to pass to callback.
164 *
165 * Get the value of a configuration option asynchronously.
166 *
167 * See also: ibus_config_get_value().
168 */
169void ibus_config_get_value_async (IBusConfig *config,
170 const gchar *section,
171 const gchar *name,
172 gint timeout_ms,
173 GCancellable *cancellable,
174 GAsyncReadyCallback callback,
175 gpointer user_data);
176
177/**
178 * ibus_config_get_value_async_finish:
179 * @config: A #IBusConfig.
180 * @result: A #GAsyncResult.
181 * @error: Return location for error or %NULL.
182 *
183 * Finish get value of a configuration option.
184 *
185 * Returns: A #GVariant or %NULL if error is set. Free with g_variant_unref().
186 *
187 * See also: ibus_config_get_value_async().
188 */
189GVariant *ibus_config_get_value_async_finish
190 (IBusConfig *config,
191 GAsyncResult *result,
192 GError **error);
193
194/**
195 * ibus_config_get_values:
196 * @config: An #IBusConfig
197 * @section: Section name of the configuration option.
198 *
199 * Get all values in a section synchronously.
200 *
201 * Returns: A #GVariant or %NULL. Free with g_variant_unref().
202 *
203 * See also: ibus_config_set_value().
204 */
205GVariant *ibus_config_get_values (IBusConfig *config,
206 const gchar *section);
207
208/**
209 * ibus_config_get_values_async:
210 * @config: An #IBusConfig
211 * @section: Section name of the configuration option.
212 * @timeout_ms: The timeout in milliseconds or -1 to use the default timeout.
213 * @cancellable: A #GCancellable or %NULL.
214 * @callback: Callback function to invoke when the return value is ready.
215 * @user_data: The data to pass to callback.
216 *
217 * Get all values in a section asynchronously.
218 *
219 * See also: ibus_config_get_values().
220 */
221void ibus_config_get_values_async(IBusConfig *config,
222 const gchar *section,
223 gint timeout_ms,
224 GCancellable *cancellable,
225 GAsyncReadyCallback callback,
226 gpointer user_data);
227
228/**
229 * ibus_config_get_values_async_finish:
230 * @config: A #IBusConfig.
231 * @result: A #GAsyncResult.
232 * @error: Return location for error or %NULL.
233 *
234 * Finish get values in a section.
235 *
236 * Returns: A #GVariant or %NULL if error is set. Free with g_variant_unref().
237 *
238 * See also: ibus_config_get_values_async().
239 */
240GVariant *ibus_config_get_values_async_finish
241 (IBusConfig *config,
242 GAsyncResult *result,
243 GError **error);
244
245/**
246 * ibus_config_set_value:
247 * @config: An #IBusConfig
248 * @section: Section name of the configuration option.
249 * @name: Name of the configure option its self.
250 * @value: A #GVariant that holds the value. If the value is floating, the
251 * function takes ownership of it.
252 *
253 * Set the value of a configuration option synchronously.
254 *
255 * Returns: %TRUE if succeed; %FALSE otherwise.
256 *
257 * See also: ibus_config_get_value().
258 */
259gboolean ibus_config_set_value (IBusConfig *config,
260 const gchar *section,
261 const gchar *name,
262 GVariant *value);
263
264/**
265 * ibus_config_set_value_async:
266 * @config: An #IBusConfig
267 * @section: Section name of the configuration option.
268 * @name: Name of the configure option.
269 * @value: A #GVariant that holds the value. If the value is floating, the
270 * function takes ownership of it.
271 * @timeout_ms: The timeout in milliseconds or -1 to use the default timeout.
272 * @cancellable: A #GCancellable or %NULL.
273 * @callback: Callback function to invoke when the return value is ready.
274 * @user_data: The data to pass to callback.
275 *
276 * Set the value of a configuration option asynchronously.
277 *
278 * See also: ibus_config_set_value().
279 */
280void ibus_config_set_value_async (IBusConfig *config,
281 const gchar *section,
282 const gchar *name,
283 GVariant *value,
284 gint timeout_ms,
285 GCancellable *cancellable,
286 GAsyncReadyCallback callback,
287 gpointer user_data);
288
289/**
290 * ibus_config_set_value_async_finish:
291 * @config: A #IBusConfig.
292 * @result: A #GAsyncResult.
293 * @error: Return location for error or %NULL.
294 *
295 * Finish set value of a configuration option.
296 *
297 * Returns: %TRUE or %FALSE if error is set.
298 *
299 * See also: ibus_config_set_value_async().
300 */
301gboolean ibus_config_set_value_async_finish
302 (IBusConfig *config,
303 GAsyncResult *result,
304 GError **error);
305
306/**
307 * ibus_config_unset:
308 * @config: An #IBusConfig
309 * @section: Section name of the configuration option.
310 * @name: Name of the configure option its self.
311 *
312 * Remove an entry of a configuration option.
313 *
314 * Returns: %TRUE if succeed; %FALSE otherwise.
315 *
316 * See also: ibus_config_get_value().
317 */
318gboolean ibus_config_unset (IBusConfig *config,
319 const gchar *section,
320 const gchar *name);
321
322/* FIXME add an asynchronous version of unset */
323
324/**
325 * ibus_config_watch:
326 * @config: An #IBusConfig
327 * @section: (allow-none): Section name of the configuration option.
328 * @name: (allow-none): Name of the configure option its self.
329 *
330 * Subscribe to the configuration option change notification.
331 *
332 * Until this function is called, every change will be notified to the
333 * client through #IBusConfig::value-changed signal. Clients should
334 * call ibus_config_watch() with the sections they are interested in,
335 * to reduce the number of D-Bus messages.
336 *
337 * Returns: %TRUE if succeed; %FALSE otherwise.
338 *
339 * See also: ibus_config_unwatch().
340 */
341gboolean ibus_config_watch (IBusConfig *config,
342 const gchar *section,
343 const gchar *name);
344
345/* FIXME add an asynchronous version of watch */
346
347/**
348 * ibus_config_unwatch:
349 * @config: An #IBusConfig
350 * @section: (allow-none): Section name of the configuration option.
351 * @name: (allow-none): Name of the configure option its self.
352 *
353 * Unsubscribe from the configuration option change notification.
354 *
355 * Returns: %TRUE if succeed; %FALSE otherwise.
356 *
357 * See also: ibus_config_watch.
358 */
359gboolean ibus_config_unwatch (IBusConfig *config,
360 const gchar *section,
361 const gchar *name);
362
363/* FIXME add an asynchronous version of unwatch */
364
365G_END_DECLS
366#endif
367
368