IBusConnection

## IBusConnection IBusConnection — DBusConnection wrapper. |

## Stability Level

Stable DBusConnection, unless otherwise indicated

## Synopsis

                        IBusConnection;
                        IBusConnectionClass;
    gboolean            (*IBusIBusMessageFunc)              (IBusConnection *connection,
                                                             IBusMessage *message);
    gboolean            (*IBusIBusSignalFunc)               (IBusConnection *connection,
                                                             IBusMessage *message);
    gboolean            (*IBusMessageFunc)                  (IBusConnection *connection,
                                                             IBusMessage *message,
                                                             gpointer user_data);
    IBusConnection *    ibus_connection_new                 (void);
    void                ibus_connection_set_connection      (IBusConnection *connection,
                                                             DBusConnection *dbus_connection,
                                                             gboolean shared);
    IBusConnection *    ibus_connection_open                (const gchar *address);
    IBusConnection *    ibus_connection_open_private        (const gchar *address);
    void                ibus_connection_close               (IBusConnection *connection);
    gboolean            ibus_connection_is_connected        (IBusConnection *connection);
    gboolean            ibus_connection_is_authenticated    (IBusConnection *connection);
    DBusConnection *    ibus_connection_get_connection      (IBusConnection *connection);
    glong               ibus_connection_get_unix_user       (IBusConnection *connection);
    gboolean            ibus_connection_read_write_dispatch (IBusConnection *connection,
                                                             gint timeout);
    gboolean            ibus_connection_send                (IBusConnection *connection,
                                                             IBusMessage *message);
    gboolean            ibus_connection_send_signal         (IBusConnection *connection,
                                                             const gchar *path,
                                                             const gchar *interface,
                                                             const gchar *name,
                                                             GType first_arg_type,
                                                             ...);
    gboolean            ibus_connection_send_signal_valist  (IBusConnection *connection,
                                                             const gchar *path,
                                                             const gchar *interface,
                                                             const gchar *name,
                                                             GType first_arg_type,
                                                             va_list args);
    gboolean            ibus_connection_send_valist         (IBusConnection *connection,
                                                             gint message_type,
                                                             const gchar *path,
                                                             const gchar *interface,
                                                             const gchar *name,
                                                             GType first_arg_type,
                                                             va_list args);
    gboolean            ibus_connection_send_with_reply     (IBusConnection *connection,
                                                             IBusMessage *message,
                                                             IBusPendingCall **pending_return,
                                                             gint timeout_milliseconds);
    IBusMessage *       ibus_connection_send_with_reply_and_block
                                                            (IBusConnection *connection,
                                                             IBusMessage *message,
                                                             gint timeout_milliseconds,
                                                             IBusError **error);
    gboolean            ibus_connection_call                (IBusConnection *connection,
                                                             const gchar *name,
                                                             const gchar *path,
                                                             const gchar *interface,
                                                             const gchar *member,
                                                             IBusError **error,
                                                             GType first_arg_type,
                                                             ...);
    IBusMessage *       ibus_connection_call_with_reply     (IBusConnection *connection,
                                                             const gchar *name,
                                                             const gchar *path,
                                                             const gchar *interface,
                                                             const gchar *member,
                                                             IBusError **error,
                                                             GType first_arg_type,
                                                             ...);
    void                ibus_connection_flush               (IBusConnection *connection);
    gboolean            ibus_connection_register_object_path
                                                            (IBusConnection *connection,
                                                             const gchar *path,
                                                             IBusMessageFunc message_func,
                                                             gpointer user_data);
    gboolean            ibus_connection_unregister_object_path
                                                            (IBusConnection *connection,
                                                             const gchar *path);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----IBusObject
                   +----IBusConnection

## Signals

      "authenticate-unix-user"                         : Run Last
      "disconnected"                                   : Run Last
      "ibus-message"                                   : Run Last
      "ibus-message-sent"                              : Run Last
      "ibus-signal"                                    : Run Last

## Description

An IBusConnection provides DBusConnection wrapper, and is used to connect to either D-Bus or IBus daemon. Usually, IBusConnection is set to a DBusConnection and emitting ibus-message when receiving incoming messages from the DBusConnection.

`see_also`: IBusMessage

## Details

### IBusConnection

    typedef struct _IBusConnection IBusConnection;

