## InfAdoptedSession InfAdoptedSession — Session handling concurrency control via the adOPTed algorithm. |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libinfinity/adopted/inf-adopted-session.h>

    enum                InfAdoptedSessionError;
                        InfAdoptedSession;
    struct              InfAdoptedSessionClass;
    InfIo *             inf_adopted_session_get_io          (InfAdoptedSession *session);
    InfAdoptedAlgorithm * inf_adopted_session_get_algorithm (InfAdoptedSession *session);
    void                inf_adopted_session_broadcast_request
                                                            (InfAdoptedSession *session,
                                                             InfAdoptedRequest *request);
    void                inf_adopted_session_undo            (InfAdoptedSession *session,
                                                             InfAdoptedUser *user,
                                                             guint n);
    void                inf_adopted_session_redo            (InfAdoptedSession *session,
                                                             InfAdoptedUser *user,
                                                             guint n);
    gboolean            inf_adopted_session_read_request_info
                                                            (InfAdoptedSession *session,
                                                             xmlNodePtr xml,
                                                             InfAdoptedStateVector *diff_vec,
                                                             InfAdoptedUser **user,
                                                             InfAdoptedStateVector **time,
                                                             xmlNodePtr *operation,
                                                             GError **error);
    void                inf_adopted_session_write_request_info
                                                            (InfAdoptedSession *session,
                                                             InfAdoptedRequest *request,
                                                             InfAdoptedStateVector *diff_vec,
                                                             xmlNodePtr xml,
                                                             xmlNodePtr operation);

## Object Hierarchy

      GObject
       +----InfSession
             +----InfAdoptedSession

## Implemented Interfaces

InfAdoptedSession implements InfCommunicationObject.

## Properties

      "algorithm"                InfAdoptedAlgorithm*  : Read
      "io"                       InfIo*                : Read / Write / Construct Only
      "max-total-log-size"       guint                 : Read / Write / Construct Only

## Description

InfAdoptedSession handles concurrency control with an InfAdoptedAlgorithm on top of a InfSession. It takes care of sending all necessary information to joining users, receives requests from the network (passing them to InfAdoptedAlgorithm) and transfers local requests to the other users. It also makes sure to periodically send the state the local host is in to other uses even if the local users are idle (which is required for others to cleanup their request logs and request caches).

## Details

### enum InfAdoptedSessionError

    typedef enum {
      INF_ADOPTED_SESSION_ERROR_NO_SUCH_USER,
      INF_ADOPTED_SESSION_ERROR_MISSING_OPERATION,
      INF_ADOPTED_SESSION_ERROR_INVALID_REQUEST,

      INF_ADOPTED_SESSION_ERROR_MISSING_STATE_VECTOR,

      INF_ADOPTED_SESSION_ERROR_FAILED
    } InfAdoptedSessionError;

Error codes for InfAdoptedSession. These only occur when invalid requests are received from the network.

`INF_ADOPTED_SESSION_ERROR_NO_SUCH_USER` | The "user" field in a request message does not contain a valid user ID.
`INF_ADOPTED_SESSION_ERROR_MISSING_OPERATION` | A request message does not contain an operation.
`INF_ADOPTED_SESSION_ERROR_INVALID_REQUEST` | A request in a synchronized request log is invalid. Invalid means that it is not the request that was issued after the previous request in the log, or that it is an Undo or Redo request without a request to Undo or Redo, respectively.
`INF_ADOPTED_SESSION_ERROR_MISSING_STATE_VECTOR` | A synchronized user does not contain that the state that user currently is in.
`INF_ADOPTED_SESSION_ERROR_FAILED` | No further specified error code.

### InfAdoptedSession

    typedef struct _InfAdoptedSession InfAdoptedSession;

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

### struct InfAdoptedSessionClass

    struct InfAdoptedSessionClass {
      InfAdoptedRequest*(*xml_to_request)(InfAdoptedSession* session,
                                          xmlNodePtr xml,
                                          InfAdoptedStateVector* diff_vec,
                                          gboolean for_sync,
                                          GError** error);

      void(*request_to_xml)(InfAdoptedSession* session,
                            xmlNodePtr xml,
                            InfAdoptedRequest* request,
                            InfAdoptedStateVector* diff_vec,
                            gboolean for_sync);
    };

Virtual functions for InfAdoptedSession.

`xml_to_request` () | Virtual function to deserialize an InfAdoptedRequest from XML. The implementation of this function can use `inf_adopted_session_read_request_info()` to read the common info.
`request_to_xml` () | Virtual function to serialize an InfAdoptedRequest to XML. This function should add properties and children to the given XML node. At might use `inf_adopted_session_write_request_info()` to write the common info.

