PlumaMessageBus: pluma Reference Manual

## PlumaMessageBus PlumaMessageBus — internal message communication bus |

## Functions

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

## Signals

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

## Types and Values

struct | PlumaMessageBus

## Object Hierarchy

        GObject
        ╰── PlumaMessageBus

## Includes

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

## 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);

## Functions

### 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()`).

#### Parameters

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.

[transfer none]

### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

bus | the PlumaMessagebus |
func | the callback function. | [scope call]
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.

#### Parameters

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.

#### Parameters

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

#### Parameters

bus | a PlumaMessageBus |
object_path | the object path |
method | the method |
callback | the connected callback. | [scope call]
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()`.

#### Parameters

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

#### Parameters

bus | a PlumaMessageBus |
object_path | the object path |
method | the method |
callback | the callback to block. | [scope call]
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` .

#### Parameters

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` .

#### Parameters

bus | a PlumaMessageBus |
object_path | the object path |
method | the method |
callback | the callback to block. | [scope call]
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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

[transfer full]

## Types and Values

### struct PlumaMessageBus

    struct PlumaMessageBus;

## Signal Details

### The `“dispatch”` signal

    void
    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

#### Parameters

bus | a PlumaMessageBus |
message | the PlumaMessage to dispatch |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“registered”` signal

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

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

#### Parameters

bus | a PlumaMessageBus |
message_type | the registered PlumaMessageType |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“unregistered”` signal

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

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

#### Parameters

bus | a PlumaMessageBus |
message_type | the unregistered PlumaMessageType |
user_data | user data set when the signal handler was connected. |

Flags: Run Last