An opaque data type representing an IBusConnection.

### IBusConnectionClass

    typedef struct {
        IBusObjectClass parent;

        /* signals */
        gboolean    (* authenticate_unix_user)
                                        (IBusConnection   *connection,
                                         gulong            uid);
        gboolean    (* ibus_message)    (IBusConnection   *connection,
                                         IBusMessage      *message);
        gboolean    (* ibus_signal)     (IBusConnection   *connection,
                                         IBusMessage      *message);
        void        (* ibus_message_sent)
                                        (IBusConnection   *connection,
                                         IBusMessage      *message);
        void        (* disconnected)    (IBusConnection   *connection);
    } IBusConnectionClass;

### IBusIBusMessageFunc ()

    gboolean            (*IBusIBusMessageFunc)              (IBusConnection *connection,
                                                             IBusMessage *message);

Prototype of an IBusIBusMessage callback function.

`connection` : | An IBusConnection.
`message` : | An IBusMessage.
Returns : | TRUE if succeed; FALSE otherwise.

### IBusIBusSignalFunc ()

    gboolean            (*IBusIBusSignalFunc)               (IBusConnection *connection,
                                                             IBusMessage *message);

Prototype of an IBusIBusSignal callback function.

`connection` : | An IBusConnection.
`message` : | An IBusMessage.
Returns : | TRUE if succeed; FALSE otherwise.

### IBusMessageFunc ()

    gboolean            (*IBusMessageFunc)                  (IBusConnection *connection,
                                                             IBusMessage *message,
                                                             gpointer user_data);

Prototype of an IBusMessage callback function.

`connection` : | An IBusConnection.
`message` : | An IBusMessage.
`user_data` : | User data for the callback function.
Returns : | TRUE if succeed; FALSE otherwise.

### ibus_connection_new ()

    IBusConnection *    ibus_connection_new                 (void);

New an IBusConnection.

Returns : | An newly allocated IBusConnection.

### ibus_connection_set_connection ()

    void                ibus_connection_set_connection      (IBusConnection *connection,
                                                             DBusConnection *dbus_connection,
                                                             gboolean shared);

Set an IBusConnection as data of a D-Bus connection. Emit signal `ibus-message` when receiving incoming message from `dbus_connection`.

`connection` : | An IBusConnection.
`dbus_connection` : | A D-Bus connection.
`shared` : | Whether the `dbus_connection` is shared.

### ibus_connection_open ()

    IBusConnection *    ibus_connection_open                (const gchar *address);

Open an IBusConnection that is set to a D-Bus connection to the specified address. Use `ibus_connection_open_private()` to get a dedicated connection not shared with other callers of `ibus_connection_open()`.

`see_also`: `ibus_connection_open_private()`.

`address` : | A remote address.
Returns : | A newly allocated IBusConnection which is set to a D-Bus connection corresponding to `address`.

### ibus_connection_open_private ()

    IBusConnection *    ibus_connection_open_private        (const gchar *address);

Open an IBusConnection that is set to a D-Bus connection to the specified address. Unlike `ibus_connection_open()`, this function always creates a new D-Bus connection. The D-Bus connection will not be saved or recycled by libdbus.

In D-Bus documentation, `dbus_connection_open()` is preferred over `dbus_connection_open_private()`, so should `ibus_connection_open()` be preferred over `ibus_connection_open_private()`.

`see_also`: `ibus_connection_open()`.

`address` : | A remote address.
Returns : | A newly allocated IBusConnection which is set to a D-Bus connection corresponding to `address`.

### ibus_connection_close ()

    void                ibus_connection_close               (IBusConnection *connection);

Close an IBusCOnnection and corresponding D-Bus connection.

`connection` : | An IBusConnection.

### ibus_connection_is_connected ()

    gboolean            ibus_connection_is_connected        (IBusConnection *connection);

Whether an IBusConnection is connected.

`connection` : | An IBusConnection.
Returns : | TRUE for connected; FALSE otherwise.

### ibus_connection_is_authenticated ()

    gboolean            ibus_connection_is_authenticated    (IBusConnection *connection);

Whether an IBusConnection is authenticated.

`connection` : | An IBusConnection.
Returns : | TRUE for authenticated; FALSE otherwise.

