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