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.