## InfCommunicationGroup InfCommunicationGroup — Communication channel for mulitple connections |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libinfinity/communication/inf-communication-group.h>

                        InfCommunicationGroup;
    struct              InfCommunicationGroupClass;
    const gchar *       inf_communication_group_get_name    (InfCommunicationGroup *group);
    InfCommunicationObject * inf_communication_group_get_target
                                                            (InfCommunicationGroup *group);
    void                inf_communication_group_set_target  (InfCommunicationGroup *group,
                                                             InfCommunicationObject *target);
    gboolean            inf_communication_group_is_member   (InfCommunicationGroup *group,
                                                             InfXmlConnection *connection);
    void                inf_communication_group_send_message
                                                            (InfCommunicationGroup *group,
                                                             InfXmlConnection *connection,
                                                             xmlNodePtr xml);
    void                inf_communication_group_send_group_message
                                                            (InfCommunicationGroup *group,
                                                             xmlNodePtr xml);
    void                inf_communication_group_cancel_messages
                                                            (InfCommunicationGroup *group,
                                                             InfXmlConnection *connection);
    const gchar *       inf_communication_group_get_method_for_network
                                                            (InfCommunicationGroup *group,
                                                             const gchar *network);
    const gchar *       inf_communication_group_get_method_for_connection
                                                            (InfCommunicationGroup *grp,
                                                             InfXmlConnection *conn);
    gchar *             inf_communication_group_get_publisher_id
                                                            (InfCommunicationGroup *group,
                                                             InfXmlConnection *for_connection);

## Object Hierarchy

      GObject
       +----InfCommunicationGroup
             +----InfCommunicationHostedGroup
             +----InfCommunicationJoinedGroup

## Properties

      "communication-manager"    InfCommunicationManager*  : Write / Construct Only
      "communication-registry"   InfCommunicationRegistry*  : Write / Construct Only
      "name"                     gchar*                : Read / Write / Construct Only
      "target"                   InfCommunicationObject*  : Read / Write

## Signals

      "member-added"                                   : Run Last
      "member-removed"                                 : Run Last

## Description

InfCommunicationGroup represents a group of different hosts. The group supports sending messages between group members and to the whole group.

A communication group supports multiple networks. Each connection belongs to a network, identified by the "network" property. It is assumed that hosts on different networks can't directly communicate with each other. Examples for networks are "tcp/ip" or "jabber".

All communication for a given network is performed by a InfCommunicationMethod. The method defines how data is sent is sent to the group. For example, a method could choose to relay all data via a central server, or to send all data directly between the hosts, or in case of a jabber network, use jabber groupchat functionality.

## Details

### InfCommunicationGroup

    typedef struct _InfCommunicationGroup InfCommunicationGroup;

InfCommunicationGroup is an opaque data type. You should only access it via the public API functions.

### struct InfCommunicationGroupClass

    struct InfCommunicationGroupClass {
      /* Signals */
      void (*member_added)(InfCommunicationGroup* group,
                           InfXmlConnection* connection);
      void (*member_removed)(InfCommunicationGroup* group,
                             InfXmlConnection* connection);

      /* Virtual functions */
      /* TODO: Should this be const gchar* const* get_methods? */
      const gchar* (*get_method)(InfCommunicationGroup* group,
                                 unsigned int index);
      gchar* (*get_publisher_id)(InfCommunicationGroup* group,
                                 InfXmlConnection* for_connection);
    };

The virtual methods and default signal handlers of InfCommunicationGroup.

`member_added` () | Default signal handler of the "member-added" signal.
`member_removed` () | Default signal handler of the "member-removed" signal.
`get_method` () | Virtual function to determine the methods to use for the group, in order of priority.
`get_publisher_id` () | Virtual function to obtain the ID of the publishing host of this group.

### inf_communication_group_get_name ()

    const gchar *       inf_communication_group_get_name    (InfCommunicationGroup *group);

Returns the name of the group.

`group` : | A InfCommunicationGroup.
Returns : | The name of the group. The returned string is owned by the group, you don't need to free it.

### inf_communication_group_get_target ()

    InfCommunicationObject * inf_communication_group_get_target
                                                            (InfCommunicationGroup *group);

Returns the group's target. The target of a group is the InfCommunicationObject to which received and sent messages are reported.

`group` : | A InfCommunicationGroup.
Returns : | A InfCommunicationGroup, or `NULL`.

### inf_communication_group_set_target ()

    void                inf_communication_group_set_target  (InfCommunicationGroup *group,
                                                             InfCommunicationObject *target);

Sets the group's target. The target of a group is the InfCommunicationObject to which received and sent messages are reported. If `target` is `NULL`, then the target will be unset.