### inf_adopted_session_get_io ()

    InfIo *             inf_adopted_session_get_io          (InfAdoptedSession *session);

Returns the InfIo object of `session`.

`session` : | A InfAdoptedSession.
Returns : | A InfIo.

### inf_adopted_session_get_algorithm ()

    InfAdoptedAlgorithm * inf_adopted_session_get_algorithm (InfAdoptedSession *session);

Returns the InfAdoptedAlgorithm object of `session`. Returns `NULL` if `session` has status `INF_SESSION_PRESYNC` or `INF_SESSION_SYNCHRONIZING` because there the algorithm object is not yet created before successful synchronization.

`session` : | A InfAdoptedSession.
Returns : | A InfAdoptedAlgorithm, or `NULL`.

### inf_adopted_session_broadcast_request ()

    void                inf_adopted_session_broadcast_request
                                                            (InfAdoptedSession *session,
                                                             InfAdoptedRequest *request);

Sends a request to all subscribed connections. The request should originate from a call to `inf_adopted_algorithm_generate_request_noexec()`, `inf_adopted_algorithm_generate_request()`, `inf_adopted_algorithm_generate_undo()` or `inf_adopted_algorithm_generate_redo()` with `session`'s InfAdoptedAlgorithm.

`session` : | A InfAdoptedSession.
`request` : | A InfAdoptedRequest obtained from `session`'s algorithm.

### inf_adopted_session_undo ()

    void                inf_adopted_session_undo            (InfAdoptedSession *session,
                                                             InfAdoptedUser *user,
                                                             guint n);

This is a shortcut for creating `n` undo requests and broadcasting them. If `n` > 1 then this is also more efficient.

`session` : | A InfAdoptedSession.
`user` : | A local InfAdoptedUser.
`n` : | The number of undo requests to issue.

### inf_adopted_session_redo ()

    void                inf_adopted_session_redo            (InfAdoptedSession *session,
                                                             InfAdoptedUser *user,
                                                             guint n);

This is a shortcut for creating `n` redo requests and broadcasting them. If `n` > 1 then this is also more efficient.

`session` : | A InfAdoptedSession.
`user` : | A local InfAdoptedUser.
`n` : | The number of redo requests to issue.

### inf_adopted_session_read_request_info ()

    gboolean            inf_adopted_session_read_request_info
                                                            (InfAdoptedSession *session,
                                                             xmlNodePtr xml,
                                                             InfAdoptedStateVector *diff_vec,
                                                             InfAdoptedUser **user,
                                                             InfAdoptedStateVector **time,
                                                             xmlNodePtr *operation,
                                                             GError **error);

This function reads common information such as the state vector the request was made and the user that made the request from XML. It is most likely to be used by implementations of the xml_to_request virtual function.

`session` : | A InfAdoptedSession.
`xml` : | The XML to read the data from.
`diff_vec` : | The reference vector of the time vector of the request, or `NULL`.
`user` : | Location to store the user of the request, or `NULL`.
`time` : | Location to store the state the request was made, or `NULL`.
`operation` : | Location to store the operation of the request, or `NULL`.
`error` : | Location to place an error, if any.
Returns : | `TRUE` if the data could be read successfully, `FALSE` if the XML request does not contain valid request data, in which case `error` is set.

### inf_adopted_session_write_request_info ()

    void                inf_adopted_session_write_request_info
                                                            (InfAdoptedSession *session,
                                                             InfAdoptedRequest *request,
                                                             InfAdoptedStateVector *diff_vec,
                                                             xmlNodePtr xml,
                                                             xmlNodePtr operation);

This function writes common data from `request`, such as the user that issued the request and the state in which the request was made into `xml`. If `diff_vec` is given, then the state is written as a diff to this vector, see `inf_adopted_state_vector_to_string_diff()`. Deserializing this data again (via `inf_adopted_session_read_request_info()`) requires the same `diff_vec` then.

This function is most likely to be used by implementations of the request_to_xml virtual function.

`session` : | A InfAdoptedSession.
`request` : | The InfAdoptedRequest whose info to write.
`diff_vec` : | A reference state vector, or `NULL`.
`xml` : | The XML node to write the data into.
`operation` : | An XML node representing the operation of the request, or `NULL`.

## Property Details

### The `"algorithm"` property

      "algorithm"                InfAdoptedAlgorithm*  : Read

The adOPTed algorithm used for translating incoming requests.

### The `"io"` property

      "io"                       InfIo*                : Read / Write / Construct Only

The IO object used for timeouts.

### The `"max-total-log-size"` property

      "max-total-log-size"       guint                 : Read / Write / Construct Only

The maximum number of requests to keep in all user's logs.

Default value: 2048

## See Also

InfSession, InfAdoptedAlgorithm