/* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
/* vim:set et sts=4: */
/* ibus - The Input Bus
* Copyright (C) 2008-2013 Peng Huang <shawn.p.huang@gmail.com>
* Copyright (C) 2008-2013 Red Hat, Inc.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
* USA
*/
#if !defined (__IBUS_H_INSIDE__) && !defined (IBUS_COMPILATION)
#error "Only <ibus.h> can be included directly"
#endif
#ifndef __IBUS_CONFIG_H_
#define __IBUS_CONFIG_H_
/**
* SECTION: ibusconfig
* @title: IBusConfig
* @short_description: IBus engine configuration module.
*
* An IBusConfig provides engine configuration methods
* such as get and set the configure settings to configuration file.
*
* Currently, IBusConfig supports gconf.
*/
#include "ibusproxy.h"
/*
* Type macros.
*/
/* define GOBJECT macros */
#define IBUS_TYPE_CONFIG \
(ibus_config_get_type ())
#define IBUS_CONFIG(obj) \
(G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_CONFIG, IBusConfig))
#define IBUS_CONFIG_CLASS(klass) \
(G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_CONFIG, IBusConfigClass))
#define IBUS_IS_CONFIG(obj) \
(G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_CONFIG))
#define IBUS_IS_CONFIG_CLASS(klass) \
(G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_CONFIG))
#define IBUS_CONFIG_GET_CLASS(obj) \
(G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_CONFIG, IBusConfigClass))
G_BEGIN_DECLS
typedef struct _IBusConfig IBusConfig;
typedef struct _IBusConfigClass IBusConfigClass;
typedef struct _IBusConfigPrivate IBusConfigPrivate;
/**
* IBusConfig:
*
* An opaque data type representing an IBusConfig.
*/
struct _IBusConfig {
/*< private >*/
IBusProxy parent;
IBusConfigPrivate *priv;
/* instance members */
};
struct _IBusConfigClass {
/*< private >*/
IBusProxyClass parent;
/* class members */
};
GType ibus_config_get_type (void);
/**
* ibus_config_new:
* @connection: A #GDBusConnection.
* @cancellable: A #GCancellable or %NULL.
* @error: Return location for error or %NULL.
*
* Create a new #IBusConfig from existing #GDBusConnection.
*
* Returns: A newly allocated #IBusConfig corresponding to @connection.
*/
IBusConfig *ibus_config_new (GDBusConnection *connection,
GCancellable *cancellable,
GError **error);
/**
* ibus_config_new_async:
* @connection: An #GDBusConnection.
* @cancellable: A #GCancellable or %NULL.
* @callback: A #GAsyncReadyCallback to call when the request is satisfied.
* The callback should not be %NULL.
* @user_data: The data to pass to callback.
*
* New an #IBusConfig asynchronously.
*/
void ibus_config_new_async (GDBusConnection *connection,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
/**
* ibus_config_new_async_finish:
* @res: A #GAsyncResult obtained from the #GAsyncReadyCallback pass to
* ibus_config_new_async().
* @error: Return location for error or %NULL.
*
* Finishes an operation started with ibus_config_new_async().
*
* Returns: A newly allocated #IBusConfig.
*/
IBusConfig *ibus_config_new_async_finish
(GAsyncResult *res,
GError **error);
/**
* ibus_config_get_value:
* @config: An #IBusConfig
* @section: Section name of the configuration option.
* @name: Name of the configure option.
*
* Get the value of a configuration option synchronously.
*
* GConf stores configure options in a tree-like structure,
* and the IBus related setting is at /desktop/ibus,
* thus, @section here is a path from there,
* while @name is the key of that configuration option.
*
* ibus-chewing, for example, stores its setting in /desktop/ibus/engine/Chewing,
* so the section name for it is "engine/Chewing".
* See also: ibus_config_set_value().
*
* Returns: A #GVariant or %NULL. Free with g_variant_unref().
*/
GVariant *ibus_config_get_value (IBusConfig *config,
const gchar *section,
const gchar *name);
/**
* ibus_config_get_value_async:
* @config: An #IBusConfig
* @section: Section name of the configuration option.
* @name: Name of the configure option.
* @timeout_ms: The timeout in milliseconds or -1 to use the default timeout.
* @cancellable: A #GCancellable or %NULL.
* @callback: Callback function to invoke when the return value is ready.
* @user_data: The data to pass to callback.
*
* Get the value of a configuration option asynchronously.
*
* See also: ibus_config_get_value().
*/
void ibus_config_get_value_async (IBusConfig *config,
const gchar *section,
const gchar *name,
gint timeout_ms,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
/**
* ibus_config_get_value_async_finish:
* @config: A #IBusConfig.
* @result: A #GAsyncResult.
* @error: Return location for error or %NULL.
*
* Finish get value of a configuration option.
*
* Returns: A #GVariant or %NULL if error is set. Free with g_variant_unref().
*
* See also: ibus_config_get_value_async().
*/
GVariant *ibus_config_get_value_async_finish
(IBusConfig *config,
GAsyncResult *result,
GError **error);
/**
* ibus_config_get_values:
* @config: An #IBusConfig
* @section: Section name of the configuration option.
*
* Get all values in a section synchronously.
*
* Returns: A #GVariant or %NULL. Free with g_variant_unref().
*
* See also: ibus_config_set_value().
*/
GVariant *ibus_config_get_values (IBusConfig *config,
const gchar *section);
/**
* ibus_config_get_values_async:
* @config: An #IBusConfig
* @section: Section name of the configuration option.
* @timeout_ms: The timeout in milliseconds or -1 to use the default timeout.
* @cancellable: A #GCancellable or %NULL.
* @callback: Callback function to invoke when the return value is ready.
* @user_data: The data to pass to callback.
*
* Get all values in a section asynchronously.
*
* See also: ibus_config_get_values().
*/
void ibus_config_get_values_async(IBusConfig *config,
const gchar *section,
gint timeout_ms,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
/**
* ibus_config_get_values_async_finish:
* @config: A #IBusConfig.
* @result: A #GAsyncResult.
* @error: Return location for error or %NULL.
*
* Finish get values in a section.
*
* Returns: A #GVariant or %NULL if error is set. Free with g_variant_unref().
*
* See also: ibus_config_get_values_async().
*/
GVariant *ibus_config_get_values_async_finish
(IBusConfig *config,
GAsyncResult *result,
GError **error);
/**
* ibus_config_set_value:
* @config: An #IBusConfig
* @section: Section name of the configuration option.
* @name: Name of the configure option its self.
* @value: A #GVariant that holds the value. If the value is floating, the
* function takes ownership of it.
*
* Set the value of a configuration option synchronously.
*
* Returns: %TRUE if succeed; %FALSE otherwise.
*
* See also: ibus_config_get_value().
*/
gboolean ibus_config_set_value (IBusConfig *config,
const gchar *section,
const gchar *name,
GVariant *value);
/**
* ibus_config_set_value_async:
* @config: An #IBusConfig
* @section: Section name of the configuration option.
* @name: Name of the configure option.
* @value: A #GVariant that holds the value. If the value is floating, the
* function takes ownership of it.
* @timeout_ms: The timeout in milliseconds or -1 to use the default timeout.
* @cancellable: A #GCancellable or %NULL.
* @callback: Callback function to invoke when the return value is ready.
* @user_data: The data to pass to callback.
*
* Set the value of a configuration option asynchronously.
*
* See also: ibus_config_set_value().
*/
void ibus_config_set_value_async (IBusConfig *config,
const gchar *section,
const gchar *name,
GVariant *value,
gint timeout_ms,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
/**
* ibus_config_set_value_async_finish:
* @config: A #IBusConfig.
* @result: A #GAsyncResult.
* @error: Return location for error or %NULL.
*
* Finish set value of a configuration option.
*
* Returns: %TRUE or %FALSE if error is set.
*
* See also: ibus_config_set_value_async().
*/
gboolean ibus_config_set_value_async_finish
(IBusConfig *config,
GAsyncResult *result,
GError **error);
/**
* ibus_config_unset:
* @config: An #IBusConfig
* @section: Section name of the configuration option.
* @name: Name of the configure option its self.
*
* Remove an entry of a configuration option.
*
* Returns: %TRUE if succeed; %FALSE otherwise.
*
* See also: ibus_config_get_value().
*/
gboolean ibus_config_unset (IBusConfig *config,
const gchar *section,
const gchar *name);
/* FIXME add an asynchronous version of unset */
/**
* ibus_config_watch:
* @config: An #IBusConfig
* @section: (allow-none): Section name of the configuration option.
* @name: (allow-none): Name of the configure option its self.
*
* Subscribe to the configuration option change notification.
*
* Until this function is called, every change will be notified to the
* client through #IBusConfig::value-changed signal. Clients should
* call ibus_config_watch() with the sections they are interested in,
* to reduce the number of D-Bus messages.
*
* Returns: %TRUE if succeed; %FALSE otherwise.
*
* See also: ibus_config_unwatch().
*/
gboolean ibus_config_watch (IBusConfig *config,
const gchar *section,
const gchar *name);
/* FIXME add an asynchronous version of watch */
/**
* ibus_config_unwatch:
* @config: An #IBusConfig
* @section: (allow-none): Section name of the configuration option.
* @name: (allow-none): Name of the configure option its self.
*
* Unsubscribe from the configuration option change notification.
*
* Returns: %TRUE if succeed; %FALSE otherwise.
*
* See also: ibus_config_watch.
*/
gboolean ibus_config_unwatch (IBusConfig *config,
const gchar *section,
const gchar *name);
/* FIXME add an asynchronous version of unwatch */
G_END_DECLS
#endif