You can safely call this function with an object that holds a reference on the group since the InfCommunicationGroup only holds a weak reference to its `target`. This means that you need to keep a reference on `target` yourself.

`group` : | A InfCommunicationGroup.
`target` : | A InfCommunicationObject, or `NULL`.

### inf_communication_group_is_member ()

    gboolean            inf_communication_group_is_member   (InfCommunicationGroup *group,
                                                             InfXmlConnection *connection);

Returns whether `connection` is a member of `group`.

`group` : | A InfCommunicationGroup.
`connection` : | A InfXmlConnection.
Returns : | `TRUE` if `connection` is a member of `group`, `FALSE` otherwise.

### inf_communication_group_send_message ()

    void                inf_communication_group_send_message
                                                            (InfCommunicationGroup *group,
                                                             InfXmlConnection *connection,
                                                             xmlNodePtr xml);

Sends a message `connection` which must be a member of `group`. `connection` needs to be a member of this group. This function takes ownership of `xml`.

`group` : | A InfCommunicationGroup.
`connection` : | The InfXmlConnection to which to send the message.
`xml` : | The message to send.

### inf_communication_group_send_group_message ()

    void                inf_communication_group_send_group_message
                                                            (InfCommunicationGroup *group,
                                                             xmlNodePtr xml);

Sends a message to all members of `group`. This function takes ownership of `xml`.

`group` : | A InfCommunicationGroup.
`xml` : | The message to send.

### inf_communication_group_cancel_messages ()

    void                inf_communication_group_cancel_messages
                                                            (InfCommunicationGroup *group,
                                                             InfXmlConnection *connection);

Stops all messages scheduled to be sent to `connection` from being sent. Messages for which `inf_communication_object_enqueued()` has already been called cannot be cancelled anymore.

`group` : | A InfCommunicationGroup.
`connection` : | The InfXmlConnection for which to cancel messages.

### inf_communication_group_get_method_for_network ()

    const gchar *       inf_communication_group_get_method_for_network
                                                            (InfCommunicationGroup *group,
                                                             const gchar *network);

Returns the method name of the method used for communication on `network` within `group`.

`group` : | A InfCommunicationGroup.
`network` : | A network specifier, such as "tcp/ip" or "jabber".
Returns : | A method name. The string is owned by the group, you don't need to free it.

### inf_communication_group_get_method_for_connection ()

    const gchar *       inf_communication_group_get_method_for_connection
                                                            (InfCommunicationGroup *grp,
                                                             InfXmlConnection *conn);

Returns the method name of the method used for communication on `conn`'s network within `group`. `conn` does not need to be a member of `grp` for this function to be called.

`grp` : | A InfCommunicationGroup.
`conn` : | The InfXmlConnection for which to retrieve the method.
Returns : | A method name. The string is owned by the group, you don't need to free it.

### inf_communication_group_get_publisher_id ()

    gchar *             inf_communication_group_get_publisher_id
                                                            (InfCommunicationGroup *group,
                                                             InfXmlConnection *for_connection);

Returns a host identifier for the group's publisher (see "local-id" and "remote-id"). If the local host is the publisher, then this will simply return `for_connection`'s local ID, otherwise the remote ID of the connection to the publisher on `for_connection`'s network is returned.

`group` : | A InfCommunicationGroup.
`for_connection` : | A InfXmlConnection.
Returns : | The publisher's host ID. Free with `g_free()`.

## Property Details

### The `"communication-manager"` property

      "communication-manager"    InfCommunicationManager*  : Write / Construct Only

The communication manager used for sending requests.

### The `"communication-registry"` property

      "communication-registry"   InfCommunicationRegistry*  : Write / Construct Only

The registry to register connections with.

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct Only

The name of the group.

Default value: NULL

### The `"target"` property

      "target"                   InfCommunicationObject*  : Read / Write

The communication object to call on received and sent data.

## Signal Details

### The `"member-added"` signal

    void                user_function                      (InfCommunicationGroup *group,
                                                            InfXmlConnection      *connection,
                                                            gpointer               user_data)       : Run Last

This signal is emitted when a connection has been added to the group.

`group` : | The InfCommunicationGroup emitting the signal.
`connection` : | The newly joined connection.
`user_data` : | user data set when the signal handler was connected.

### The `"member-removed"` signal

    void                user_function                      (InfCommunicationGroup *group,
                                                            InfXmlConnection      *connection,
                                                            gpointer               user_data)       : Run Last

This signal is emitted when a connection has been removed from the group.

`group` : | The InfCommunicationGroup emitting the signal.
`connection` : | The connection that was removed
`user_data` : | user data set when the signal handler was connected.