src/ibusshare.h

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