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,
                                                         gssize 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. [transfer full]

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,
                                                         gssize 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. [allow-none]

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. [out]

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 :

 a newly-allocated string. [transfer full]

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 :

 a list of URIs in a NULL-terminated string vector. [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 :

 a newly-allocated, NULL-terminated 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. [transfer full]

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. [transfer none]

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
Generated by GTK-Doc V1.16.1