PlumaMessageBus

PlumaMessageBus — internal message communication bus

Synopsis

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

struct              PlumaMessageBus;
void                (*PlumaMessageCallback)             (PlumaMessageBus *bus,
                                                         PlumaMessage *message,
                                                         gpointer userdata);
PlumaMessageBus *   pluma_message_bus_get_default       (void);
PlumaMessageBus *   pluma_message_bus_new               (void);
PlumaMessageType *  pluma_message_bus_lookup            (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method);
PlumaMessageType *  pluma_message_bus_register          (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method,
                                                         guint num_optional,
                                                         ...);
void                pluma_message_bus_unregister        (PlumaMessageBus *bus,
                                                         PlumaMessageType *message_type);
void                pluma_message_bus_unregister_all    (PlumaMessageBus *bus,
                                                         const gchar *object_path);
gboolean            pluma_message_bus_is_registered     (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method);
void                pluma_message_bus_foreach           (PlumaMessageBus *bus,
                                                         PlumaMessageBusForeach func,
                                                         gpointer userdata);
guint               pluma_message_bus_connect           (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method,
                                                         PlumaMessageCallback callback,
                                                         gpointer userdata,
                                                         GDestroyNotify destroy_data);
void                pluma_message_bus_disconnect        (PlumaMessageBus *bus,
                                                         guint id);
void                pluma_message_bus_disconnect_by_func
                                                        (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method,
                                                         PlumaMessageCallback callback,
                                                         gpointer userdata);
void                pluma_message_bus_block             (PlumaMessageBus *bus,
                                                         guint id);
void                pluma_message_bus_block_by_func     (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method,
                                                         PlumaMessageCallback callback,
                                                         gpointer userdata);
void                pluma_message_bus_unblock           (PlumaMessageBus *bus,
                                                         guint id);
void                pluma_message_bus_unblock_by_func   (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method,
                                                         PlumaMessageCallback callback,
                                                         gpointer userdata);
void                pluma_message_bus_send_message      (PlumaMessageBus *bus,
                                                         PlumaMessage *message);
void                pluma_message_bus_send_message_sync (PlumaMessageBus *bus,
                                                         PlumaMessage *message);
void                pluma_message_bus_send              (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method,
                                                         ...);
PlumaMessage *      pluma_message_bus_send_sync         (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method,
                                                         ...);

Object Hierarchy

  GObject
   +----PlumaMessageBus

Signals

  "dispatch"                                       : Run Last
  "registered"                                     : Run Last
  "unregistered"                                   : Run Last

Description

pluma 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 pluma functionality to external applications by providing DBus bindings for the internal pluma message bus.

