src/ibusproxy.h

   1 /* vim:set et sts=4: */
   2 /* ibus - The Input Bus
   3  * Copyright (C) 2008-2010 Peng Huang <shawn.p.huang@gmail.com>
   4  * Copyright (C) 2008-2010 Red Hat, Inc.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21 /**
  22  * SECTION: ibusproxy
  23  * @short_description: Base proxy object.
  24  * @stability: Stable
  25  *
  26  * An IBusProxy is the base of all proxy objects,
  27  * which communicate the corresponding #IBusServices on the other end of IBusConnection.
  28  * For example, IBus clients (such as editors, web browsers) invoke the proxy object,
  29  * IBusInputContext to communicate with the InputContext service of the ibus-daemon.
  30  *
  31  * Almost all services have corresponding proxies, except very simple services.
  32  */
  33 #ifndef __IBUS_PROXY_H_
  34 #define __IBUS_PROXY_H_
  35
  36 #include "ibusobject.h"
  37 #include "ibusconnection.h"
  38 #include "ibusmessage.h"
  39
  40 /*
  41  * Type macros.
  42  */
  43
  44 /* define GOBJECT macros */
  45 #define IBUS_TYPE_PROXY             \
  46     (ibus_proxy_get_type ())
  47 #define IBUS_PROXY(obj)             \
  48     (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_PROXY, IBusProxy))
  49 #define IBUS_PROXY_CLASS(klass)     \
  50     (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_PROXY, IBusProxyClass))
  51 #define IBUS_IS_PROXY(obj)          \
  52     (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_PROXY))
  53 #define IBUS_IS_PROXY_CLASS(klass)  \
  54     (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_PROXY))
  55 #define IBUS_PROXY_GET_CLASS(obj)   \
  56     (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_PROXY, IBusProxyClass))
  57
  58 G_BEGIN_DECLS
  59
  60 typedef struct _IBusProxy IBusProxy;
  61 typedef struct _IBusProxyClass IBusProxyClass;
  62
  63 /**
  64  * IBusProxy:
  65  *
  66  * An opaque data type representing an IBusProxy.
  67  */
  68 struct _IBusProxy {
  69     IBusObject parent;
  70     /* instance members */
  71 };
  72
  73 struct _IBusProxyClass {
  74     IBusObjectClass parent;
  75
  76     /* class members */
  77     gboolean    (* ibus_signal)     (IBusProxy      *proxy,
  78                                      IBusMessage    *message);
  79     /*< private >*/
  80     /* padding */
  81     gpointer pdummy[7];
  82 };
  83
  84 GType            ibus_proxy_get_type        (void);
  85
  86 /**
  87  * ibus_proxy_new:
  88  * @name: The service name of proxy object.
  89  * @path: The path of proxy object.
  90  * @connection: An IBusConnection.
  91  * @returns: A newly allocated IBusProxy instance.
  92  *
  93  * New an IBusProxy instance.
  94  * Property IBusProxy:name is set as @name, and
  95  * IBusProxy:path is set as @path.
  96  */
  97 IBusProxy       *ibus_proxy_new             (const gchar        *name,
  98                                              const gchar        *path,
  99                                              IBusConnection     *connection);
 100
 101 /**
 102  * ibus_proxy_send:
 103  * @proxy: An IBusProxy.
 104  * @message: The IBusMessage to be sent.
 105  * @returns: TRUE if succeed; FALSE otherwise.
 106  *
 107  * Send an #IBusMessage to the corresponding service.
 108  *
 109  * @see_also ibus_proxy_call(), ibus_proxy_send_with_reply(), ibus_proxy_send_with_reply_and_block().
 110  */
 111 gboolean         ibus_proxy_send            (IBusProxy          *proxy,
 112                                              IBusMessage        *message);
 113
 114 /**
 115  * ibus_proxy_call:
 116  * @proxy: An IBusProxy.
 117  * @method: The method to be called.
 118  * @first_arg_type: Type of first argument.
 119  * @...: Rest of arguments, NULL to mark the end.
 120  * @returns: TRUE if succeed; FALSE otherwise.
 121  *
 122  * Call a method of the corresponding service.
 123  *
 124  * @see_also ibus_proxy_send(), ibus_proxy_call_with_reply(), ibus_proxy_call_with_reply_and_block().
 125  */
 126 gboolean         ibus_proxy_call            (IBusProxy          *proxy,
 127                                              const gchar        *method,
 128                                              GType               first_arg_type,
 129                                              ...);
 130
 131 /**
 132  * ibus_proxy_call_with_reply:
 133  * @proxy: An IBusProxy.
 134  * @method: The method to be called.
 135  * @pending: Return location of a IBusPendingCall object, or NULL if connection is disconnected.
 136  * @timeout_milliseconds: Time out in milliseconds.
 137  * @error: Returned error is stored here; NULL to ignore error.
 138  * @first_arg_type: Type of first argument.
 139  * @...: Rest of arguments, NULL to mark the end.
 140  * @returns: TRUE if succeed; FALSE otherwise.
 141  *
 142  * Call a method of the corresponding service, and returns an IBusPendingCall used to receive a reply to the message.
 143  * This function calls ibus_connection_send_with_reply() to do the actual sending.
 144  *
 145  * @see_also: ibus_connection_send_with_reply(), ibus_proxy_call(),
 146  * ibus_proxy_send_with_reply(), ibus_proxy_call_with_reply_and_block().
 147  */
 148 gboolean         ibus_proxy_call_with_reply (IBusProxy          *proxy,
 149                                              const gchar        *method,
 150                                              IBusPendingCall   **pending,
 151                                              gint                timeout_milliseconds,
 152                                              IBusError         **error,
 153                                              GType              first_arg_type,
 154                                              ...);
 155
 156 /**
 157  * ibus_proxy_call_with_reply_and_block:
 158  * @proxy: An IBusProxy.
 159  * @method: The method to be called.
 160  * @timeout_milliseconds: Time out in milliseconds.
 161  * @error: Returned error is stored here; NULL to ignore error.
 162  * @first_arg_type: Type of first argument.
 163  * @...: Rest of arguments, NULL to mark the end.
 164  * @returns: An IBusMessage that is the reply or NULL with an error code if the function fails.
 165  *
 166  * Call a method of the corresponding service and blocks a certain time period while waiting for
 167  * an IBusMessage as reply.
 168  * If the IBusMessage is not NULL, it calls ibus_connection_send_with_reply_and_block() to do the
 169  * actual sending.
 170  *
 171  * @see_also: ibus_connection_send_with_reply_and_block(), ibus_proxy_call(),
 172  * ibus_proxy_send_with_reply(), ibus_proxy_call_with_reply_and_block().
 173  */
 174 IBusMessage     *ibus_proxy_call_with_reply_and_block
 175                                             (IBusProxy          *proxy,
 176                                              const gchar        *method,
 177                                              gint                timeout_milliseconds,
 178                                              IBusError         **error,
 179                                              GType               first_arg_type,
 180                                             ...);
 181
 182 /**
 183  * ibus_proxy_send_with_reply:
 184  * @proxy: An IBusProxy.
 185  * @message: The IBusMessage to be sent.
 186  * @pending: Return location of a IBusPendingCall object, or NULL if connection is disconnected.
 187  * @timeout_milliseconds: Time out in milliseconds.
 188  * @returns: TRUE if succeed; FALSE otherwise.
 189  *
 190  * Send an IBusMessage to the corresponding service and returns
 191  * an IBusPendingCall used to receive a reply to the message.
 192  * This function calls ibus_connection_send_with_reply() to do the actual sending.
 193  *
 194  * @see_also: ibus_connection_send_with_reply(), ibus_proxy_send(),
 195  * ibus_proxy_call_with_reply(), ibus_proxy_send_with_reply_and_block().
 196  */
 197 gboolean         ibus_proxy_send_with_reply (IBusProxy          *proxy,
 198                                              IBusMessage        *message,
 199                                              IBusPendingCall   **pending,
 200                                              gint                timeout_milliseconds);
 201
 202 /**
 203  * ibus_proxy_send_with_reply_and_block:
 204  * @proxy: An IBusProxy.
 205  * @message: The IBusMessage to be sent.
 206  * @returns: An IBusMessage that is the reply or NULL with an error code if the function fails.
 207  *
 208  * Send an IBusMessage to the corresponding service and blocks a certain time period while waiting for
 209  * an IBusMessage as reply.
 210  * If the IBusMessage is not NULL, it calls ibus_connection_send_with_reply_and_block() to do the
 211  * actual sending.
 212  *
 213  * @see_also: ibus_connection_send_with_reply_and_block(), ibus_proxy_send(), ibus_proxy_send_with_reply(),
 214  * ibus_proxy_call_with_reply_and_block().
 215  */
 216 IBusMessage     *ibus_proxy_send_with_reply_and_block
 217                                             (IBusProxy          *proxy,
 218                                              IBusMessage        *message);
 219
 220 /**
 221  * ibus_proxy_handle_signal:
 222  * @proxy: An IBusProxy.
 223  * @message: The IBusMessage to be sent.
 224  * @returns: TRUE if succeed; FALSE otherwise.
 225  *
 226  * Handle a signal by emitting IBusProxy::ibus-signal.
 227  *
 228  * If signal name is <constant>NameOwnerChanged</constant>
 229  * and the service name is identical to the old name, then
 230  * @proxy will be destroyed by ibus_object_destroy () and FALSE is returned.
 231  * Otherwise TRUE is returned.
 232  *
 233  * Note that if the path of of message is not identical to the IBusProxy:path
 234  * this function will not emit IBusProxy::ibus-signal.
 235  *
 236  */
 237 gboolean         ibus_proxy_handle_signal   (IBusProxy          *proxy,
 238                                              IBusMessage        *message);
 239
 240 /**
 241  * ibus_proxy_get_name:
 242  * @proxy: An IBusProxy.
 243  * @returns: The service name of the proxy object.
 244  *
 245  * Get the service name of a proxy object.
 246  */
 247 const gchar     *ibus_proxy_get_name        (IBusProxy          *proxy);
 248
 249 /**
 250  * ibus_proxy_get_unique_name:
 251  * @proxy: An IBusProxy.
 252  * @returns: The service name of the proxy object.
 253  *
 254  * Get the unique name of the proxy object.
 255  */
 256 const gchar     *ibus_proxy_get_unique_name (IBusProxy          *proxy);
 257
 258 /**
 259  * ibus_proxy_get_path:
 260  * @proxy: An IBusProxy.
 261  * @returns: The path of proxy object.
 262  *
 263  * Get the path of a proxy object.
 264  */
 265 const gchar     *ibus_proxy_get_path        (IBusProxy          *proxy);
 266
 267 /**
 268  * ibus_proxy_get_interface:
 269  * @proxy: An IBusProxy.
 270  * @returns: The service name of the proxy object.
 271  *
 272  * Get interface of a proxy object.
 273  */
 274 const gchar     *ibus_proxy_get_interface   (IBusProxy          *proxy);
 275
 276 /**
 277  * ibus_proxy_get_connection:
 278  * @proxy: An IBusProxy.
 279  * @returns: (transfer none): The connection of the proxy object.
 280  *
 281  * Get the connection of a proxy object.
 282  */
 283 IBusConnection  *ibus_proxy_get_connection  (IBusProxy          *proxy);
 284
 285 G_END_DECLS
 286 #endif
 287