Message Data

Message Data — Message container for UniqueApp

Functions

Types and Values

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().

Functions

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 .

Parameters

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 .

Parameters

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.

Parameters

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().

Parameters

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.

Parameters

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().

Parameters

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.

Parameters

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().

Parameters

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 .

Parameters

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().

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

message_data

a UniqueMessageData

 

Returns

the workspace number

Types and Values

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.