There are two different communication busses available. The default bus (see pluma_message_bus_get_default()) is an application wide communication bus. In addition, each PlumaWindow has a separate, private bus (see pluma_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

1
2
3
4
5
6
7
8
PlumaMessageBus *bus = pluma_message_bus_get_default ();

// Register 'method' at '/plugins/example' with one required
// string argument 'arg1'
PlumaMessageType *message_type = pluma_message_bus_register ("/plugins/example", "method", 
                                                             0, 
                                                             "arg1", G_TYPE_STRING,
                                                             NULL);


Example 2. Connecting a callback

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
static void
example_method_cb (PlumaMessageBus *bus,
                   PlumaMessage    *message,
                   gpointer         userdata)
{
	gchar *arg1 = NULL;

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

PlumaMessageBus *bus = pluma_message_bus_get_default ();

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


Example 3. Sending a message

1
2
3
4
5
6
PlumaMessageBus *bus = pluma_message_bus_get_default ();

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


Details

struct PlumaMessageBus

struct PlumaMessageBus;

PlumaMessageCallback ()

void                (*PlumaMessageCallback)             (PlumaMessageBus *bus,
                                                         PlumaMessage *message,
                                                         gpointer userdata);

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

bus :

the PlumaMessageBus on which the message was sent

message :

the PlumaMessage which was sent

userdata :

the supplied user data when connecting the callback

pluma_message_bus_get_default ()

PlumaMessageBus *   pluma_message_bus_get_default       (void);

Get the default application PlumaMessageBus.

Returns :

the default PlumaMessageBus

pluma_message_bus_new ()

PlumaMessageBus *   pluma_message_bus_new               (void);

Create a new message bus. Use pluma_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 PlumaWindow.

Returns :

a new PlumaMessageBus

pluma_message_bus_lookup ()

PlumaMessageType *  pluma_message_bus_lookup            (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method);

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

bus :

a PlumaMessageBus

object_path :

the object path

method :

the method

Returns :

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

pluma_message_bus_register ()

PlumaMessageType *  pluma_message_bus_register          (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method,
                                                         guint num_optional,
                                                         ...);

Register a message on the bus. A message must be registered on the bus before it can be send. This function registers the type arguments for method at object_path. The arguments are specified with the variable arguments which should contain pairs of const gchar *key and GType terminated by NULL. The last num_optional arguments are registered as optional (and are thus not required when sending a message).

This function emits a "registered" signal.

bus :

a PlumaMessageBus

object_path :

the object path

method :

the method to register

num_optional :

the number of optional arguments

... :

NULL terminated list of key/gtype method argument pairs

Returns :

the registered PlumaMessageType. The returned reference is owned by the bus. If you want to keep it alive after unregistering, use pluma_message_type_ref().

pluma_message_bus_unregister ()

void                pluma_message_bus_unregister        (PlumaMessageBus *bus,
                                                         PlumaMessageType *message_type);

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.

bus :

a PlumaMessageBus

message_type :

the PlumaMessageType to unregister

pluma_message_bus_unregister_all ()

void                pluma_message_bus_unregister_all    (PlumaMessageBus *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.

bus :

a PlumaMessageBus

object_path :

the object path

pluma_message_bus_is_registered ()

gboolean            pluma_message_bus_is_registered     (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method);

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

bus :

a PlumaMessageBus

object_path :

the object path

method :

the method

Returns :

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

pluma_message_bus_foreach ()

void                pluma_message_bus_foreach           (PlumaMessageBus *bus,
                                                         PlumaMessageBusForeach func,
                                                         gpointer userdata);

Calls func for each message type registered on the bus

bus :

the PlumaMessagebus

func :

the callback function

userdata :

the user data to supply to the callback function

pluma_message_bus_connect ()

guint               pluma_message_bus_connect           (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method,
                                                         PlumaMessageCallback callback,
                                                         gpointer userdata,
                                                         GDestroyNotify destroy_data);

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

bus :

a PlumaMessageBus

object_path :

the object path

method :

the method

callback :

function to be called when message method at object_path is sent

userdata :

userdata to use for the callback

destroy_data :

function to evoke with userdata as argument when userdata needs to be freed

Returns :

the callback identifier

pluma_message_bus_disconnect ()

void                pluma_message_bus_disconnect        (PlumaMessageBus *bus,
                                                         guint id);

Disconnects a previously connected message callback.

bus :

a PlumaMessageBus

id :

the callback id as returned by pluma_message_bus_connect()

pluma_message_bus_disconnect_by_func ()

void                pluma_message_bus_disconnect_by_func
                                                        (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method,
                                                         PlumaMessageCallback callback,
                                                         gpointer userdata);

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

bus :

a PlumaMessageBus

object_path :

the object path

method :

the method

callback :

the connected callback

userdata :

the userdata with which the callback was connected

pluma_message_bus_block ()

void                pluma_message_bus_block             (PlumaMessageBus *bus,
                                                         guint id);

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

bus :

a PlumaMessageBus

id :

the callback id

pluma_message_bus_block_by_func ()

void                pluma_message_bus_block_by_func     (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method,
                                                         PlumaMessageCallback callback,
                                                         gpointer userdata);

Blocks evoking the callback that matches provided callback and userdata. Unblock the callback using pluma_message_unblock_by_func().

bus :

a PlumaMessageBus

object_path :

the object path

method :

the method

callback :

the callback to block

userdata :

the userdata with which the callback was connected

pluma_message_bus_unblock ()

void                pluma_message_bus_unblock           (PlumaMessageBus *bus,
                                                         guint id);

Unblocks the callback specified by id.

bus :

a PlumaMessageBus

id :

the callback id

pluma_message_bus_unblock_by_func ()

void                pluma_message_bus_unblock_by_func   (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method,
                                                         PlumaMessageCallback callback,
                                                         gpointer userdata);

Unblocks the callback that matches provided callback and userdata.

bus :

a PlumaMessageBus

object_path :

the object path

method :

the method

callback :

the callback to block

userdata :

the userdata with which the callback was connected

pluma_message_bus_send_message ()

void                pluma_message_bus_send_message      (PlumaMessageBus *bus,
                                                         PlumaMessage *message);

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

bus :

a PlumaMessageBus

message :

the message to send

pluma_message_bus_send_message_sync ()

void                pluma_message_bus_send_message_sync (PlumaMessageBus *bus,
                                                         PlumaMessage *message);

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

bus :

a PlumaMessageBus

message :

the message to send

pluma_message_bus_send ()

void                pluma_message_bus_send              (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method,
                                                         ...);

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 pluma_message_bus_send_sync().

bus :

a PlumaMessageBus

object_path :

the object path

method :

the method

... :

NULL terminated list of key/value pairs

pluma_message_bus_send_sync ()

PlumaMessage *      pluma_message_bus_send_sync         (PlumaMessageBus *bus,
                                                         const gchar *object_path,
                                                         const gchar *method,
                                                         ...);

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 pluma_message_bus_send().

bus :

a PlumaMessageBus

object_path :

the object path

method :

the method

... :

NULL terminated list of key/value pairs

Returns :

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

Signal Details

The "dispatch" signal

void                user_function                      (PlumaMessageBus *bus,
                                                        PlumaMessage    *message,
                                                        gpointer         user_data)      : Run Last

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). 2

bus :

a PlumaMessageBus

message :

the PlumaMessage to dispatch

user_data :

user data set when the signal handler was connected.

The "registered" signal

void                user_function                      (PlumaMessageBus  *bus,
                                                        PlumaMessageType *message_type,
                                                        gpointer          user_data)         : Run Last

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

bus :

a PlumaMessageBus

message_type :

the registered PlumaMessageType

user_data :

user data set when the signal handler was connected.

The "unregistered" signal

void                user_function                      (PlumaMessageBus  *bus,
                                                        PlumaMessageType *message_type,
                                                        gpointer          user_data)         : Run Last

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

bus :

a PlumaMessageBus

message_type :

the unregistered PlumaMessageType

user_data :

user data set when the signal handler was connected.