## InfdSessionProxy InfdSessionProxy |

## Synopsis

                        InfdSessionProxy;
    struct              InfdSessionProxyClass;
    InfSession *        infd_session_proxy_get_session      (InfdSessionProxy *proxy);
    InfUser *           infd_session_proxy_add_user         (InfdSessionProxy *proxy,
                                                             const GParameter *params,
                                                             guint n_params,
                                                             GError **error);
    void                infd_session_proxy_subscribe_to     (InfdSessionProxy *proxy,
                                                             InfXmlConnection *connection,
                                                             guint seq_id,
                                                             gboolean synchronize);
    gboolean            infd_session_proxy_has_subscriptions
                                                            (InfdSessionProxy *proxy);
    gboolean            infd_session_proxy_is_subscribed    (InfdSessionProxy *proxy,
                                                             InfXmlConnection *connection);
    gboolean            infd_session_proxy_is_idle          (InfdSessionProxy *proxy);

## Object Hierarchy

      GObject
       +----InfdSessionProxy

## Implemented Interfaces

InfdSessionProxy implements InfCommunicationObject.

## Properties

      "idle"                     gboolean              : Read
      "session"                  InfSession*           : Read / Write / Construct Only
      "subscription-group"       InfCommunicationHostedGroup*  : Read / Write / Construct Only

## Signals

      "add-subscription"                               : Run Last
      "remove-subscription"                            : Run Last

## Description

## Details

### InfdSessionProxy

    typedef struct _InfdSessionProxy InfdSessionProxy;

### struct InfdSessionProxyClass

    struct InfdSessionProxyClass {
      GObjectClass parent_class;

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

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

### infd_session_proxy_get_session ()

    InfSession *        infd_session_proxy_get_session      (InfdSessionProxy *proxy);

Returns the session proxied by `proxy`. Returns `NULL` if the session was closed.

`proxy` : | A InfdSessionProxy.
Returns : | A InfSession, or `NULL`.

### infd_session_proxy_add_user ()

    InfUser *           infd_session_proxy_add_user         (InfdSessionProxy *proxy,
                                                             const GParameter *params,
                                                             guint n_params,
                                                             GError **error);

Adds a local user to `proxy`'s session. `params` must not contain the 'id' property because it will be choosen by the proxy. Also, if the 'name' property is already in use by an existing, but unavailable user, this user will be re-used.

`proxy` : | A InfdSessionProxy.
`params` : | Construction properties for the InfUser (or derived) object.
`n_params` : | Number of parameters.
`error` : | Location to store error information.
Returns : | The InfUser that has been added, or `NULL` in case of an error.

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

`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_has_subscriptions ()

    gboolean            infd_session_proxy_has_subscriptions
                                                            (InfdSessionProxy *proxy);

Returns whether there are subscribed connections to the session.

`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.

`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).

`proxy` : | A InfdSessionProxy.
Returns : | Whether the session is idle.

## Property Details

### The `"idle"` property

      "idle"                     gboolean              : Read

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

Default value: TRUE

### The `"session"` property

      "session"                  InfSession*           : Read / Write / Construct Only

The underlying session.

### The `"subscription-group"` property

      "subscription-group"       InfCommunicationHostedGroup*  : Read / Write / Construct Only

The communication manager group of subscribed connections.

## Signal Details

### The `"add-subscription"` signal

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

Emitted every time a connection is subscribed to the session.

`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.

### The `"remove-subscription"` signal

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

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

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