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_SHARE_H_
28#define __IBUS_SHARE_H_
29
30/**
31 * SECTION: ibusshare
32 * @short_description: Shared utility functions and definition.
33 * @stability: Stable
34 *
35 * This file defines some utility functions and definition
36 * which are shared among ibus component and services.
37 */
38
39#include <glib.h>
40
41#ifdef IBUS_DISABLE_DEPRECATION_WARNINGS
42#define IBUS_DEPRECATED
43#else
44#define IBUS_DEPRECATED G_DEPRECATED
45#endif
46
47/**
48 * IBUS_SERVICE_IBUS:
49 *
50 * Address of IBus service.
51 */
52#define IBUS_SERVICE_IBUS "org.freedesktop.IBus"
53
54/**
55 * IBUS_SERVICE_PORTAL:
56 *
57 * Address of IBus portalservice.
58 */
59#define IBUS_SERVICE_PORTAL "org.freedesktop.portal.IBus"
60
61/**
62 * IBUS_SERVICE_PANEL:
63 *
64 * Address of IBus panel service.
65 */
66#define IBUS_SERVICE_PANEL "org.freedesktop.IBus.Panel"
67
68/**
69 * IBUS_SERVICE_CONFIG:
70 *
71 * Address of IBus config service.
72 */
73#define IBUS_SERVICE_CONFIG "org.freedesktop.IBus.Config"
74
75/**
76 * IBUS_SERVICE_NOTIFICATIONS:
77 *
78 * Address of IBus notification service.
79 */
80#define IBUS_SERVICE_NOTIFICATIONS "org.freedesktop.IBus.Notifications"
81
82/**
83 * IBUS_PATH_IBUS:
84 *
85 * D-Bus path for IBus
86 */
87#define IBUS_PATH_IBUS "/org/freedesktop/IBus"
88
89/**
90 * IBUS_PATH_FACTORY:
91 *
92 * D-Bus path for IBus factory.
93 */
94#define IBUS_PATH_FACTORY "/org/freedesktop/IBus/Factory"
95
96/**
97 * IBUS_PATH_PANEL:
98 *
99 * D-Bus path for IBus panel.
100 */
101#define IBUS_PATH_PANEL "/org/freedesktop/IBus/Panel"
102
103/**
104 * IBUS_PATH_CONFIG:
105 *
106 * D-Bus path for IBus config.
107 */
108#define IBUS_PATH_CONFIG "/org/freedesktop/IBus/Config"
109
110/**
111 * IBUS_PATH_NOTIFICATIONS:
112 *
113 * D-Bus path for IBus notifications.
114 */
115#define IBUS_PATH_NOTIFICATIONS "/org/freedesktop/IBus/Notifications"
116
117/**
118 * IBUS_PATH_INPUT_CONTEXT:
119 *
120 * Template of D-Bus path for IBus input context.
121 */
122#define IBUS_PATH_INPUT_CONTEXT "/org/freedesktop/IBus/InputContext_%d"
123
124/**
125 * IBUS_INTERFACE_IBUS:
126 *
127 * D-Bus interface for IBus.
128 */
129#define IBUS_INTERFACE_IBUS "org.freedesktop.IBus"
130
131/**
132 * IBUS_INTERFACE_PORTAL:
133 *
134 * D-Bus interface for IBus portal.
135 */
136#define IBUS_INTERFACE_PORTAL "org.freedesktop.IBus.Portal"
137
138/**
139 * IBUS_INTERFACE_INPUT_CONTEXT:
140 *
141 * D-Bus interface for IBus input context.
142 */
143#define IBUS_INTERFACE_INPUT_CONTEXT \
144 "org.freedesktop.IBus.InputContext"
145
146/**
147 * IBUS_INTERFACE_FACTORY:
148 *
149 * D-Bus interface for IBus factory.
150 */
151#define IBUS_INTERFACE_FACTORY "org.freedesktop.IBus.Factory"
152
153/**
154 * IBUS_INTERFACE_ENGINE:
155 *
156 * D-Bus interface for IBus engine.
157 */
158#define IBUS_INTERFACE_ENGINE "org.freedesktop.IBus.Engine"
159
160/**
161 * IBUS_INTERFACE_PANEL:
162 *
163 * D-Bus interface for IBus panel.
164 */
165#define IBUS_INTERFACE_PANEL "org.freedesktop.IBus.Panel"
166
167/**
168 * IBUS_INTERFACE_CONFIG:
169 *
170 * D-Bus interface for IBus config.
171 */
172#define IBUS_INTERFACE_CONFIG "org.freedesktop.IBus.Config"
173
174/**
175 * IBUS_INTERFACE_NOTIFICATIONS:
176 *
177 * D-Bus interface for IBus notifications.
178 */
179#define IBUS_INTERFACE_NOTIFICATIONS "org.freedesktop.IBus.Notifications"
180
181G_BEGIN_DECLS
182
183/**
184 * ibus_get_local_machine_id:
185 *
186 * Obtains the machine UUID of the machine this process is running on.
187 *
188 * Returns: A newly allocated string that shows the UUID of the machine.
189 */
190const gchar *ibus_get_local_machine_id
191 (void);
192
193/**
194 * ibus_set_display:
195 * @display: Display address, as in DISPLAY environment for X.
196 *
197 * Set the display address.
198 */
199void ibus_set_display (const gchar *display);
200
201/**
202 * ibus_get_address:
203 *
204 * Return the D-Bus address of IBus.
205 * It will find the address from following source:
206 * <orderedlist>
207 * <listitem><para>Environment variable IBUS_ADDRESS</para></listitem>
208 * <listitem><para>Socket file under ~/.config/ibus/bus/</para></listitem>
209 * </orderedlist>
210 *
211 * Returns: D-Bus address of IBus. %NULL for not found.
212 *
213 * See also: ibus_write_address().
214 */
215const gchar *ibus_get_address (void);
216
217/**
218 * ibus_write_address:
219 * @address: D-Bus address of IBus.
220 *
221 * Write D-Bus address to socket file.
222 *
223 * See also: ibus_get_address().
224 */
225void ibus_write_address (const gchar *address);
226
227/**
228 * ibus_get_user_name:
229 *
230 * Get the current user name.
231 * It is determined by:
232 * <orderedlist>
233 * <listitem><para>getlogin()</para></listitem>
234 * <listitem><para>Environment variable SUDO_USER</para></listitem>
235 * <listitem><para>Environment variable USERHELPER_UID</para></listitem>
236 * <listitem><para>Environment variable USERNAME</para></listitem>
237 * <listitem><para>Environment variable LOGNAME</para></listitem>
238 * <listitem><para>Environment variable USER</para></listitem>
239 * <listitem><para>Environment variable LNAME</para></listitem>
240 * </orderedlist>
241 *
242 * Returns: A newly allocated string that stores current user name.
243 */
244const gchar *ibus_get_user_name (void);
245
246/**
247 * ibus_get_daemon_uid:
248 *
249 * Get UID of ibus-daemon.
250 *
251 * Returns: UID of ibus-daemon; or 0 if UID is not available.
252 *
253 * Deprecated: This function has been deprecated and should
254 * not be used in newly written code.
255 */
256glong ibus_get_daemon_uid (void) G_GNUC_DEPRECATED;
257
258/**
259 * ibus_get_socket_path:
260 *
261 * Get the path of socket file.
262 *
263 * Returns: A newly allocated string that stores the path of socket file.
264 */
265const gchar *ibus_get_socket_path (void);
266
267/**
268 * ibus_get_timeout:
269 *
270 * Get the GDBus timeout in milliseconds. The timeout is for clients (e.g.
271 * im-ibus.so), not for ibus-daemon.
272 * Note that the timeout for ibus-daemon could be set by --timeout command
273 * line option of the daemon.
274 *
275 * Returns: A GDBus timeout in milliseconds. -1 when default timeout for
276 * GDBus should be used.
277 */
278gint ibus_get_timeout (void);
279
280/**
281 * ibus_free_strv:
282 * @strv: List of strings.
283 *
284 * Free a list of strings.
285 * Deprecated: This function has been deprecated and should
286 * not be used in newly written code.
287 */
288void ibus_free_strv (gchar **strv)
289 G_GNUC_DEPRECATED;
290
291/**
292 * ibus_key_event_to_string:
293 * @keyval: Key symbol.
294 * @modifiers: Modifiers such as Ctrl or Shift.
295 *
296 * Return the name of a key symbol and modifiers.
297 *
298 * For example, if press ctrl, shift, and enter, then this function returns:
299 * Shift+Control+enter.
300 *
301 * Returns: The name of a key symbol and modifier.
302 */
303const gchar *ibus_key_event_to_string
304 (guint keyval,
305 guint modifiers);
306
307/**
308 * ibus_key_event_from_string:
309 * @string: Key event string.
310 * @keyval: Variable that hold key symbol result.
311 * @modifiers: Variable that hold modifiers result.
312 *
313 * Parse key event string and return key symbol and modifiers.
314 *
315 * Returns: %TRUE for succeed; %FALSE if failed.
316 */
317gboolean ibus_key_event_from_string
318 (const gchar *string,
319 guint *keyval,
320 guint *modifiers);
321
322/**
323 * ibus_init:
324 *
325 * Initialize the ibus types.
326 */
327void ibus_init (void);
328
329/**
330 * ibus_main:
331 *
332 * Runs an IBus main loop until ibus_quit() is called in the loop.
333 *
334 * See also: ibus_quit().
335 */
336void ibus_main (void);
337
338/**
339 * ibus_quit:
340 *
341 * Stops an IBus from running.
342 *
343 * Any calls to ibus_quit() for the loop will return.
344 * See also: ibus_main().
345 */
346void ibus_quit (void);
347
348/**
349 * ibus_set_log_handler:
350 * @verbose: TRUE for verbose logging.
351 *
352 * Sets GLIB's log handler to ours. Our log handler adds time info
353 * including hour, minute, second, and microsecond, like:
354 *
355 * (ibus-daemon:7088): IBUS-DEBUG: 18:06:45.822819: ibus-daemon started
356 *
357 * If @verbose is %TRUE, all levels of messages will be logged. Otherwise,
358 * DEBUG and WARNING messages will be ignored. The function is used in
359 * ibus-daemon, but can be useful for IBus client programs as well for
360 * debugging. It's totally fine for not calling this function. If you
361 * don't set a custom GLIB log handler, the default GLIB log handler will
362 * be used.
363 */
364void ibus_set_log_handler (gboolean verbose);
365
366/**
367 * ibus_unset_log_handler:
368 *
369 * Remove the log handler which is set by ibus_set_log_handler.
370 */
371void ibus_unset_log_handler (void);
372
373G_END_DECLS
374#endif
375