## InfCommunicationGroup

InfCommunicationGroup — Communication channel for mulitple connections

## Stability Level

Unstable, unless otherwise indicated

## Functions

const gchar * | inf_communication_group_get_name ()
InfCommunicationObject * | inf_communication_group_get_target ()
void | inf_communication_group_set_target ()
gboolean | inf_communication_group_is_member ()
void | inf_communication_group_send_message ()
void | inf_communication_group_send_group_message ()
void | inf_communication_group_cancel_messages ()
const gchar * | inf_communication_group_get_method_for_network ()
const gchar * | inf_communication_group_get_method_for_connection ()
gchar * | inf_communication_group_get_publisher_id ()

## Properties

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

## Signals

void | member-added | Run Last
void | member-removed | Run Last

## Types and Values

struct | InfCommunicationGroup
struct | InfCommunicationGroupClass

## Object Hierarchy

        GObject
        ╰── InfCommunicationGroup
            ├── InfCommunicationHostedGroup
            ╰── InfCommunicationJoinedGroup

## Includes

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

## 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.

## Functions

### inf_communication_group_get_name ()

    const gchar *
    inf_communication_group_get_name (InfCommunicationGroup *group);

Returns the name of the group.

#### Parameters

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.

#### Parameters

group | A InfCommunicationGroup. |

#### Returns

A InfCommunicationGroup, or `NULL`.

[transfer none][allow-none]

### 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.

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

group | A InfCommunicationGroup. |
connection | The InfXmlConnection to which to send the message. |
xml | The message to send. | [transfer full]

### 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` .

#### Parameters

group | A InfCommunicationGroup. |
xml | The message to send. | [transfer full]

### 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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

group | A InfCommunicationGroup. |
for_connection | A InfXmlConnection. |

#### Returns

The publisher's host ID. Free with `g_free()`.

[transfer full]

## Types and Values

### struct InfCommunicationGroup

    struct 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.

#### Members

`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. |

## Property Details

### The `“communication-manager”` property

      “communication-manager”    InfCommunicationManager *

The communication manager used for sending requests.

Owner: InfCommunicationGroup

Flags: Write / Construct Only

### The `“communication-registry”` property

      “communication-registry”   InfCommunicationRegistry *

The registry to register connections with.

Owner: InfCommunicationGroup

Flags: Write / Construct Only

### The `“name”` property

      “name”                     gchar *

The name of the group.

Owner: InfCommunicationGroup

Flags: Read / Write / Construct Only

Default value: NULL

### The `“target”` property

      “target”                   InfCommunicationObject *

The communication object to call on received and sent data.

Owner: InfCommunicationGroup

Flags: Read / Write

## Signal Details

### The `“member-added”` signal

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

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

#### Parameters

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

Flags: Run Last

### The `“member-removed”` signal

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

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

#### Parameters

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

Flags: Run Last