libinfinity-0.6 Reference Manual: InfdSessionProxy

## InfdSessionProxy InfdSessionProxy — Server-side session management |

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | infd_session_proxy_subscribe_to ()
void | infd_session_proxy_unsubscribe ()
gboolean | infd_session_proxy_has_subscriptions ()
gboolean | infd_session_proxy_is_subscribed ()
gboolean | infd_session_proxy_is_idle ()

## Properties

gboolean | idle | Read
InfIo * | io | Read / Write / Construct Only
InfCommunicationHostedGroup * | subscription-group | Read / Write / Construct Only

## Signals

void | add-subscription | Run Last
gboolean | reject-user-join | Run Last
void | remove-subscription | Run Last

## Types and Values

struct | InfdSessionProxy
struct | InfdSessionProxyClass

## Object Hierarchy

        GObject
        ╰── InfdSessionProxy

## Implemented Interfaces

InfdSessionProxy implements InfCommunicationObject and InfSessionProxy.

## Includes

    #include <libinfinity/server/infd-session-proxy.h>

## Description

InfdSessionProxy is a manager for InfSession that is specific for the server side. The InfdSessionProxy manages exactly one InfSession. It is usually created by InfdDirectory when the content of a node is requested.

InfdSessionProxy allows to perform server-specific operations for the session it manages, such as joining a local user, or removing a connection from the list of subscribed connections. In addition it handles requests made by its counterpart, InfcSessionProxy, for the client side, such as remote user joins.

InfdSessionProxy implements the InfSessionProxy interface, which can be used to access the underlying InfSession or to join a local user.

## Functions

### infd_session_proxy_subscribe_to ()

    void
    infd_session_proxy_subscribe_to (InfdSessionProxy *proxy,
                                     InfXmlConnection *connection,
                                     guint seq_id,
                                     gboolean synchronize);

Subscribes `connection` to `proxy` 's session. The first thing that will be done is a synchronization (see `inf_session_synchronize_to()`). Then, all changes to the session are propagated to `connection` .

`seq_id` should be a unique number for `connection` , and the same number must be passed on the client side to the InfcSessionProxy object. Normally InfdDirectory and InfcBrowser take care of choosing an appropriate sequence identifier.

Normally, you want to set `synchronize` to `TRUE` in which case the whole session state will be synchronized to `connection` (within the subscription group). However, if for whatever reason the remote site already has a copy of the session, then you may set `synchronize` to `FALSE` to skip synchronization. This happens for example for newly created documents, or when the remote site synchronized the local site and wants to be initially subscribed.

If `proxy` 's session is not in `INF_SESSION_RUNNING` status, but in `INF_SESSION_SYNCHRONIZING`, then `connection` must be the connection that synchronizes the session and `synchronize` needs to be set to `FALSE`. This causes the synchronizing connection to initially be subscribed. This needs to be called directly after having created the session proxy (i.e. without returning to the main loop before) so that the synchronization connection is added to the subscription group for synchronization.

Otherwise a subscription can only be initiated if `proxy` 's session is in state `INF_SESSION_RUNNING`.

#### Parameters

proxy | A InfdSessionProxy. |
connection | A InfXmlConnection that is not yet subscribed. |
seq_id | The sequence identifier for `connection` . |
synchronize | If `TRUE`, then synchronize the session to `connection` first. |

### infd_session_proxy_unsubscribe ()

    void
    infd_session_proxy_unsubscribe (InfdSessionProxy *proxy,
                                    InfXmlConnection *connection);

Unsubscribes a subscribed connection from `proxy` 's session. This will prevent all users joined via `connection` to continue modifying the session's buffer, and it will cancel ongoing synchronization to `connection` , if not yet finished.

#### Parameters

proxy | A InfdSessionProxy. |
connection | The InfXmlConnection to unsubscribe. |

### infd_session_proxy_has_subscriptions ()

    gboolean
    infd_session_proxy_has_subscriptions (InfdSessionProxy *proxy);

Returns whether there are subscribed connections to the session.

#### Parameters

proxy | A InfdSessionProxy. |

#### Returns

Whether there are subscribed connections.

