PlumaMessageType

PlumaMessageType — message type description

Synopsis

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

                    PlumaMessageType;
GType               pluma_message_type_get_type         (void);
gboolean            pluma_message_type_is_supported     (GType type);
gchar *             pluma_message_type_identifier       (const gchar *object_path,
                                                         const gchar *method);
gboolean            pluma_message_type_is_valid_object_path
                                                        (const gchar *object_path);
PlumaMessageType *  pluma_message_type_new              (const gchar *object_path,
                                                         const gchar *method,
                                                         guint num_optional,
                                                         ...);
PlumaMessageType *  pluma_message_type_new_valist       (const gchar *object_path,
                                                         const gchar *method,
                                                         guint num_optional,
                                                         va_list va_args);
PlumaMessageType *  pluma_message_type_ref              (PlumaMessageType *message_type);
void                pluma_message_type_unref            (PlumaMessageType *message_type);
void                pluma_message_type_set              (PlumaMessageType *message_type,
                                                         guint num_optional,
                                                         ...);
void                pluma_message_type_set_valist       (PlumaMessageType *message_type,
                                                         guint num_optional,
                                                         va_list va_args);
PlumaMessage *      pluma_message_type_instantiate      (PlumaMessageType *message_type,
                                                         ...);
PlumaMessage *      pluma_message_type_instantiate_valist
                                                        (PlumaMessageType *message_type,
                                                         va_list va_args);
const gchar *       pluma_message_type_get_object_path  (PlumaMessageType *message_type);
const gchar *       pluma_message_type_get_method       (PlumaMessageType *message_type);
GType               pluma_message_type_lookup           (PlumaMessageType *message_type,
                                                         const gchar *key);
void                pluma_message_type_foreach          (PlumaMessageType *message_type,
                                                         PlumaMessageTypeForeach func,
                                                         gpointer user_data);

Object Hierarchy

  GBoxed
   +----PlumaMessageType

Description

A message type is a prototype description for a PlumaMessage used to transmit messages on a PlumaMessageBus. The message type describes the Object Path, Method and Arguments of the message.

A message type can contain any number of required and optional arguments. To instantiate a PlumaMessage from a PlumaMessageType, use pluma_message_type_instantiate().

Registering a new message type on a PlumaMessageBus with pluma_message_bus_register() internally creates a new PlumaMessageType. When then using pluma_message_bus_send(), an actual instantiation of the registered type is internally created and send over the bus.

Example 4. 

1
2
3
4
5
6
7
8
9
10
11
// Defining a new message type
PlumaMessageType *message_type = pluma_message_type_new ("/plugins/example",
                                                         "method",
                                                         0,
                                                         "arg1", G_TYPE_STRING,
                                                         NULL);

// Instantiating an actual message from the type
PlumaMessage *message = pluma_message_type_instantiate (message_type,
                                                        "arg1", "Hello World",
                                                        NULL);


Details

PlumaMessageType

typedef struct _PlumaMessageType PlumaMessageType;

pluma_message_type_get_type ()

GType               pluma_message_type_get_type         (void);

Retrieves the GType object which is associated with the PlumaMessageType class.

Returns :

the GType associated with PlumaMessageType.

pluma_message_type_is_supported ()

gboolean            pluma_message_type_is_supported     (GType type);

Returns if type is GType supported by the message system.

type :

the GType

Returns :

TRUE if type is a supported GType

pluma_message_type_identifier ()

gchar *             pluma_message_type_identifier       (const gchar *object_path,
                                                         const gchar *method);

Get the string identifier for method at object_path.

object_path :

the object path

method :

the method

Returns :

the identifier for method at object_path

pluma_message_type_is_valid_object_path ()

gboolean            pluma_message_type_is_valid_object_path
                                                        (const gchar *object_path);

Returns whether object_path is a valid object path

object_path :

the object path

Returns :

TRUE if object_path is a valid object path

pluma_message_type_new ()

