InfCommunicationGroup

InfCommunicationGroup — Communication channel for mulitple connections

Stability Level

Unstable, unless otherwise indicated

Functions

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

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