IrisMessage

IrisMessage — A generic message representation

Synopsis

#define             IRIS_TYPE_MESSAGE
                    IrisMessage;
GType               iris_message_get_type               (void);
IrisMessage*        iris_message_new                    (gint what);
IrisMessage*        iris_message_new_data               (gint what,
                                                         GType type,
                                                         ...);
IrisMessage*        iris_message_new_full               (gint what,
                                                         const gchar *first_name,
                                                         ...);
IrisMessage*        iris_message_ref                    (IrisMessage *message);
void                iris_message_unref                  (IrisMessage *message);
IrisMessage*        iris_message_copy                   (IrisMessage *message);
const GValue*       iris_message_get_data               (IrisMessage *message);
void                iris_message_set_data               (IrisMessage *message,
                                                         const GValue *value);
guint               iris_message_count_names            (IrisMessage *message);
gboolean            iris_message_is_empty               (IrisMessage *message);
gboolean            iris_message_contains               (IrisMessage *message,
                                                         const gchar *name);
void                iris_message_get_value              (IrisMessage *message,
                                                         const gchar *name,
                                                         GValue *value);
void                iris_message_set_value              (IrisMessage *message,
                                                         const gchar *name,
                                                         const GValue *value);
const gchar*        iris_message_get_string             (IrisMessage *message,
                                                         const gchar *name);
void                iris_message_set_string             (IrisMessage *message,
                                                         const gchar *name,
                                                         const gchar *value);
gint                iris_message_get_int                (IrisMessage *message,
                                                         const gchar *name);
void                iris_message_set_int                (IrisMessage *message,
                                                         const gchar *name,
                                                         gint value);
gint64              iris_message_get_int64              (IrisMessage *message,
                                                         const gchar *name);
void                iris_message_set_int64              (IrisMessage *message,
                                                         const gchar *name,
                                                         gint64 value);
gfloat              iris_message_get_float              (IrisMessage *message,
                                                         const gchar *name);
void                iris_message_set_float              (IrisMessage *message,
                                                         const gchar *name,
                                                         gfloat value);
gdouble             iris_message_get_double             (IrisMessage *message,
                                                         const gchar *name);
void                iris_message_set_double             (IrisMessage *message,
                                                         const gchar *name,
                                                         gdouble value);
glong               iris_message_get_long               (IrisMessage *message,
                                                         const gchar *name);
void                iris_message_set_long               (IrisMessage *message,
                                                         const gchar *name,
                                                         glong value);
gulong              iris_message_get_ulong              (IrisMessage *message,
                                                         const gchar *name);
void                iris_message_set_ulong              (IrisMessage *message,
                                                         const gchar *name,
                                                         gulong value);
gchar               iris_message_get_char               (IrisMessage *message,
                                                         const gchar *name);
void                iris_message_set_char               (IrisMessage *message,
                                                         const gchar *name,
                                                         gchar value);
guchar              iris_message_get_uchar              (IrisMessage *message,
                                                         const gchar *name);
void                iris_message_set_uchar              (IrisMessage *message,
                                                         const gchar *name,
                                                         guchar value);
gboolean            iris_message_get_boolean            (IrisMessage *message,
                                                         const gchar *name);
void                iris_message_set_boolean            (IrisMessage *message,
                                                         const gchar *name,
                                                         gboolean value);
gpointer            iris_message_get_pointer            (IrisMessage *message,
                                                         const gchar *name);
void                iris_message_set_pointer            (IrisMessage *message,
                                                         const gchar *name,
                                                         gpointer value);

Description

IrisMessage is the representation of a message that can be passed within a process. It is typically delivered to a port which can help provide actions based on the message. IrisMessage's contain a set of key/value pairs that describe the message. The message itself also has a type, which is defined by the public "what" member of the IrisMessage struct.

Since messages can be expensive, they are reference counted. You can control the lifetime of an IrisMessage using iris_message_ref() and iris_message_unref().

You can add key/values to the message using methods such as iris_message_set_string() and iris_message_set_value(). There are helpers for most base types within GLib. For complex types, use iris_message_set_value() containing a GValue with the complex type.

Named keys uses a hashtable internally which may be more of an expensive operation than is desired. IrisMessage provides a way to pack the data into the message using iris_message_set_data(). For light-weight messages containing a single value this is preferred.

Updating the structure is not thread-safe. Generally it is not recommended to modify a message after passing it.

Details

IRIS_TYPE_MESSAGE

#define IRIS_TYPE_MESSAGE (iris_message_get_type())

IrisMessage

typedef struct {
	gint            what;
} IrisMessage;