PlumaMessageType *  pluma_message_type_new              (const gchar *object_path,
                                                         const gchar *method,
                                                         guint num_optional,
                                                         ...);

Create a new PlumaMessageType for method at object_path. Argument names and values are supplied by the NULL terminated variable argument list. The last num_optional provided arguments are considered optional.

object_path :

the object path

method :

the method

num_optional :

number of optional arguments

... :

key/gtype pair variable argument list

Returns :

the newly constructed PlumaMessageType

pluma_message_type_new_valist ()

PlumaMessageType *  pluma_message_type_new_valist       (const gchar *object_path,
                                                         const gchar *method,
                                                         guint num_optional,
                                                         va_list va_args);

Create a new PlumaMessageType for method at object_path. Argument names and values are supplied by the NULL terminated variable argument list. The last num_optional provided arguments are considered optional.

object_path :

the object path

method :

the method

num_optional :

number of optional arguments

var_args :

key/gtype pair variable argument list

Returns :

the newly constructed PlumaMessageType

pluma_message_type_ref ()

PlumaMessageType *  pluma_message_type_ref              (PlumaMessageType *message_type);

Increases the reference count on message_type.

message_type :

the PlumaMessageType

Returns :

message_type

pluma_message_type_unref ()

void                pluma_message_type_unref            (PlumaMessageType *message_type);

Decreases the reference count on message_type. When the reference count drops to 0, message_type is destroyed.

message_type :

the PlumaMessageType

pluma_message_type_set ()

void                pluma_message_type_set              (PlumaMessageType *message_type,
                                                         guint num_optional,
                                                         ...);

Sets argument names/types supplied by the NULL terminated variable argument list. The last num_optional provided arguments are considered optional.

message_type :

the PlumaMessageType

num_optional :

number of optional arguments

... :

key/gtype pair variable argument list

pluma_message_type_set_valist ()

void                pluma_message_type_set_valist       (PlumaMessageType *message_type,
                                                         guint num_optional,
                                                         va_list va_args);

Sets argument names/types supplied by the NULL terminated variable argument list var_args. The last num_optional provided arguments are considered optional.

message_type :

the PlumaMessageType

num_optional :

number of optional arguments

var_args :

key/gtype pair variable argument list

pluma_message_type_instantiate ()

PlumaMessage *      pluma_message_type_instantiate      (PlumaMessageType *message_type,
                                                         ...);

Instantiate a new message from the message type with specific values for the message arguments.

message_type :

the PlumaMessageType

... :

NULL terminated variable list of key/value pairs

Returns :

the newly created message

pluma_message_type_instantiate_valist ()

PlumaMessage *      pluma_message_type_instantiate_valist
                                                        (PlumaMessageType *message_type,
                                                         va_list va_args);

Instantiate a new message from the message type with specific values for the message arguments.

message_type :

the PlumaMessageType

va_args :

NULL terminated variable list of key/value pairs

Returns :

the newly created message

pluma_message_type_get_object_path ()

const gchar *       pluma_message_type_get_object_path  (PlumaMessageType *message_type);

Get the message type object path.

message_type :

the PlumaMessageType

Returns :

the message type object path

pluma_message_type_get_method ()

const gchar *       pluma_message_type_get_method       (PlumaMessageType *message_type);

Get the message type method.

message_type :

the PlumaMessageType

Returns :

the message type method

pluma_message_type_lookup ()

GType               pluma_message_type_lookup           (PlumaMessageType *message_type,
                                                         const gchar *key);

Get the argument key GType.

message_type :

the PlumaMessageType

key :

the argument key

Returns :

the GType of key

pluma_message_type_foreach ()

void                pluma_message_type_foreach          (PlumaMessageType *message_type,
                                                         PlumaMessageTypeForeach func,
                                                         gpointer user_data);

Calls func for each argument in the message type.

message_type :

the PlumaMessageType

func :

the callback function

user_data :

user data supplied to the callback function