InfCommunicationObject: libinfinity-0.7 Reference Manual

## InfCommunicationObject InfCommunicationObject — Network message destinations |

## Stability Level

Unstable, unless otherwise indicated

## Functions

InfCommunicationScope | inf_communication_object_received ()
void | inf_communication_object_enqueued ()
void | inf_communication_object_sent ()

## Types and Values

enum | InfCommunicationScope
| InfCommunicationObject
struct | InfCommunicationObjectInterface

## Object Hierarchy

        GEnum
        ╰── InfCommunicationScope
        GInterface
        ╰── InfCommunicationObject

## Prerequisites

InfCommunicationObject requires GObject.

## Known Implementations

InfCommunicationObject is implemented by InfAdoptedSession, InfChatSession, InfSession, InfcBrowser, InfcSessionProxy, InfdDirectory and InfdSessionProxy.

## Includes

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

## Description

A InfCommunicationObject is the destination of network messages sent through the InfCommunicationManager. Each InfCommunicationGroup is associated with InfCommunicationObject. Requests received by that group are reported to the InfCommunicationObject by calling `inf_communication_object_received()` on it. Messages sent to a member of that group (via `inf_communication_group_send_message()`) are also reported by calling `inf_communication_object_sent()`.

## Functions

### inf_communication_object_received ()

    InfCommunicationScope
    inf_communication_object_received (InfCommunicationObject *object,
                                       InfXmlConnection *conn,
                                       xmlNodePtr node);

This function is called when a InfCommunicationManager received data from `connection` belonging to a group whose communication object is `object` . This function should process the incoming data. If it could not process it, then it should set `error` .

It should return `INF_COMMUNICATION_SCOPE_GROUP` if the message is allowed to be forwarded to other group members. Since recipients of forwarded messages don't see the original sender (but just the forwarding host), forwarding arbitrary messages could lead to a security problem in the worst case.

For example, if, in central mode, a client sends an (invalid) <add-node> request to the whole (InfDirectory) group, and the server forwarded this to all clients, those clients would try to create a new node although the server rejected the request. In decentral mode, this is not a problem since all clients see where the message comes from, and can themselves reject all messages not coming from the server.

#### Parameters

object | A InfCommunicationObject. |
conn | The InfXmlConnection data was received from. |
node | The received data. |

#### Returns

`INF_COMMUNICATION_SCOPE_GROUP` if the message is allowed to be forwarded, `INF_COMMUNICATION_SCOPE_PTP` if not.

### inf_communication_object_enqueued ()

    void
    inf_communication_object_enqueued (InfCommunicationObject *object,
                                       InfXmlConnection *conn,
                                       xmlNodePtr node);

This function is called, when an XML message scheduled to be sent via `inf_communication_group_send_message()` or `inf_communication_group_send_group_message()` cannot be cancelled anymore, because it was already passed to `conn` .

#### Parameters

object | A InfCommunicationObject. |
conn | A InfXmlConnection. |
node | The XML data. |

### inf_communication_object_sent ()

    void
    inf_communication_object_sent (InfCommunicationObject *object,
                                   InfXmlConnection *conn,
                                   xmlNodePtr node);

This function is called when a XML message sent via `inf_communication_group_send_message()` or `inf_communication_group_send_group_message()` has actually been sent out.

#### Parameters

object | A InfCommunicationObject. |
conn | A InfXmlConnection. |
node | The sent data. |

## Types and Values

### enum InfCommunicationScope

InfCommunicationScope specifies to which hosts a message belongs.

#### Members

INF_COMMUNICATION_SCOPE_PTP | The message is sent from one group member to another. |
INF_COMMUNICATION_SCOPE_GROUP | The message is sent to all group members. |

### InfCommunicationObject

    typedef struct _InfCommunicationObject InfCommunicationObject;

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

### struct InfCommunicationObjectInterface

    struct InfCommunicationObjectInterface {
      InfCommunicationScope (*received)(InfCommunicationObject* object,
                                        InfXmlConnection* conn,
                                        xmlNodePtr node);

      void (*enqueued)(InfCommunicationObject* object,
                       InfXmlConnection* conn,
                       xmlNodePtr node);

      void (*sent)(InfCommunicationObject* object,
                   InfXmlConnection* conn,
                   xmlNodePtr node);
    };

The virtual methods of InfCommunicationObject. These are called by the InfCommunicationMethod when appropriate.

#### Members

`received` () | Called when a message for the group related to this InfCommunicationObject was received. |
`enqueued` () | Called when a message to be sent to another group member has been enqueued, which means sending it can no longer be cancelled via `inf_communication_group_cancel_messages()`. |
`sent` () | Called when a message has been sent to another group member of the group related no this InfCommunicationObject. |

## See Also

InfCommunicationManager