GeditMessageBus: gedit Reference Manual

GeditMessageBus

GeditMessageBus — internal message communication bus

Functions

void	(*GeditMessageCallback) ()
void	(*GeditMessageBusForeach) ()
GeditMessageBus *	gedit_message_bus_get_default ()
GeditMessageBus *	gedit_message_bus_new ()
GType	gedit_message_bus_lookup ()
void	gedit_message_bus_register ()
void	gedit_message_bus_unregister ()
void	gedit_message_bus_unregister_all ()
gboolean	gedit_message_bus_is_registered ()
void	gedit_message_bus_foreach ()
guint	gedit_message_bus_connect ()
void	gedit_message_bus_disconnect ()
void	gedit_message_bus_disconnect_by_func ()
void	gedit_message_bus_block ()
void	gedit_message_bus_block_by_func ()
void	gedit_message_bus_unblock ()
void	gedit_message_bus_unblock_by_func ()
void	gedit_message_bus_send_message ()
void	gedit_message_bus_send_message_sync ()
void	gedit_message_bus_send ()
GeditMessage *	gedit_message_bus_send_sync ()

Signals

void	dispatch	Run Last
void	registered	Run Last
void	unregistered	Run Last

Types and Values

struct

GeditMessageBus

Object Hierarchy

    GObject
    ╰── GeditMessageBus

Includes

#include <gedit/gedit-message-bus.h>

Description

gedit has a communication bus very similar to DBus. Its primary use is to allow easy communication between plugins, but it can also be used to expose gedit functionality to external applications by providing DBus bindings for the internal gedit message bus.

There are two different communication busses available. The default bus (see gedit_message_bus_get_default()) is an application wide communication bus. In addition, each GeditWindow has a separate, private bus (see gedit_window_get_message_bus()). This makes it easier for plugins to communicate to other plugins in the same window.

The concept of the message bus is very simple. You can register a message type on the bus, specified as a Method at a specific Object Path with a certain set of Method Arguments. You can then connect callback functions for this message type on the bus. Whenever a message with the Object Path and Method for which callbacks are connected is sent over the bus, the callbacks are called. There is no distinction between Methods and Signals (signals are simply messages where sender and receiver have switched places).

Example 1. Registering a message type

GeditMessageBus *bus = gedit_message_bus_get_default ();

// Register 'method' at '/plugins/example' with one required
// string argument 'arg1'
gedit_message_bus_register (bus, EXAMPLE_TYPE_METHOD_MESSAGE,
                            "/plugins/example", "method");

Example 2. Connecting a callback

static void
example_method_cb (GeditMessageBus *bus,
                   GeditMessage    *message,
                   gpointer         user_data)
{
	gchar *arg1 = NULL;

	gedit_message_get (message, "arg1", &arg1, NULL);
	g_message ("Evoked /plugins/example.method with: %s", arg1);
	g_free (arg1);
}

GeditMessageBus *bus = gedit_message_bus_get_default ();

guint id = gedit_message_bus_connect (bus,
                                      "/plugins/example", "method",
                                      example_method_cb,
                                      NULL,
                                      NULL);

Example 3. Sending a message

GeditMessageBus *bus = gedit_message_bus_get_default ();

gedit_message_bus_send (bus,
                        "/plugins/example", "method",
                        "arg1", "Hello World",
                        NULL);

Functions

GeditMessageCallback ()

void
(*GeditMessageCallback) (GeditMessageBus *bus,
                         GeditMessage *message,
                         gpointer user_data);

Callback signature used for connecting callback functions to be called when a message is received (see gedit_message_bus_connect()).

Parameters

bus	the GeditMessageBus on which the message was sent
message	the GeditMessage which was sent
user_data	the supplied user data when connecting the callback

GeditMessageBusForeach ()

void
(*GeditMessageBusForeach) (gchar const *object_path,
                           gchar const *method,
                           gpointer user_data);

gedit_message_bus_get_default ()

GeditMessageBus *
gedit_message_bus_get_default (void);

Get the default application GeditMessageBus.

Returns

the default GeditMessageBus.

[transfer none]

gedit_message_bus_new ()

GeditMessageBus *
gedit_message_bus_new (void);

Create a new message bus. Use gedit_message_bus_get_default() to get the default, application wide, message bus. Creating a new bus is useful for associating a specific bus with for instance a GeditWindow.

