PlumaMessageType: pluma Reference Manual

## PlumaMessageType PlumaMessageType — message type description |

## Functions

GType | pluma_message_type_get_type ()
gboolean | pluma_message_type_is_supported ()
gchar * | pluma_message_type_identifier ()
gboolean | pluma_message_type_is_valid_object_path ()
PlumaMessageType * | pluma_message_type_new ()
PlumaMessageType * | pluma_message_type_new_valist ()
PlumaMessageType * | pluma_message_type_ref ()
void | pluma_message_type_unref ()
void | pluma_message_type_set ()
void | pluma_message_type_set_valist ()
PlumaMessage * | pluma_message_type_instantiate ()
PlumaMessage * | pluma_message_type_instantiate_valist ()
const gchar * | pluma_message_type_get_object_path ()
const gchar * | pluma_message_type_get_method ()
GType | pluma_message_type_lookup ()
void | pluma_message_type_foreach ()

## Types and Values

| PlumaMessageType

## Object Hierarchy

        GBoxed
        ╰── PlumaMessageType

## Includes

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

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

## Functions

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

#### Parameters

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

#### Parameters

object_path | the object path. | [allow-none]
method | the method. | [allow-none]

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

#### Parameters

object_path | the object path. | [allow-none]

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

#### Parameters

object_path | the object path. | [allow-none]
method | the method. | [allow-none]
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.

#### Parameters

object_path | the object path. | [allow-none]
method | the method. | [allow-none]
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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

message_type | the PlumaMessageType |
... | NULL terminated variable list of key/value pairs |

#### Returns

the newly created message.

[transfer full]

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

#### Parameters

message_type | the PlumaMessageType |
va_args | NULL terminated variable list of key/value pairs |

#### Returns

the newly created message.

[transfer full]

### pluma_message_type_get_object_path ()

    const gchar *
    pluma_message_type_get_object_path (PlumaMessageType *message_type);

Get the message type object path.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

message_type | the PlumaMessageType |
func | the callback function. | [scope call]
user_data | user data supplied to the callback function |

## Types and Values

### PlumaMessageType

    typedef struct _PlumaMessageType PlumaMessageType;