iris_message_get_type ()

GType               iris_message_get_type               (void);

Returns :

iris_message_new ()

IrisMessage*        iris_message_new                    (gint what);

Creates a new IrisMessage. what can be any constant used within your application that the local or remote application knows how to handle.

what :

 the message type

Returns :

 the newly created IrisMessage.

iris_message_new_data ()

IrisMessage*        iris_message_new_data               (gint what,
                                                         GType type,
                                                         ...);

Creates a new IrisMessage instance with the data value initialized. The ellipsis parameter is used so you may pass any type of value or pointer into the constructor, however only one is allowed.

what :

 The message type

type :

 the GType of the data element

... :

Returns :

 The newly created IrisMessage instance

iris_message_new_full ()

IrisMessage*        iris_message_new_full               (gint what,
                                                         const gchar *first_name,
                                                         ...);

Creates a new instance of a IrisMessage and sets its fields.

what :

 the message type

first_name :

 the name of the first field in the message

... :

 the GType and value for the first property, followed optionally by more name/type/value triplets, follwed by NULL

Returns :

 a new instance of IrisMessage.

iris_message_ref ()

IrisMessage*        iris_message_ref                    (IrisMessage *message);

Atomically Increases the reference count of message by one.

message :

 a IrisMessage

Returns :

 the passed IrisMessage, with the reference count increased by one.

iris_message_unref ()

void                iris_message_unref                  (IrisMessage *message);

Atomically decrease the reference count of an IrisMessage. If the reference count reaches zero, the object is destroyed and all its allocated resources are freed.

message :

 An IrisMessage

iris_message_copy ()

IrisMessage*        iris_message_copy                   (IrisMessage *message);

Copies message. If the node contains complex data types then the reference count of the objects are increased.

message :

 An IrisMessage

Returns :

 the copied IrisMessage.

iris_message_get_data ()

const GValue*       iris_message_get_data               (IrisMessage *message);

Retrieves the data value for the IrisMessage. A message may have one data value within it that is not associated with a key. This is that value.

message :

 An IrisMessage

Returns :

 A pointer to a GValue that should not be modified.

iris_message_set_data ()

void                iris_message_set_data               (IrisMessage *message,
                                                         const GValue *value);

Updates the data field for the message. A message may have only one data value within it that is not associated with a key. This is that value.

message :

 An IrisMessage

value :

 A GValue

iris_message_count_names ()

guint               iris_message_count_names            (IrisMessage *message);

Retrieves the number of key/value pairs that are currently stored within the message.

message :

 An IrisMessage

Returns :

 the number of key/value pairs

iris_message_is_empty ()

gboolean            iris_message_is_empty               (IrisMessage *message);

Checks to see if the message is currently empty, meaning it has no key/value pairs associated.

message :

 An IrisMessage

Returns :

 TRUE if there are no key/value pairs associated.

iris_message_contains ()

gboolean            iris_message_contains               (IrisMessage *message,
                                                         const gchar *name);

Checks to see if message contains a field named name.

message :

 An IrisMessage

name :

 the name to lookup

Returns :

 TRUE if the message contains name

iris_message_get_value ()

void                iris_message_get_value              (IrisMessage *message,
                                                         const gchar *name,
                                                         GValue *value);

Copies the value found using name as the key into the GValue pointed to by value. Remember to unset your value using g_value_unset() when you are done.

message :

 An IrisMessage

name :

 the name of the value to retrieve

value :

 a GValue to store the result in

iris_message_set_value ()

void                iris_message_set_value              (IrisMessage *message,
                                                         const gchar *name,
                                                         const GValue *value);

Updates the value for key to use the value pointed to by value.

message :

 An IrisMessage

name :

 the name of the key

value :

 A GValue containing the new value

iris_message_get_string ()

const gchar*        iris_message_get_string             (IrisMessage *message,
                                                         const gchar *name);

Retrieves the value for key which must be a string.

message :

 An IrisMessage

name :

 The key of the item

Returns :

 a string containing the value for key.

iris_message_set_string ()

void                iris_message_set_string             (IrisMessage *message,
                                                         const gchar *name,
                                                         const gchar *value);

Updates the key for message to the string pointed to by value. The contents of the string is duplicated and stored within the message.

message :

 An IrisMessage

name :

 the key

value :

 a string

iris_message_get_int ()

gint                iris_message_get_int                (IrisMessage *message,
                                                         const gchar *name);

Retrieves the value for key.

message :

 An IrisMessage

name :

 the key

Returns :

 the value for key as a gint.

iris_message_set_int ()

