GeditMessageType

## GeditMessageType GeditMessageType — message type description |

## Synopsis

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

                        GeditMessageType;
    GType               gedit_message_type_get_type         (void);
    gboolean            gedit_message_type_is_supported     (GType type);
    gchar *             gedit_message_type_identifier       (const gchar *object_path,
                                                             const gchar *method);
    gboolean            gedit_message_type_is_valid_object_path
                                                            (const gchar *object_path);
    GeditMessageType *  gedit_message_type_new              (const gchar *object_path,
                                                             const gchar *method,
                                                             guint num_optional,
                                                             ...);
    GeditMessageType *  gedit_message_type_new_valist       (const gchar *object_path,
                                                             const gchar *method,
                                                             guint num_optional,
                                                             va_list va_args);
    GeditMessageType *  gedit_message_type_ref              (GeditMessageType *message_type);
    void                gedit_message_type_unref            (GeditMessageType *message_type);
    void                gedit_message_type_set              (GeditMessageType *message_type,
                                                             guint num_optional,
                                                             ...);
    void                gedit_message_type_set_valist       (GeditMessageType *message_type,
                                                             guint num_optional,
                                                             va_list va_args);
    GeditMessage *      gedit_message_type_instantiate      (GeditMessageType *message_type,
                                                             ...);
    GeditMessage *      gedit_message_type_instantiate_valist
                                                            (GeditMessageType *message_type,
                                                             va_list va_args);
    const gchar *       gedit_message_type_get_object_path  (GeditMessageType *message_type);
    const gchar *       gedit_message_type_get_method       (GeditMessageType *message_type);
    GType               gedit_message_type_lookup           (GeditMessageType *message_type,
                                                             const gchar *key);
    void                gedit_message_type_foreach          (GeditMessageType *message_type,
                                                             GeditMessageTypeForeach func,
                                                             gpointer user_data);

## Description

A message type is a prototype description for a GeditMessage used to transmit messages on a GeditMessageBus. 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 GeditMessage from a GeditMessageType, use `gedit_message_type_instantiate()`.

Registering a new message type on a GeditMessageBus with `gedit_message_bus_register()` internally creates a new GeditMessageType. When then using `gedit_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
    GeditMessageType *message_type = gedit_message_type_new ("/plugins/example",
                                                             "method",
                                                             0,
                                                             "arg1", G_TYPE_STRING,
                                                             NULL);

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

## Details

### GeditMessageType

    typedef struct _GeditMessageType GeditMessageType;

### gedit_message_type_get_type ()

    GType               gedit_message_type_get_type         (void);

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

Returns : | the GType associated with GeditMessageType.

### gedit_message_type_is_supported ()

    gboolean            gedit_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

### gedit_message_type_identifier ()

    gchar *             gedit_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`

### gedit_message_type_is_valid_object_path ()

    gboolean            gedit_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

### gedit_message_type_new ()

    GeditMessageType *  gedit_message_type_new              (const gchar *object_path,
                                                             const gchar *method,
                                                             guint num_optional,
                                                             ...);

Create a new GeditMessageType 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 GeditMessageType

### gedit_message_type_new_valist ()

    GeditMessageType *  gedit_message_type_new_valist       (const gchar *object_path,
                                                             const gchar *method,
                                                             guint num_optional,
                                                             va_list va_args);

Create a new GeditMessageType 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 GeditMessageType

### gedit_message_type_ref ()

    GeditMessageType *  gedit_message_type_ref              (GeditMessageType *message_type);

Increases the reference count on `message_type`.

`message_type` : | the GeditMessageType
Returns : | `message_type`

### gedit_message_type_unref ()

    void                gedit_message_type_unref            (GeditMessageType *message_type);

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

`message_type` : | the GeditMessageType

### gedit_message_type_set ()

    void                gedit_message_type_set              (GeditMessageType *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 GeditMessageType
`num_optional` : | number of optional arguments
`...` : | key/gtype pair variable argument list

### gedit_message_type_set_valist ()

    void                gedit_message_type_set_valist       (GeditMessageType *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 GeditMessageType
`num_optional` : | number of optional arguments
`var_args` : | key/gtype pair variable argument list

### gedit_message_type_instantiate ()

    GeditMessage *      gedit_message_type_instantiate      (GeditMessageType *message_type,
                                                             ...);

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

`message_type` : | the GeditMessageType
`...` : | NULL terminated variable list of key/value pairs
Returns : | the newly created message

### gedit_message_type_instantiate_valist ()

    GeditMessage *      gedit_message_type_instantiate_valist
                                                            (GeditMessageType *message_type,
                                                             va_list va_args);

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

`message_type` : | the GeditMessageType
`va_args` : | NULL terminated variable list of key/value pairs
Returns : | the newly created message

### gedit_message_type_get_object_path ()

    const gchar *       gedit_message_type_get_object_path  (GeditMessageType *message_type);

Get the message type object path.

`message_type` : | the GeditMessageType
Returns : | the message type object path

### gedit_message_type_get_method ()

    const gchar *       gedit_message_type_get_method       (GeditMessageType *message_type);

Get the message type method.

`message_type` : | the GeditMessageType
Returns : | the message type method

### gedit_message_type_lookup ()

    GType               gedit_message_type_lookup           (GeditMessageType *message_type,
                                                             const gchar *key);

Get the argument key GType.

`message_type` : | the GeditMessageType
`key` : | the argument key
Returns : | the GType of `key`

### gedit_message_type_foreach ()

    void                gedit_message_type_foreach          (GeditMessageType *message_type,
                                                             GeditMessageTypeForeach func,
                                                             gpointer user_data);

Calls `func` for each argument in the message type.

`message_type` : | the GeditMessageType
`func` : | the callback function
`user_data` : | user data supplied to the callback function