## Message Data

Message Data — Message container for UniqueApp

## Synopsis

                        UniqueMessageData;
    UniqueMessageData * unique_message_data_new             (void);
    UniqueMessageData * unique_message_data_copy            (UniqueMessageData *message_data);
    void                unique_message_data_free            (UniqueMessageData *message_data);

    void                unique_message_data_set             (UniqueMessageData *message_data,
                                                             const guchar *data,
                                                             gsize length);
    const guchar *      unique_message_data_get             (UniqueMessageData *message_data,
                                                             gsize *length);

    gboolean            unique_message_data_set_text        (UniqueMessageData *message_data,
                                                             const gchar *str,
                                                             gssize length);
    gchar *             unique_message_data_get_text        (UniqueMessageData *message_data);
    gboolean            unique_message_data_set_uris        (UniqueMessageData *message_data,
                                                             gchar **uris);
    gchar **            unique_message_data_get_uris        (UniqueMessageData *message_data);
    void                unique_message_data_set_filename    (UniqueMessageData *message_data,
                                                             const gchar *filename);
    gchar *             unique_message_data_get_filename    (UniqueMessageData *message_data);

    GdkScreen *         unique_message_data_get_screen      (UniqueMessageData *message_data);
    const gchar *       unique_message_data_get_startup_id  (UniqueMessageData *message_data);
    guint               unique_message_data_get_workspace   (UniqueMessageData *message_data);

## Description

UniqueMessageData contains the data sent from a UniqueApp to a running instance of the same application. It can contain arbitrary binary data, and provides convenience functions to set plain text or URI list.

You should create a UniqueMessageData structure using `unique_message_data_new()`, you can copy it using the `unique_message_data_copy()` and you should free it using `unique_message_data_free()`.

You can set data using `unique_message_data_set()`, `unique_message_data_set_text()`, `unique_message_data_set_filename()` or `unique_message_data_set_uris()`.

You can retrieve the data set using `unique_message_data_get()`, `unique_message_data_get_text()`, `unique_message_data_get_filename()` or `unique_message_data_get_uris()`.

## Details

### UniqueMessageData

    typedef struct _UniqueMessageData UniqueMessageData;

UniqueMessageData contains the data passed between instances of a UniqueApp. The UniqueMessageData structure received inside the signal handlers for UniqueApp::message-received is guaranteed to contain the GdkScreen, the workspace and the startup notification id of the instance sending the message.

### unique_message_data_new ()

    UniqueMessageData * unique_message_data_new             (void);

Creates a new UniqueMessageData structure. This structure holds the message data passed between running instances with `unique_app_send_message()`.

Returns : | the newly created UniqueMessageData

### unique_message_data_copy ()

    UniqueMessageData * unique_message_data_copy            (UniqueMessageData *message_data);

Copies `message_data`.

`message_data` : | a UniqueMessageData
Returns : | a copy of the passed UniqueMessageData

### unique_message_data_free ()

    void                unique_message_data_free            (UniqueMessageData *message_data);

Frees all the resources allocated by `message_data`.

`message_data` : | a UniqueMessageData

### unique_message_data_set ()

    void                unique_message_data_set             (UniqueMessageData *message_data,
                                                             const guchar *data,
                                                             gsize length);

Sets `data` as the payload of `message_data`. Any other data is removed from the message data. If `data` is `NULL`, a `length` of -1 will unset the payload, while a `length` of 0 will set the payload to an empty string.

You can use `unique_message_data_get()` to retrieve the data.

`message_data` : | a UniqueMessageData
`data` : | binary blob to set, or `NULL`
`length` : | length of `data`

### unique_message_data_get ()

    const guchar *      unique_message_data_get             (UniqueMessageData *message_data,
                                                             gsize *length);

Retrieves the raw contents of `message_data` set using `unique_messaget_data_set()`.

`message_data` : | a UniqueMessageData
`length` : | return location for the length of the contents
Returns : | the contents of the message data or `NULL`. The returned string is owned by the UniqueMessageData and should never be modified or freed

Since 1.0.2

### unique_message_data_set_text ()

    gboolean            unique_message_data_set_text        (UniqueMessageData *message_data,
                                                             const gchar *str,
                                                             gssize length);

Sets `str` as the plain text payload of `message_data`, converting it to UTF-8 if needed. If `length` is -1, the length of the string will be used. Use `unique_message_data_get_text()` to retrieve the text.

`message_data` : | a UniqueMessageData
`str` : | plain text to be set as payload
`length` : | length of the text, or -1
Returns : | `TRUE` if the text was successfully converted to UTF-8

### unique_message_data_get_text ()

    gchar *             unique_message_data_get_text        (UniqueMessageData *message_data);

Retrieves the text set using `unique_message_data_set_text()`.

`message_data` : | a UniqueMessageData
Returns : | an allocated string.

### unique_message_data_set_uris ()

    gboolean            unique_message_data_set_uris        (UniqueMessageData *message_data,
                                                             gchar **uris);

Converts `uris` to a valid URI list and sets it as payload of `message_data`. You can use `unique_message_data_get_uris()` to retrieve the list from a UniqueMessageData.

`message_data` : | a UniqueMessageData
`uris` : | array zero-terminated=1) (element-type utf8. array zero-terminated=1. element-type utf8.
Returns : | `TRUE` if the URIs were successfully converted

### unique_message_data_get_uris ()

    gchar **            unique_message_data_get_uris        (UniqueMessageData *message_data);

Retrieves a `NULL`-terminated string vector containing the URIs set with `unique_message_data_set_uris()`.

`message_data` : | a UniqueMessageData
Returns : | an allocated list of URIs. Use `g_strfreev()` to free it.. array zero-terminated=1. element-type utf8. transfer full.

### unique_message_data_set_filename ()

    void                unique_message_data_set_filename    (UniqueMessageData *message_data,
                                                             const gchar *filename);

Sets `filename` as the contents of `message_data`.

`message_data` : | a UniqueMessageData
`filename` : | a filename

Since 1.0.2

### unique_message_data_get_filename ()

    gchar *             unique_message_data_get_filename    (UniqueMessageData *message_data);

Retrieves the filename set with `unique_message_data_set_filename()`.

`message_data` : | a UniqueMessageData
Returns : | a newly allocated string containing the filename. Use `g_free()` to free the resources used by the returned value.

Since 1.0.2

### unique_message_data_get_screen ()

    GdkScreen *         unique_message_data_get_screen      (UniqueMessageData *message_data);

Returns a pointer to the screen from where the message came. You can use `gtk_window_set_screen()` to move windows or dialogs to the right screen. This field is always set by the Unique library.

`message_data` : | a UniqueMessageData
Returns : | a GdkScreen

### unique_message_data_get_startup_id ()

    const gchar *       unique_message_data_get_startup_id  (UniqueMessageData *message_data);

Retrieves the startup notification id set inside `message_data`. This field is always set by the Unique library.

`message_data` : | a UniqueMessageData
Returns : | the startup notification id. The returned string is owned by the UniqueMessageData structure and should not be modified or freed

### unique_message_data_get_workspace ()

    guint               unique_message_data_get_workspace   (UniqueMessageData *message_data);

Retrieves the workspace number from where the message came. This field is always set by the Unique library.

`message_data` : | a UniqueMessageData
Returns : | the workspace number