InfCommunicationMethod

InfCommunicationMethod — Network communication method

Stability Level

Unstable, unless otherwise indicated

Functions

Signals

void add-member Run Last
void remove-member Run Last

Types and Values

Object Hierarchy

    GInterface
    ╰── InfCommunicationMethod

Prerequisites

InfCommunicationMethod requires GObject.

Known Implementations

InfCommunicationMethod is implemented by InfCommunicationCentralMethod.

Includes

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

Description

A InfCommunicationMethod specifies how messages are transferred between group members on the same network. So one method handles all connections on a specific network for the group.

Functions

inf_communication_method_add_member ()

void
inf_communication_method_add_member (InfCommunicationMethod *method,
                                     InfXmlConnection *connection);

Adds a new connection to the group. The network of connection must match the network the method is handling, and connection must not already be a member of the group (see inf_communication_method_is_member()).

Parameters

method

A InfCommunicationMethod.

 

connection

The InfXmlConnection to add.

 

inf_communication_method_remove_member ()

void
inf_communication_method_remove_member
                               (InfCommunicationMethod *method,
                                InfXmlConnection *connection);

Removes a connection from the group. connection needs to be a member of the group (see inf_communication_method_is_member()).

Parameters

method

A InfCommunicationMethod.

 

connection

The InfXmlConnection to remove.

 

inf_communication_method_is_member ()

gboolean
inf_communication_method_is_member (InfCommunicationMethod *method,
                                    InfXmlConnection *connection);

Returns whether connection was added to the group via inf_communication_method_add_member().

Parameters

method

A InfCommunicationMethod.

 

connection

A InfXmlConnection.

 

Returns

Whether connection is a member of the group.


inf_communication_method_send_single ()

void
inf_communication_method_send_single (InfCommunicationMethod *method,
                                      InfXmlConnection *connection,
                                      xmlNodePtr xml);

Sends an XML message to connection . This function takes ownership of xml .

Parameters

method

A InfCommunicationMethod.

 

connection

A InfXmlConnection that is a group member.

 

xml

The message to send.

[transfer full]

inf_communication_method_send_all ()

void
inf_communication_method_send_all (InfCommunicationMethod *method,
                                   xmlNodePtr xml);

Sends an XML message to all group members on this network. This function takes ownership of xml .

Parameters

method

A InfCommunicationMethod.

 

xml

The message to send.

[transfer full]

inf_communication_method_cancel_messages ()

void
inf_communication_method_cancel_messages
                               (InfCommunicationMethod *method,
                                InfXmlConnection *connection);

This function stops all messages to be sent to connection that have not yet been sent.

Parameters

method

A InfCommunicationMethod.

 

connection

A InfXmlConnection that is a group member.

 

inf_communication_method_received ()

InfCommunicationScope
inf_communication_method_received (InfCommunicationMethod *method,
                                   InfXmlConnection *connection,
                                   xmlNodePtr xml);

This function is called by the InfCommunicationRegistry if data has been received on registered connections (see inf_communication_registry_register()).

This function returns the scope of the message. If the scope is INF_COMMUNICATION_SCOPE_GROUP then the registry relays the message to other connections on different networks (if any).

Parameters

method

A InfCommunicationMethod.

 

connection

A InfXmlConnection that is a group member.

 

xml

The received message.

 

Returns

The scope of the message.


inf_communication_method_enqueued ()

void
inf_communication_method_enqueued (InfCommunicationMethod *method,
                                   InfXmlConnection *connection,
                                   xmlNodePtr xml);

This function is called by the InfCommunicationRegistry if data has been enqueued on registered connections (see inf_communication_registry_register()).

Parameters

method

A InfCommunicationMethod.

 

connection

A InfXmlConnection.

 

xml

The enqueued message.

 

inf_communication_method_sent ()

void
inf_communication_method_sent (InfCommunicationMethod *method,
                               InfXmlConnection *connection,
                               xmlNodePtr xml);

This function is called by the InfCommunicationRegistry if data has been sent on registered connections (see inf_communication_registry_register()).

Parameters

method

A InfCommunicationMethod.

 

connection

A InfXmlConnection.

 

xml

The sent message.

 

Types and Values

InfCommunicationMethod

typedef struct _InfCommunicationMethod InfCommunicationMethod;

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


struct InfCommunicationMethodInterface

struct InfCommunicationMethodInterface {
  /* Signals */
  void (*add_member)(InfCommunicationMethod* method,
                     InfXmlConnection* connection);
  void (*remove_member)(InfCommunicationMethod* method,
                        InfXmlConnection* connection);

  /* Virtual functions */
  gboolean (*is_member)(InfCommunicationMethod* method,
                        InfXmlConnection* connection);

  void (*send_single)(InfCommunicationMethod* method,
                      InfXmlConnection* connection,
                      xmlNodePtr xml);
  void (*send_all)(InfCommunicationMethod* method,
                   xmlNodePtr xml);
  void (*cancel_messages)(InfCommunicationMethod* method,
                          InfXmlConnection* connection);

  InfCommunicationScope (*received)(InfCommunicationMethod* method,
                                    InfXmlConnection* connection,
                                    xmlNodePtr xml);
  void (*enqueued)(InfCommunicationMethod* method,
                   InfXmlConnection* connection,
                   xmlNodePtr xml);
  void (*sent)(InfCommunicationMethod* method,
               InfXmlConnection* connection,
               xmlNodePtr xml);
};

The default signal handlers of virtual methods of InfCommunicationMethod. These implement communication within a InfCommunicationGroup.

Members

add_member ()

Default signal handler of the “add-member” signal.

 

remove_member ()

Default signal handler of the “remove-member” signal.

 

is_member ()

Returns whether the given connection is a member of the group.

 

send_single ()

Sends a message to a single connection. Takes ownership of xml .

 

send_all ()

Sends a message to all group members, except except . Takes ownership of xml .

 

cancel_messages ()

Cancel sending messages that have not yet been sent to the given connection.

 

received ()

Handles reception of a message from a registered connection. This normally includes informing a group's NetObject and forwarding the message to other group members.

 

enqueued ()

Handles when a message has been enqueued to be sent on a registered connection.

 

sent ()

Handles when a message has been sent to a registered connection.

 

Signal Details

The “add-member” signal

void
user_function (InfCommunicationMethod *method,
               InfXmlConnection       *connection,
               gpointer                user_data)

This signal is emitted whenever a new connection has been added to the group on the network this method handles.

Parameters

method

The InfCommunicationMethod emitting the signal.

 

connection

The InfXmlConnection that was added.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “remove-member” signal

void
user_function (InfCommunicationMethod *method,
               InfXmlConnection       *connection,
               gpointer                user_data)

This signal is emitted whenever a connection has been removed from the group on the network this method handles.

Parameters

method

The InfCommunicationMethod emitting the signal.

 

connection

The InfXmlConnection that was removed.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

See Also

InfCommunicationManager