src/ibusproxy.h

   1 /* vim:set et sts=4: */
   2 /* ibus - The Input Bus
   3  * Copyright (C) 2008-2009 Peng Huang <shawn.p.huang@gmail.com>
   4  * Copyright (C) 2008-2009 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 IBusMessagwe is not NULL,  it calls ibus_connection_send_with_reply_and_block() to do the actual sending.
 170  *
 171  * @see_also: ibus_connection_send_with_reply_and_block(),
 172  * @see_also: ibus_proxy_call(), 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(),
 195  * @see_also: ibus_proxy_send(), 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 actual sending.
 211  *
 212  * @see_also: ibus_connection_send_with_reply_and_block(),
 213  * @see_also: ibus_proxy_send(), ibus_proxy_send_with_reply(), ibus_proxy_call_with_reply_and_block().
 214  */
 215 IBusMessage     *ibus_proxy_send_with_reply_and_block
 216                                             (IBusProxy          *proxy,
 217                                              IBusMessage        *message);
 218
 219 /**
 220  * ibus_proxy_handle_signal:
 221  * @proxy: An IBusProxy.
 222  * @message: The IBusMessage to be sent.
 223  * @returns: TRUE if succeed; FALSE otherwise.
 224  *
 225  * Handle a signal by emitting IBusProxy::ibus-signal.
 226  *
 227  * If signal name is <constant>NameOwnerChanged</constant>
 228  * and the service name is identical to the old name, then
 229  * @proxy will be destroyed by ibus_object_destroy () and FALSE is returned.
 230  * Otherwise TRUE is returned.
 231  *
 232  * Note that if the path of of message is not identical to the IBusProxy:path
 233  * this function will not emit IBusProxy::ibus-signal.
 234  *
 235  */
 236 gboolean         ibus_proxy_handle_signal   (IBusProxy          *proxy,
 237                                              IBusMessage        *message);
 238
 239 /**
 240  * ibus_proxy_get_name:
 241  * @proxy: An IBusProxy.
 242  * @returns: The service name of the proxy object.
 243  *
 244  * Get the service name of a proxy object.
 245  */
 246 const gchar     *ibus_proxy_get_name        (IBusProxy          *proxy);
 247
 248 /**
 249  * ibus_proxy_get_unique_name:
 250  * @proxy: An IBusProxy.
 251  * @returns: The service name of the proxy object.
 252  *
 253  * Get the unique name of the proxy object.
 254  */
 255 const gchar     *ibus_proxy_get_unique_name (IBusProxy          *proxy);
 256
 257 /**
 258  * ibus_proxy_get_path:
 259  * @proxy: An IBusProxy.
 260  * @returns: The path of proxy object.
 261  *
 262  * Get the path of a proxy object.
 263  */
 264 const gchar     *ibus_proxy_get_path        (IBusProxy          *proxy);
 265
 266 /**
 267  * ibus_proxy_get_interface:
 268  * @proxy: An IBusProxy.
 269  * @returns: The service name of the proxy object.
 270  *
 271  * Get interface of a proxy object.
 272  */
 273 const gchar     *ibus_proxy_get_interface   (IBusProxy          *proxy);
 274
 275 /**
 276  * ibus_proxy_get_connection:
 277  * @proxy: An IBusProxy.
 278  * @returns: The connection of the proxy object.
 279  *
 280  * Get the connection of a proxy object.
 281  */
 282 IBusConnection  *ibus_proxy_get_connection  (IBusProxy          *proxy);
 283
 284 G_END_DECLS
 285 #endif
 286