### ibus_connection_get_connection ()

    DBusConnection *    ibus_connection_get_connection      (IBusConnection *connection);

Return corresponding DBusConnection.

`connection` : | An IBusConnection.
Returns : | The corresponding DBusConnection.

### ibus_connection_get_unix_user ()

    glong               ibus_connection_get_unix_user       (IBusConnection *connection);

Return The UNIX UID of peer user.

`connection` : | An IBusConnection.
Returns : | The UNIX UID of peer user.

### ibus_connection_read_write_dispatch ()

    gboolean            ibus_connection_read_write_dispatch (IBusConnection *connection,
                                                             gint timeout);

Return TRUE if the disconnect message has not been processed. This function is a wrapper of `dbus_connection_read_write_dispatch()`, which is also intended for use with applications that don't want to write a main loop and deal with DBusWatch and DBusTimeout. Following text is from the documentation of `dbus_connection_read_write_dispatch()`: An example usage would be:

     while (dbus_connection_read_write_dispatch (connection, -1))
    ; // empty loop body

In this usage you would normally have set up a filter function to look at each message as it is dispatched. The loop terminates when the last message from the connection (the disconnected signal) is processed.

If there are messages to dispatch, this function will `dbus_connection_dispatch()` once, and return. If there are no messages to dispatch, this function will block until it can read or write, then read or write, then return.

The way to think of this function is that it either makes some sort of progress, or it blocks. Note that, while it is blocked on I/O, it cannot be interrupted (even by other threads), which makes this function unsuitable for applications that do more than just react to received messages.

`see_also`: `dbus_connection_read_write_dispatch()`.

`connection` : | An IBusConnection.
`timeout` : | Maximum time to block or -1 for infinite.
Returns : | TRUE if the disconnect message has not been processed; FALSE otherwise.

### ibus_connection_send ()

    gboolean            ibus_connection_send                (IBusConnection *connection,
                                                             IBusMessage *message);

Send an IBusMessage to an IBusConnection. If succeed, signal `ibus-message-sent` is emitted.

`see_also`: `ibus_connection_send_with_reply()`, `ibus_connection_send_with_reply_and_block()`, `ibus_connection_send_signal()`, `ibus_connection_send_signal_valist()`, `ibus_connection_send_valist()`, `dbus_connection_send()`.

`connection` : | An IBusConnection.
`message` : | IBusMessage to be sent.
Returns : | TRUE if succeed; FALSE otherwise.

### ibus_connection_send_signal ()

    gboolean            ibus_connection_send_signal         (IBusConnection *connection,
                                                             const gchar *path,
                                                             const gchar *interface,
                                                             const gchar *name,
                                                             GType first_arg_type,
                                                             ...);

Send a wrapped D-Bus signal to an IBusConnection. This function wraps a signal as an IBusMessage, then sent the IBusMessage via `ibus_connection_send()`.

`see_also`: `ibus_connection_send()`, `ibus_connection_send_signal_valist()`, `ibus_message_new_signal()`.

`connection` : | An IBusConnection.
`path` : | The path to the object emitting the signal.
`interface` : | The interface the signal is emitted from.
`name` : | Name of the signal.
`first_arg_type` : | Type of first argument.
`...` : | Rest of arguments, NULL to mark the end.
Returns : | TRUE if succeed; FALSE otherwise.

### ibus_connection_send_signal_valist ()

    gboolean            ibus_connection_send_signal_valist  (IBusConnection *connection,
                                                             const gchar *path,
                                                             const gchar *interface,
                                                             const gchar *name,
                                                             GType first_arg_type,
                                                             va_list args);

Send a wrapped D-Bus signal to an IBusConnection. This function wraps a signal as an IBusMessage, then sent the IBusMessage via `ibus_connection_send()`.

`see_also`: `ibus_connection_send()`, `ibus_connection_send_signal()`, `ibus_connection_send_valist()`, `ibus_message_new_signal()`.

`connection` : | An IBusConnection.
`path` : | The path to the object emitting the signal.
`interface` : | The interface the signal is emitted from.
`name` : | Name of the signal.
`first_arg_type` : | Type of first arg.
`args` : | Ret of arguments.
Returns : | TRUE if succeed; FALSE otherwise.

