## InfCommunicationMethod

InfCommunicationMethod — Network communication method

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | inf_communication_method_add_member ()
void | inf_communication_method_remove_member ()
gboolean | inf_communication_method_is_member ()
void | inf_communication_method_send_single ()
void | inf_communication_method_send_all ()
void | inf_communication_method_cancel_messages ()
InfCommunicationScope | inf_communication_method_received ()
void | inf_communication_method_enqueued ()
void | inf_communication_method_sent ()

## Signals

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

## Types and Values

| InfCommunicationMethod
struct | InfCommunicationMethodInterface

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