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-2010 Peng Huang <shawn.p.huang@gmail.com>
5 * Copyright (C) 2008-2010 Red Hat, Inc.
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 of the License, or (at your option) any later version.
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.
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
23 #if !defined (__IBUS_H_INSIDE__) && !defined (IBUS_COMPILATION)
24 #error "Only <ibus.h> can be included directly"
29 * @short_description: Shared utility functions and definition.
32 * This file defines some utility functions and definition
33 * which are shared among ibus component and services.
36 #ifndef __IBUS_SHARE_H_
37 #define __IBUS_SHARE_H_
44 * Address of IBus service.
46 #define IBUS_SERVICE_IBUS "org.freedesktop.IBus"
51 * Address of IBus panel service.
53 #define IBUS_SERVICE_PANEL "org.freedesktop.IBus.Panel"
56 * IBUS_SERVICE_CONFIG:
58 * Address of IBus config service.
60 #define IBUS_SERVICE_CONFIG "org.freedesktop.IBus.Config"
63 * IBUS_SERVICE_NOTIFICATIONS:
65 * Address of IBus notification service.
67 #define IBUS_SERVICE_NOTIFICATIONS "org.freedesktop.IBus.Notifications"
74 #define IBUS_PATH_IBUS "/org/freedesktop/IBus"
79 * D-Bus path for IBus factory.
81 #define IBUS_PATH_FACTORY "/org/freedesktop/IBus/Factory"
86 * D-Bus path for IBus panel.
88 #define IBUS_PATH_PANEL "/org/freedesktop/IBus/Panel"
93 * D-Bus path for IBus config.
95 #define IBUS_PATH_CONFIG "/org/freedesktop/IBus/Config"
98 * IBUS_PATH_NOTIFICATIONS:
100 * D-Bus path for IBus notifications.
102 #define IBUS_PATH_NOTIFICATIONS "/org/freedesktop/IBus/Notifications"
105 * IBUS_PATH_INPUT_CONTEXT:
107 * Template of D-Bus path for IBus input context.
109 #define IBUS_PATH_INPUT_CONTEXT "/org/freedesktop/IBus/InputContext_%d"
112 * IBUS_INTERFACE_IBUS:
114 * D-Bus interface for IBus.
116 #define IBUS_INTERFACE_IBUS "org.freedesktop.IBus"
119 * IBUS_INTERFACE_INPUT_CONTEXT:
121 * D-Bus interface for IBus input context.
123 #define IBUS_INTERFACE_INPUT_CONTEXT \
124 "org.freedesktop.IBus.InputContext"
127 * IBUS_INTERFACE_FACTORY:
129 * D-Bus interface for IBus factory.
131 #define IBUS_INTERFACE_FACTORY "org.freedesktop.IBus.Factory"
134 * IBUS_INTERFACE_ENGINE:
136 * D-Bus interface for IBus engine.
138 #define IBUS_INTERFACE_ENGINE "org.freedesktop.IBus.Engine"
141 * IBUS_INTERFACE_PANEL:
143 * D-Bus interface for IBus panel.
145 #define IBUS_INTERFACE_PANEL "org.freedesktop.IBus.Panel"
148 * IBUS_INTERFACE_CONFIG:
150 * D-Bus interface for IBus config.
152 #define IBUS_INTERFACE_CONFIG "org.freedesktop.IBus.Config"
155 * IBUS_INTERFACE_NOTIFICATIONS:
157 * D-Bus interface for IBus notifications.
159 #define IBUS_INTERFACE_NOTIFICATIONS "org.freedesktop.IBus.Notifications"
164 * ibus_get_local_machine_id:
165 * @returns: A newly allocated string that shows the UUID of the machine.
167 * Obtains the machine UUID of the machine this process is running on.
169 const gchar *ibus_get_local_machine_id
174 * @display: Display address, as in DISPLAY environment for X.
176 * Set the display address.
178 void ibus_set_display (const gchar *display);
182 * @returns: D-Bus address of IBus. %NULL for not found.
184 * Return the D-Bus address of IBus.
185 * It will find the address from following source:
187 * <listitem><para>Environment variable IBUS_ADDRESS</para></listitem>
188 * <listitem><para>Socket file under ~/.config/ibus/bus/</para></listitem>
191 * @see_also: ibus_write_address().
193 const gchar *ibus_get_address (void);
196 * ibus_write_address:
197 * @address: D-Bus address of IBus.
199 * Write D-Bus address to socket file.
201 * @see_also: ibus_get_address().
203 void ibus_write_address (const gchar *address);
206 * ibus_get_user_name:
207 * @returns: A newly allocated string that stores current user name.
209 * Get the current user name.
210 * It is determined by:
212 * <listitem><para>getlogin()</para></listitem>
213 * <listitem><para>Environment variable SUDO_USER</para></listitem>
214 * <listitem><para>Environment variable USERHELPER_UID</para></listitem>
215 * <listitem><para>Environment variable USERNAME</para></listitem>
216 * <listitem><para>Environment variable LOGNAME</para></listitem>
217 * <listitem><para>Environment variable USER</para></listitem>
218 * <listitem><para>Environment variable LNAME</para></listitem>
221 const gchar *ibus_get_user_name (void);
224 * ibus_get_daemon_uid:
225 * @returns: UID of ibus-daemon; or 0 if UID is not available.
227 * Get UID of ibus-daemon.
229 * Deprecated: This function has been deprecated and should
230 * not be used in newly written code.
232 glong ibus_get_daemon_uid (void) G_GNUC_DEPRECATED;
235 * ibus_get_socket_path:
236 * @returns: A newly allocated string that stores the path of socket file.
238 * Get the path of socket file.
240 const gchar *ibus_get_socket_path (void);
244 * @returns: A GDBus timeout in milliseconds. -1 when default timeout for GDBus should be used.
246 * Get the GDBus timeout in milliseconds. The timeout is for clients (e.g. im-ibus.so), not for ibus-daemon.
247 * Note that the timeout for ibus-daemon could be set by --timeout command line option of the daemon.
249 gint ibus_get_timeout (void);
253 * @strv: List of strings.
255 * Free a list of strings.
256 * Deprecated: This function has been deprecated and should
257 * not be used in newly written code.
259 void ibus_free_strv (gchar **strv)
263 * ibus_key_event_to_string:
264 * @keyval: Key symbol.
265 * @modifiers: Modifiers such as Ctrl or Shift.
266 * @returns: The name of a key symbol and modifier.
268 * Return the name of a key symbol and modifiers.
270 * For example, if press ctrl, shift, and enter, then this function returns:
271 * Shift+Control+enter.
273 const gchar *ibus_key_event_to_string
278 * ibus_key_event_from_string:
279 * @string: Key event string.
280 * @keyval: Variable that hold key symbol result.
281 * @modifiers: Variable that hold modifiers result.
282 * @returns: TRUE for succeed; FALSE if failed.
284 * Parse key event string and return key symbol and modifiers.
286 gboolean ibus_key_event_from_string
287 (const gchar *string,
294 * Init the ibus types.
296 * It is actually a wrapper of g_type_init().
298 void ibus_init (void);
303 * Runs an IBus main loop until ibus_quit() is called in the loop.
305 * @see_also: ibus_quit().
307 void ibus_main (void);
312 * Stops an IBus from running.
314 * Any calls to ibus_quit() for the loop will return.
315 * @see_also: ibus_main().
317 void ibus_quit (void);
320 * ibus_set_log_handler:
321 * @verbose: TRUE for verbose logging.
323 * Sets GLIB's log handler to ours. Our log handler adds time info
324 * including hour, minute, second, and microsecond, like:
326 * (ibus-daemon:7088): IBUS-DEBUG: 18:06:45.822819: ibus-daemon started
328 * If @verbose is TRUE, all levels of messages will be logged. Otherwise,
329 * DEBUG and WARNING messages will be ignored. The function is used in
330 * ibus-daemon, but can be useful for IBus client programs as well for
331 * debugging. It's totally fine for not calling this function. If you
332 * don't set a custom GLIB log handler, the default GLIB log handler will
335 void ibus_set_log_handler (gboolean verbose);