Returns

a new GeditMessageBus

gedit_message_bus_lookup ()

GType
gedit_message_bus_lookup (GeditMessageBus *bus,
                          const gchar *object_path,
                          const gchar *method);

Get the registered GeditMessageType for method at object_path . The returned GeditMessageType is owned by the bus and should not be unreffed.

Parameters

bus	a GeditMessageBus
object_path	the object path
method	the method

Returns

the registered GeditMessageType or NULL if no message type is registered for method at object_path

gedit_message_bus_register ()

void
gedit_message_bus_register (GeditMessageBus *bus,
                            GType message_type,
                            const gchar *object_path,
                            const gchar *method);

Register a message on the bus. A message must be registered on the bus before it can be send. This function registers the type for method at object_path .

This function emits a “registered” signal.

Parameters

bus	a GeditMessageBus
message_type	the message type
object_path	the object path
method	the method to register

gedit_message_bus_unregister ()

void
gedit_message_bus_unregister (GeditMessageBus *bus,
                              const gchar *object_path,
                              const gchar *method);

Unregisters a previously registered message type. This is especially useful for plugins which should unregister message types when they are deactivated.

This function emits the “unregistered” signal.

Parameters

bus	a GeditMessageBus
object_path	the object path
method	the method

gedit_message_bus_unregister_all ()

void
gedit_message_bus_unregister_all (GeditMessageBus *bus,
                                  const gchar *object_path);

Unregisters all message types for object_path . This is especially useful for plugins which should unregister message types when they are deactivated.

This function emits the “unregistered” signal for all unregistered message types.

Parameters

bus	a GeditMessageBus
object_path	the object path

gedit_message_bus_is_registered ()

gboolean
gedit_message_bus_is_registered (GeditMessageBus *bus,
                                 const gchar *object_path,
                                 const gchar *method);

Check whether a message type method at object_path is registered on the bus.

Parameters

bus	a GeditMessageBus
object_path	the object path
method	the method

Returns

TRUE if the method at object_path is a registered message type on the bus

gedit_message_bus_foreach ()

void
gedit_message_bus_foreach (GeditMessageBus *bus,
                           GeditMessageBusForeach func,
                           gpointer user_data);

Calls func for each message type registered on the bus

Parameters

bus	the GeditMessageBus
func	the callback function.	[scope call]
user_data	the user data to supply to the callback function

gedit_message_bus_connect ()

guint
gedit_message_bus_connect (GeditMessageBus *bus,
                           const gchar *object_path,
                           const gchar *method,
                           GeditMessageCallback callback,
                           gpointer user_data,
                           GDestroyNotify destroy_data);

Connect a callback handler to be evoked when message method at object_path is sent over the bus.

Parameters

bus	a GeditMessageBus
object_path	the object path
method	the method
callback	function to be called when message `method` at `object_path` is sent
user_data	user_data to use for the callback.	[allow-none]
destroy_data	function to evoke with `user_data` as argument when `user_data` needs to be freed.	[allow-none]

Returns

the callback identifier

gedit_message_bus_disconnect ()

void
gedit_message_bus_disconnect (GeditMessageBus *bus,
                              guint id);

Disconnects a previously connected message callback.

Parameters

bus	a GeditMessageBus
id	the callback id as returned by `gedit_message_bus_connect()`

gedit_message_bus_disconnect_by_func ()

void
gedit_message_bus_disconnect_by_func (GeditMessageBus *bus,
                                      const gchar *object_path,
                                      const gchar *method,
                                      GeditMessageCallback callback,
                                      gpointer user_data);

Disconnects a previously connected message callback by matching the provided callback function and user_data. See also gedit_message_bus_disconnect().

Parameters

bus	a GeditMessageBus
object_path	the object path
method	the method
callback	the connected callback.	[scope call]
user_data	the user_data with which the callback was connected

gedit_message_bus_block ()

void
gedit_message_bus_block (GeditMessageBus *bus,
                         guint id);

Blocks evoking the callback specified by id . Unblock the callback by using gedit_message_bus_unblock().

Parameters

bus	a GeditMessageBus
id	the callback id

gedit_message_bus_block_by_func ()

void
gedit_message_bus_block_by_func (GeditMessageBus *bus,
                                 const gchar *object_path,
                                 const gchar *method,
                                 GeditMessageCallback callback,
                                 gpointer user_data);