### infd_session_proxy_is_subscribed ()

    gboolean
    infd_session_proxy_is_subscribed (InfdSessionProxy *proxy,
                                      InfXmlConnection *connection);

Returns `TRUE` when `connection` is subscribed to the session and `FALSE` otherwise.

#### Parameters

proxy | A InfdSessionProxy. |
connection | The connection to check for being subscribed. |

#### Returns

Whether `connection` is subscribed.

### infd_session_proxy_is_idle ()

    gboolean
    infd_session_proxy_is_idle (InfdSessionProxy *proxy);

Returns whether the session is idle. The session is considered idle when there are no subscriptions and no synchronizations (in either direction).

#### Parameters

proxy | A InfdSessionProxy. |

#### Returns

Whether the session is idle.

## Types and Values

### struct InfdSessionProxy

    struct InfdSessionProxy;

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

### struct InfdSessionProxyClass

    struct InfdSessionProxyClass {
      /* Signals */
      void (*add_subscription)(InfdSessionProxy* proxy,
                               InfXmlConnection* connection,
                               guint seq_id);

      void (*remove_subscription)(InfdSessionProxy* proxy,
                                  InfXmlConnection* connection);

      gboolean (*reject_user_join)(InfdSessionProxy* proxy,
                                   InfXmlConnection* connection,
                                   const GArray* user_properties,
                                   InfUser* rejoin_user);
    };

This structure contains the default signal handlers of the InfdSessionProxy class.

#### Members

`add_subscription` () | Default signal handler for the “add-subscription” signal. |
`remove_subscription` () | Default signal handler for the “remove-subscription” signal. |
`reject_user_join` () | Default signal handler for the “reject-user-join” signal. |

## Property Details

### The `“idle”` property

      “idle”                     gboolean

The session is considered idle when are no subscriptions and no synchronizations.

Flags: Read

Default value: TRUE

### The `“io”` property

      “io”                       InfIo *

The InfIo object for scheduling events.

Flags: Read / Write / Construct Only

### The `“subscription-group”` property

      “subscription-group”       InfCommunicationHostedGroup *

The communication manager group of subscribed connections.

Flags: Read / Write / Construct Only

## Signal Details

### The `“add-subscription”` signal

    void
    user_function (InfdSessionProxy *proxy,
                   InfXmlConnection *connection,
                   guint             seq_id,
                   gpointer          user_data)

Emitted every time a connection is subscribed to the session.

#### Parameters

proxy | The InfdSessionProxy emitting the signal. |
connection | The subscribed InfXmlConnection. |
seq_id | The sequence identifier for `connection` as passed to `infd_session_proxy_subscribe_to()`. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“reject-user-join”` signal

    gboolean
    user_function (InfdSessionProxy *proxy,
                   InfXmlConnection *connection,
                   gpointer          user_properties,
                   InfUser          *rejoin_user,
                   gpointer          user_data)

This signal is emitted before every remote user join. The signal handler can return `TRUE` in which case the InfdSessionProxy does not allow the user join with `INF_REQUEST_ERROR_NOT_AUTHORIZED` error. If there is more than one signal handler, then if one of them returns `TRUE` the user join is rejected.

The `user_properties` parameter is a GArray of GParameter values. It contains the construct properties for the InfUser object that would be created if the user join is not rejected. It must not be modified, but it can be used to make the decision whether to reject the user join or not dependent on the parameters, such as allowing the user join only if the user has a predefined name. The function `inf_session_lookup_user_property()` can be used to look up a named parameter in the array.

#### Parameters

proxy | The InfdSessionProxy emitting the signal. |
connection | A subscribed InfXmlConnection requesting the user join. |
user_properties | An array with the properties for the new user. |
rejoin_user | The existing unavailable user that is being rejoined, or `NULL`. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“remove-subscription”` signal

    void
    user_function (InfdSessionProxy *proxy,
                   InfXmlConnection *connection,
                   gpointer          user_data)

Emitted every time a connection is unsubscribed to the session, or a subscription is removed because the session is closed.

#### Parameters

proxy | The InfdSessionProxy emitting the signal. |
connection | The unsubscribed InfXmlConnection. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

## See Also

InfSession