IBusConnection

IBusConnection — DBusConnection wrapper.

Stability Level

Stable DBusConnection, unless otherwise indicated

Synopsis

gboolean            (*IBusIBusMessageFunc)              (IBusConnection *connection,
                                                         IBusMessage *message);
gboolean            (*IBusIBusSignalFunc)               (IBusConnection *connection,
                                                         IBusMessage *message);
gboolean            (*IBusMessageFunc)                  (IBusConnection *connection,
                                                         IBusMessage *message,
                                                         gpointer user_data);
                    IBusConnection;
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

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.

IBusConnection

typedef struct _IBusConnection IBusConnection;

An opaque data type representing an IBusConnection.


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.