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 <dbus/dbus.h>
  37 #include "ibusobject.h"
  38 #include "ibusconnection.h"
  39 #include "ibusmessage.h"
  40
  41 /*
  42  * Type macros.
  43  */
  44
  45 /* define GOBJECT macros */
  46 #define IBUS_TYPE_PROXY             \
  47     (ibus_proxy_get_type ())
  48 #define IBUS_PROXY(obj)             \
  49     (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_PROXY, IBusProxy))
  50 #define IBUS_PROXY_CLASS(klass)     \
  51     (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_PROXY, IBusProxyClass))
  52 #define IBUS_IS_PROXY(obj)          \
  53     (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_PROXY))
  54 #define IBUS_IS_PROXY_CLASS(klass)  \
  55     (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_PROXY))
  56 #define IBUS_PROXY_GET_CLASS(obj)   \
  57     (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_PROXY, IBusProxyClass))
  58
  59 G_BEGIN_DECLS
  60
  61 typedef struct _IBusProxy IBusProxy;
  62 typedef struct _IBusProxyClass IBusProxyClass;
  63
  64 /**
  65  * IBusProxy:
  66  *
  67  * An opaque data type representing an IBusProxy.
  68  */
  69 struct _IBusProxy {
  70     IBusObject parent;
  71     /* instance members */
  72 };
  73
  74 struct _IBusProxyClass {
  75     IBusObjectClass parent;
  76
  77     /* class members */
  78     gboolean    (* ibus_signal)     (IBusProxy   *proxy,
  79                                      IBusMessage      *message);
  80     /*< private >*/
  81     /* padding */
  82     gpointer pdummy[7];
  83 };
  84
  85 GType            ibus_proxy_get_type        (void);
  86
  87 /**
  88  * ibus_proxy_new:
  89  * @name: The service name of proxy object.
  90  * @path: The path of proxy object.
  91  * @connection: An IBusConnection.
  92  * @returns: A newly allocated IBusProxy instance.
  93  *
  94  * New an IBusProxy instance.
  95  * Property IBusProxy:name is set as @name, and
  96  * IBusProxy:path is set as @path.
  97  */
  98 IBusProxy       *ibus_proxy_new             (const gchar        *name,
  99                                              const gchar        *path,
 100                                              IBusConnection     *connection);
 101
 102 /**
 103  * ibus_proxy_send:
 104  * @proxy: An IBusProxy.
 105  * @message: The IBusMessage to be sent.
 106  * @returns: TRUE if succeed; FALSE otherwise.
 107  *
 108  * Send an #IBusMessage to the corresponding service.
 109  *
 110  * @see_also ibus_proxy_call(), ibus_proxy_send_with_reply(), ibus_proxy_send_with_reply_and_block().
 111  */
 112 gboolean         ibus_proxy_send            (IBusProxy          *proxy,
 113                                              IBusMessage        *message);
 114
 115 /**
 116  * ibus_proxy_call:
 117  * @proxy: An IBusProxy.
 118  * @method: The method to be called.
 119  * @first_arg_type: Type of first argument.
 120  * @...: Rest of arguments, NULL to mark the end.
 121  * @returns: TRUE if succeed; FALSE otherwise.
 122  *
 123  * Call a method of the corresponding service.
 124  *
 125  * @see_also ibus_proxy_send(), ibus_proxy_call_with_reply(), ibus_proxy_call_with_reply_and_block().
 126  */
 127 gboolean         ibus_proxy_call            (IBusProxy          *proxy,
 128                                              const gchar        *method,
 129                                              GType               first_arg_type,
 130                                              ...);
 131
 132 /**
 133  * ibus_proxy_call_with_reply:
 134  * @proxy: An IBusProxy.
 135  * @method: The method to be called.
 136  * @pending: Return location of a IBusPendingCall object, or NULL if connection is disconnected.
 137  * @timeout_milliseconds: Time out in milliseconds.
 138  * @error: Returned error is stored here; NULL to ignore error.
 139  * @first_arg_type: Type of first argument.
 140  * @...: Rest of arguments, NULL to mark the end.
 141  * @returns: TRUE if succeed; FALSE otherwise.
 142  *
 143  * Call a method of the corresponding service, and returns an IBusPendingCall used to receive a reply to the message.
 144  * This function calls ibus_connection_send_with_reply() to do the actual sending.
 145  *
 146  * @see_also: ibus_connection_send_with_reply(),
 147  * @see_also: ibus_proxy_call(), ibus_proxy_send_with_reply(), ibus_proxy_call_with_reply_and_block().
 148  */
 149 gboolean         ibus_proxy_call_with_reply (IBusProxy          *proxy,
 150                                              const gchar        *method,
 151                                              IBusPendingCall   **pending,
 152                                              gint                timeout_milliseconds,
 153                                              IBusError         **error,
 154                                              GType              first_arg_type,
 155                                              ...);
 156
 157 /**
 158  * ibus_proxy_call_with_reply_and_block:
 159  * @proxy: An IBusProxy.
 160  * @method: The method to be called.
 161  * @timeout_milliseconds: Time out in milliseconds.
 162  * @error: Returned error is stored here; NULL to ignore error.
 163  * @first_arg_type: Type of first argument.
 164  * @...: Rest of arguments, NULL to mark the end.
 165  * @returns: An IBusMessage that is the reply or NULL with an error code if the function fails.
 166  *
 167  * Call a method of the corresponding service and blocks a certain time period while waiting for
 168  * an IBusMessage as reply.
 169  * If the IBusMessage is not NULL, it calls ibus_connection_send_with_reply_and_block() to do the
 170  * actual sending.
 171  *
 172  * @see_also: ibus_connection_send_with_reply_and_block(),
 173  * @see_also: ibus_proxy_call(), ibus_proxy_send_with_reply(), ibus_proxy_call_with_reply_and_block().
 174  */
 175 IBusMessage     *ibus_proxy_call_with_reply_and_block
 176                                             (IBusProxy          *proxy,
 177                                              const gchar        *method,
 178                                              gint                timeout_milliseconds,
 179                                              IBusError         **error,
 180                                              GType               first_arg_type,
 181                                             ...);
 182
 183 /**
 184  * ibus_proxy_send_with_reply:
 185  * @proxy: An IBusProxy.
 186  * @message: The IBusMessage to be sent.
 187  * @pending: Return location of a IBusPendingCall object, or NULL if connection is disconnected.
 188  * @timeout_milliseconds: Time out in milliseconds.
 189  * @returns: TRUE if succeed; FALSE otherwise.
 190  *
 191  * Send an IBusMessage to the corresponding service and returns
 192  * an IBusPendingCall used to receive a reply to the message.
 193  * This function calls ibus_connection_send_with_reply() to do the actual sending.
 194  *
 195  * @see_also: ibus_connection_send_with_reply(),
 196  * @see_also: ibus_proxy_send(), ibus_proxy_call_with_reply(), ibus_proxy_send_with_reply_and_block().
 197  */
 198 gboolean         ibus_proxy_send_with_reply (IBusProxy          *proxy,
 199                                              IBusMessage        *message,
 200                                              IBusPendingCall   **pending,
 201                                              gint                timeout_milliseconds);
 202
 203 /**
 204  * ibus_proxy_send_with_reply_and_block:
 205  * @proxy: An IBusProxy.
 206  * @message: The IBusMessage to be sent.
 207  * @returns: An IBusMessage that is the reply or NULL with an error code if the function fails.
 208  *
 209  * Send an IBusMessage to the corresponding service and blocks a certain time period while waiting for
 210  * an IBusMessage as reply.
 211  * If the IBusMessage is not NULL, it calls ibus_connection_send_with_reply_and_block() to do the
 212  * actual sending.
 213  *
 214  * @see_also: ibus_connection_send_with_reply_and_block(),
 215  * @see_also: ibus_proxy_send(), ibus_proxy_send_with_reply(), ibus_proxy_call_with_reply_and_block().
 216  */
 217 IBusMessage     *ibus_proxy_send_with_reply_and_block
 218                                             (IBusProxy          *proxy,
 219                                              IBusMessage        *message);
 220
 221 /**
 222  * ibus_proxy_handle_signal:
 223  * @proxy: An IBusProxy.
 224  * @message: The IBusMessage to be sent.
 225  * @returns: TRUE if succeed; FALSE otherwise.
 226  *
 227  * Handle a signal by emitting IBusProxy::ibus-signal.
 228  *
 229  * If signal name is <constant>NameOwnerChanged</constant>
 230  * and the service name is identical to the old name, then
 231  * @proxy will be destroyed by ibus_object_destroy () and FALSE is returned.
 232  * Otherwise TRUE is returned.
 233  *
 234  * Note that if the path of of message is not identical to the IBusProxy:path
 235  * this function will not emit IBusProxy::ibus-signal.
 236  *
 237  */
 238 gboolean         ibus_proxy_handle_signal   (IBusProxy          *proxy,
 239                                              IBusMessage        *message);
 240
 241 /**
 242  * ibus_proxy_get_name:
 243  * @proxy: An IBusProxy.
 244  * @returns: The service name of the proxy object.
 245  *
 246  * Get the service name of a proxy object.
 247  */
 248 const gchar     *ibus_proxy_get_name        (IBusProxy          *proxy);
 249
 250 /**
 251  * ibus_proxy_get_unique_name:
 252  * @proxy: An IBusProxy.
 253  * @returns: The service name of the proxy object.
 254  *
 255  * Get the unique name of the proxy object.
 256  */
 257 const gchar     *ibus_proxy_get_unique_name (IBusProxy          *proxy);
 258
 259 /**
 260  * ibus_proxy_get_path:
 261  * @proxy: An IBusProxy.
 262  * @returns: The path of proxy object.
 263  *
 264  * Get the path of a proxy object.
 265  */
 266 const gchar     *ibus_proxy_get_path        (IBusProxy          *proxy);
 267
 268 /**
 269  * ibus_proxy_get_interface:
 270  * @proxy: An IBusProxy.
 271  * @returns: The service name of the proxy object.
 272  *
 273  * Get interface of a proxy object.
 274  */
 275 const gchar     *ibus_proxy_get_interface   (IBusProxy          *proxy);
 276
 277 /**
 278  * ibus_proxy_get_connection:
 279  * @proxy: An IBusProxy.
 280  * @returns: The connection of the proxy object.
 281  *
 282  * Get the connection of a proxy object.
 283  */
 284 IBusConnection  *ibus_proxy_get_connection  (IBusProxy          *proxy);
 285
 286 G_END_DECLS
 287 #endif
 288