Top | ![]() |
![]() |
![]() |
![]() |
void | (*PlumaMessageCallback) () |
PlumaMessageBus * | pluma_message_bus_get_default () |
PlumaMessageBus * | pluma_message_bus_new () |
PlumaMessageType * | pluma_message_bus_lookup () |
PlumaMessageType * | pluma_message_bus_register () |
void | pluma_message_bus_unregister () |
void | pluma_message_bus_unregister_all () |
gboolean | pluma_message_bus_is_registered () |
void | pluma_message_bus_foreach () |
guint | pluma_message_bus_connect () |
void | pluma_message_bus_disconnect () |
void | pluma_message_bus_disconnect_by_func () |
void | pluma_message_bus_block () |
void | pluma_message_bus_block_by_func () |
void | pluma_message_bus_unblock () |
void | pluma_message_bus_unblock_by_func () |
void | pluma_message_bus_send_message () |
void | pluma_message_bus_send_message_sync () |
void | pluma_message_bus_send () |
PlumaMessage * | pluma_message_bus_send_sync () |
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); |
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 |
PlumaMessageBus *
pluma_message_bus_get_default (void
);
Get the default application PlumaMessageBus.
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.
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.
the registered PlumaMessageType or NULL
if no message type
is registered for method
at object_path
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 |
||
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 |
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()
.
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.
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.
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.
void pluma_message_bus_foreach (PlumaMessageBus *bus
,PlumaMessageBusForeach func
,gpointer userdata
);
Calls func
for each message type registered on the bus
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.
void pluma_message_bus_disconnect (PlumaMessageBus *bus
,guint id
);
Disconnects a previously connected message callback.
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()
.
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()
.
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()
.
void pluma_message_bus_unblock (PlumaMessageBus *bus
,guint id
);
Unblocks the callback specified by id
.
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
.
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.
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.
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()
.
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 |
||
object_path |
the object path |
|
method |
the method |
|
... |
NULL terminated list of key/value pairs |
the constructed PlumaMessage. The caller owns a reference
to the PlumaMessage and should call g_object_unref()
when
it is no longer needed
“dispatch”
signalvoid user_function (PlumaMessageBus *bus, PlumaMessage *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). 2
bus |
||
message |
the PlumaMessage to dispatch |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“registered”
signalvoid user_function (PlumaMessageBus *bus, PlumaMessageType *message_type, gpointer user_data)
The "registered" signal is emitted when a message has been registered on the bus.
bus |
||
message_type |
the registered PlumaMessageType |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“unregistered”
signalvoid user_function (PlumaMessageBus *bus, PlumaMessageType *message_type, gpointer user_data)
The "unregistered" signal is emitted when a message has been unregistered from the bus.
bus |
||
message_type |
the unregistered PlumaMessageType |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last