### ibus_connection_send_valist ()

    gboolean            ibus_connection_send_valist         (IBusConnection *connection,
                                                             gint message_type,
                                                             const gchar *path,
                                                             const gchar *interface,
                                                             const gchar *name,
                                                             GType first_arg_type,
                                                             va_list args);

Send a wrapped D-Bus message to an IBusConnection.

This function wraps a D-Bus message as an IBusMessage, then sent the IBusMessage via `ibus_connection_send()`.

Message type can be specified with `message_type`. Types include `DBUS_MESSAGE_TYPE_METHOD_CALL`, `DBUS_MESSAGE_TYPE_METHOD_RETURN`, `DBUS_MESSAGE_TYPE_ERROR`, `DBUS_MESSAGE_TYPE_SIGNAL`, but other types are allowed and all code must silently ignore messages of unknown type. `DBUS_MESSAGE_TYPE_INVALID` will never be returned.

`see_also`: `ibus_connection_send()`, `ibus_connection_send_singal_valist()`, `ibus_connection_call()`, `ibus_message_new_signal()`, `dbus_message_get_type()`.

`connection` : | An IBusConnection.
`message_type` : | Message type.
`path` : | The path to the object emitting the signal.
`interface` : | The interface the signal is emitted from.
`name` : | Name of the signal.
`first_arg_type` : | Type of first arg.
`args` : | Ret of arguments.
Returns : | TRUE if succeed; FALSE otherwise.

### ibus_connection_send_with_reply ()

    gboolean            ibus_connection_send_with_reply     (IBusConnection *connection,
                                                             IBusMessage *message,
                                                             IBusPendingCall **pending_return,
                                                             gint timeout_milliseconds);

Queues an IBusMessage to send, and returns a IBusPendingCall used to receive a reply to the message. This function is a wrapper of `dbus_connection_send_with_reply()`.

`see_also`: `ibus_connection_send()`, `ibus_connection_send_with_reply_and_block()`, `ibus_proxy_call_with_reply()`, IBusPendingCall, `dbus_connection_send_with_reply()`

`connection` : | An IBusConnection.
`message` : | An IBusMessage.
`pending_return` : | Return location of a IBusPendingCall object, or NULL if connection is disconnected.
`timeout_milliseconds` : | timeout in milliseconds or -1 for default.
Returns : | FALSE if no memory, TRUE otherwise.

### ibus_connection_send_with_reply_and_block ()

    IBusMessage *       ibus_connection_send_with_reply_and_block
                                                            (IBusConnection *connection,
                                                             IBusMessage *message,
                                                             gint timeout_milliseconds,
                                                             IBusError **error);

Sends an IBus message and blocks a certain time period while waiting for an IBusMessage as reply. If the IBusMessage is not NULL, signal `ibus-message-sent` is emitted.

`see_also`: `ibus_connection_send()`, `ibus_connection_send_with_reply()`, `dbus_connection_send_with_reply_and_block()`

`connection` : | An IBusConnection.
`message` : | An IBusMessage.
`timeout_milliseconds` : | timeout in milliseconds or -1 for default.
`error` : | Returned error is stored here; NULL to ignore error.
Returns : | An IBusMessage that is the reply or NULL with an error code if the function fails.

### ibus_connection_call ()

    gboolean            ibus_connection_call                (IBusConnection *connection,
                                                             const gchar *name,
                                                             const gchar *path,
                                                             const gchar *interface,
                                                             const gchar *member,
                                                             IBusError **error,
                                                             GType first_arg_type,
                                                             ...);

Invoke a member function by sending an IBusMessage. This method does not support reply message, use ibus_connection_call_with_reply instead.

`see_also`: `ibus_connection_send_valist()`.

`connection` : | An IBusConnection.
`name` : | Name of the signal.
`path` : | The path to the object emitting the signal.
`interface` : | The interface the signal is emitted from.
`member` : | The name of the member function to be called.
`error` : | Returned error is stored here; NULL to ignore error.
`first_arg_type` : | Type of first argument.
`...` : | Rest of arguments, NULL to mark the end.
Returns : | TRUE if succeed; FALSE otherwise.