Blocks evoking the callback that matches provided callback and user_data . Unblock the callback using gedit_message_bus_unblock_by_func().

Parameters

bus	a GeditMessageBus
object_path	the object path
method	the method
callback	the callback to block.	[scope call]
user_data	the user_data with which the callback was connected

gedit_message_bus_unblock ()

void
gedit_message_bus_unblock (GeditMessageBus *bus,
                           guint id);

Unblocks the callback specified by id .

Parameters

bus	a GeditMessageBus
id	the callback id

gedit_message_bus_unblock_by_func ()

void
gedit_message_bus_unblock_by_func (GeditMessageBus *bus,
                                   const gchar *object_path,
                                   const gchar *method,
                                   GeditMessageCallback callback,
                                   gpointer user_data);

Unblocks the callback that matches provided callback and user_data .

Parameters

bus	a GeditMessageBus
object_path	the object path
method	the method
callback	the callback to block.	[scope call]
user_data	the user_data with which the callback was connected

gedit_message_bus_send_message ()

void
gedit_message_bus_send_message (GeditMessageBus *bus,
                                GeditMessage *message);

This sends the provided message asynchronously over the bus. To send a message synchronously, use gedit_message_bus_send_message_sync(). The convenience function gedit_message_bus_send() can be used to easily send a message without constructing the message object explicitly first.

Parameters

bus	a GeditMessageBus
message	the message to send

gedit_message_bus_send_message_sync ()

void
gedit_message_bus_send_message_sync (GeditMessageBus *bus,
                                     GeditMessage *message);

This sends the provided message synchronously over the bus. To send a message asynchronously, use gedit_message_bus_send_message(). The convenience function gedit_message_bus_send_sync() can be used to easily send a message without constructing the message object explicitly first.

Parameters

bus	a GeditMessageBus
message	the message to send

gedit_message_bus_send ()

void
gedit_message_bus_send (GeditMessageBus *bus,
                        const gchar *object_path,
                        const gchar *method,
                        const gchar *first_property,
                        ...);

This provides a convenient way to quickly send a message method at object_path asynchronously over the bus. The variable argument list specifies key (string) value pairs used to construct the message arguments. To send a message synchronously use gedit_message_bus_send_sync().

Parameters

bus	a GeditMessageBus
object_path	the object path
method	the method
first_property	the first property
...	NULL terminated list of key/value pairs

gedit_message_bus_send_sync ()

GeditMessage *
gedit_message_bus_send_sync (GeditMessageBus *bus,
                             const gchar *object_path,
                             const gchar *method,
                             const gchar *first_property,
                             ...);

This provides a convenient way to quickly send a message method at object_path synchronously over the bus. The variable argument list specifies key (string) value pairs used to construct the message arguments. To send a message asynchronously use gedit_message_bus_send().

Parameters

bus	a GeditMessageBus
object_path	the object path
method	the method
first_property	the first property
...	`NULL` terminated list of key/value pairs.	[allow-none]

Returns

the constructed GeditMessage. The caller owns a reference to the GeditMessage and should call g_object_unref() when it is no longer needed.

[allow-none][transfer full]

Types and Values

struct GeditMessageBus

struct GeditMessageBus;

Signal Details

The `“dispatch”` signal

void
user_function (GeditMessageBus *bus,
               GeditMessage    *message,
               gpointer         user_data)

The "dispatch" signal is emitted when a message is to be dispatched. The message is dispatched in the default handler of this signal. Primary use of this signal is to customize the dispatch of a message (for instance to automatically dispatch all messages over DBus).

Parameters

bus	a GeditMessageBus
message	the GeditMessage to dispatch
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“registered”` signal

void
user_function (GeditMessageBus *bus,
               char            *object_path,
               char            *method,
               gpointer         user_data)

The "registered" signal is emitted when a message has been registered on the bus.

Parameters

bus	a GeditMessageBus
object_path	the registered object path.
method	the registered method
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“unregistered”` signal

void
user_function (GeditMessageBus *bus,
               char            *object_path,
               char            *method,
               gpointer         user_data)

The "unregistered" signal is emitted when a message has been unregistered from the bus.

Parameters

bus	a GeditMessageBus
object_path	the unregistered object path.
method	the unregistered method
user_data	user data set when the signal handler was connected.

Flags: Run Last