PlumaMessageType

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