### ibus_connection_call_with_reply ()

    IBusMessage *       ibus_connection_call_with_reply     (IBusConnection *connection,
                                                             const gchar *name,
                                                             const gchar *path,
                                                             const gchar *interface,
                                                             const gchar *member,
                                                             IBusError **error,
                                                             GType first_arg_type,
                                                             ...);

Invoke a member function by sending an IBusMessage.

`see_also`: `ibus_connection_send_valist()`.

`connection` : | An IBusConnection.
`name` : | Name of the signal.
`path` : | The path to the object emitting the signal.
`interface` : | The interface the signal is emitted from.
`member` : | The name of the member function to be called.
`error` : | Returned error is stored here; NULL to ignore error.
`first_arg_type` : | Type of first argument.
`...` : | Rest of arguments, NULL to mark the end.
Returns : | Reply message, or NULL when fail. The returned message must be freed with `ibus_message_unref()`.

### ibus_connection_flush ()

    void                ibus_connection_flush               (IBusConnection *connection);

Blocks until the outgoing message queue is empty. This function is a wrapper of `dbus_connection_flush()`.

`see_also`: `dbus_connection_flush()`

`connection` : | An IBusConnection.

### ibus_connection_register_object_path ()

    gboolean            ibus_connection_register_object_path
                                                            (IBusConnection *connection,
                                                             const gchar *path,
                                                             IBusMessageFunc message_func,
                                                             gpointer user_data);

Registers a handler for a given path in the object hierarchy. The given vtable handles messages sent to exactly the given path. This function is a wrapper of `dbus_connection_register_object_path()`.

`see_also`: `ibus_connection_register_object_path()`

`connection` : | An IBusConnection.
`path` : | Object path to be register.
`message_func` : | Callback function for message handling.
`user_data` : | User data for `message_func`.
Returns : | FALSE if fail because of out of memory; TRUE otherwise.

### ibus_connection_unregister_object_path ()

    gboolean            ibus_connection_unregister_object_path
                                                            (IBusConnection *connection,
                                                             const gchar *path);

Unregisters the handler registered with exactly the given path. It's a bug to call this function for a path that isn't registered. Can unregister both fallback paths and object paths. This function is a wrapper of `dbus_connection_unregister_object_path()`

`connection` : | An IBusConnection.
`path` : | Object path to be unregister.
Returns : | FALSE if fail because of out of memory; TRUE otherwise.

## Signal Details

### The `"authenticate-unix-user"` signal

    gboolean            user_function                      (IBusConnection *ibusconnection,
                                                            gulong          uid,
                                                            gpointer        user_data)           : Run Last

Emitted when sending an ibus-message. Implement the member function `ibus_message()` in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`ibusconnection` : | The object which received the signal.
`uid` : | unix user id.
`user_data` : | user data set when the signal handler was connected.
Returns : | TRUE if succeed; FALSE otherwise.

### The `"disconnected"` signal

    void                user_function                      (IBusConnection *ibusconnection,
                                                            gpointer        user_data)           : Run Last

Emitted when an ibus-message is disconnected. Implement the member function `disconnected()` function in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`ibusconnection` : | The object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"ibus-message"` signal

    gboolean            user_function                      (IBusConnection *ibusconnection,
                                                            gpointer        message,
                                                            gpointer        user_data)           : Run Last

Emitted when sending an ibus-message. Implement the member function `ibus_message()` in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`ibusconnection` : | The object which received the signal.
`message` : | An IBusMessage.
`user_data` : | user data set when the signal handler was connected.
Returns : | TRUE if succeed; FALSE otherwise.

### The `"ibus-message-sent"` signal

    void                user_function                      (IBusConnection *ibusconnection,
                                                            gpointer        message,
                                                            gpointer        user_data)           : Run Last

Emitted when an ibus-message is sent. Implement the member function `ibus_message_sent()` function in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`ibusconnection` : | The object which received the signal.
`message` : | An IBusMessage that contain the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"ibus-signal"` signal

    gboolean            user_function                      (IBusConnection *ibusconnection,
                                                            gpointer        message,
                                                            gpointer        user_data)           : Run Last

Emitted when sending an ibus-signal. Implement the member function `ibus_signal()` function in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`ibusconnection` : | The object which received the signal.
`message` : | An IBusMessage that contain the signal.
`user_data` : | user data set when the signal handler was connected.
Returns : | TRUE if succeed; FALSE otherwise.