void                iris_message_set_int                (IrisMessage *message,
                                                         const gchar *name,
                                                         gint value);

Updates message to use value as the value for key.

message :

 An IrisMessage

name :

 the key

value :

 the value

iris_message_get_int64 ()

gint64              iris_message_get_int64              (IrisMessage *message,
                                                         const gchar *name);

Retrieves the value for key.

message :

 An IrisMessage

name :

 the key

Returns :

 the value for key as a gint64.

iris_message_set_int64 ()

void                iris_message_set_int64              (IrisMessage *message,
                                                         const gchar *name,
                                                         gint64 value);

Updates message to use value as the value for key.

message :

 An IrisMessage

name :

 the key

value :

 the value

iris_message_get_float ()

gfloat              iris_message_get_float              (IrisMessage *message,
                                                         const gchar *name);

Retrieves the value for key.

message :

 An IrisMessage

name :

 the key

Returns :

 the value for key as a gfloat.

iris_message_set_float ()

void                iris_message_set_float              (IrisMessage *message,
                                                         const gchar *name,
                                                         gfloat value);

Updates message to use value as the value for key.

message :

 An IrisMessage

name :

 the key

value :

 the value

iris_message_get_double ()

gdouble             iris_message_get_double             (IrisMessage *message,
                                                         const gchar *name);

Retrieves the value for key.

message :

 An IrisMessage

name :

 the key

Returns :

 the value for key as a gdouble.

iris_message_set_double ()

void                iris_message_set_double             (IrisMessage *message,
                                                         const gchar *name,
                                                         gdouble value);

Updates message to use value as the value for key.

message :

 An IrisMessage

name :

 the key

value :

 the value

iris_message_get_long ()

glong               iris_message_get_long               (IrisMessage *message,
                                                         const gchar *name);

Retrieves the value for key.

message :

 An IrisMessage

name :

 the key

Returns :

 the value for key

iris_message_set_long ()

void                iris_message_set_long               (IrisMessage *message,
                                                         const gchar *name,
                                                         glong value);

Updates message to use value as the value for key.

message :

 An IrisMessage

name :

 the key

value :

 the value

iris_message_get_ulong ()

gulong              iris_message_get_ulong              (IrisMessage *message,
                                                         const gchar *name);

Retrieves the value for key.

message :

 An IrisMessage

name :

 the key

Returns :

 the value for key

iris_message_set_ulong ()

void                iris_message_set_ulong              (IrisMessage *message,
                                                         const gchar *name,
                                                         gulong value);

Updates message to use value as the value for key.

message :

 An IrisMessage

name :

 the key

value :

 the value

iris_message_get_char ()

gchar               iris_message_get_char               (IrisMessage *message,
                                                         const gchar *name);

Retrieves the value for key.

message :

 An IrisMessage

name :

 the key

Returns :

 the value for key

iris_message_set_char ()

void                iris_message_set_char               (IrisMessage *message,
                                                         const gchar *name,
                                                         gchar value);

Updates message to use value as the value for key.

message :

 An IrisMessage

name :

 the key

value :

 the value

iris_message_get_uchar ()

guchar              iris_message_get_uchar              (IrisMessage *message,
                                                         const gchar *name);

Retrieves the value for key.

message :

 An IrisMessage

name :

 the key

Returns :

 the value for key

iris_message_set_uchar ()

void                iris_message_set_uchar              (IrisMessage *message,
                                                         const gchar *name,
                                                         guchar value);

Updates message to use value as the value for key.

message :

 An IrisMessage

name :

 the key

value :

 the value

iris_message_get_boolean ()

gboolean            iris_message_get_boolean            (IrisMessage *message,
                                                         const gchar *name);

Retrieves the value for key.

message :

 An IrisMessage

name :

 the key

Returns :

 the value for key

iris_message_set_boolean ()

void                iris_message_set_boolean            (IrisMessage *message,
                                                         const gchar *name,
                                                         gboolean value);

Updates message to use value as the value for key.

message :

 An IrisMessage

name :

 the key

value :

 the value

iris_message_get_pointer ()

gpointer            iris_message_get_pointer            (IrisMessage *message,
                                                         const gchar *name);

Retrieves the value for key.

message :

 An IrisMessage

name :

 the key

Returns :

 the value for key

iris_message_set_pointer ()

void                iris_message_set_pointer            (IrisMessage *message,
                                                         const gchar *name,
                                                         gpointer value);

Updates message to use value as the value for key.

message :

 An IrisMessage

name :

 the key

value :

 the value
Generated by GTK-Doc V1.11