Infinity.Session¶

Subclasses:: Infinity.AdoptedSession, Infinity.ChatSession

Methods¶

Inherited:: GObject.Object (37), Infinity.CommunicationObject (3)
Structs:: GObject.ObjectClass (5)

class	`get_user_property` (array, name)
class	`lookup_user_property` (params, name)
	`add_user` (params)
	`cancel_synchronization` (connection)
	`close` ()
	`get_buffer` ()
	`get_communication_manager` ()
	`get_status` ()
	`get_subscription_group` ()
	`get_synchronization_progress` (connection)
	`get_synchronization_status` (connection)
	`get_user_table` ()
	`has_synchronizations` ()
	`send_to_subscriptions` (xml)
	`set_subscription_group` (group)
	`set_user_status` (user, status)
	`synchronize_from` ()
	`synchronize_to` (group, connection)
	`user_to_xml` (user, xml)

Virtual Methods¶

Inherited:: GObject.Object (7), Infinity.CommunicationObject (3)

	`do_close` ()
	`do_error` (connection, xml, error)
	`do_process_xml_run` (connection, xml)
	`do_process_xml_sync` (connection, xml)
	`do_set_xml_user_props` (params, n_params, xml)
	`do_synchronization_begin` (group, connection)
	`do_synchronization_complete` (connection)
	`do_synchronization_failed` (connection, error)
	`do_synchronization_progress` (connection, percentage)
	`do_to_xml_sync` (parent)
	`do_validate_user_props` (params, n_params, exclude)

Properties¶

Name	Type	Flags	Short Description
`buffer`	`Infinity.Buffer`	r/w/co	The buffer in which the document content is stored
`communication-manager`	`Infinity.CommunicationManager`	r/w/co	The communication manager used for sending requests
`status`	`Infinity.SessionStatus`	r/w/co	Current status of the session
`subscription-group`	`Infinity.CommunicationGroup`	r/w	Communication group of subscribed connections
`sync-connection`	`Infinity.XmlConnection`	r/w/co	Connection which synchronizes the initial session state
`sync-group`	`Infinity.CommunicationGroup`	r/w/co	Communication group in which to perform synchronization
`user-table`	`Infinity.UserTable`	r/w/co	User table containing the users of the session

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`close`	This signal is emitted if the session is closed.
`error`	This signal is emitted when the session detects an error.
`synchronization-begin`	This signal is emitted whenever the session is started to be synchronized to another connection.
`synchronization-complete`	This signal is emitted when synchronization has completed, in addition to `Infinity.Session` `::synchronization-progress` with a progress value of 1.0.
`synchronization-failed`	This signal is emitted when synchronization has failed before its completion due to malformed data from the other side or network failure.
`synchronization-progress`	This signal is emitted whenever a new XML node has been sent or received over connection as part of a synchronization.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class Infinity.Session(**kwargs)¶

Bases:: GObject.Object, Infinity.CommunicationObject
Abstract:: No
Structure:: Infinity.SessionClass

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

classmethod get_user_property(array, name)¶

Parameters:

array ([GObject.Parameter]) – A GLib.Array containing GObject.Parameter values.
name (str) – Name to look up.

Returns:

A GObject.Parameter.

Return type:

GObject.Parameter

Looks up the paremeter with the given name in array. If there is no such parameter, a new one will be created.

classmethod lookup_user_property(params, name)¶

Parameters:

params ([GObject.Parameter]) – A pointer to an array of containing GObject.Parameter values.
name (str) – Name to look up.

Returns:

A GObject.Parameter, or None.

Return type:

GObject.Parameter

Looks up the parameter with the given name in array.

add_user(params)¶

Parameters:: params ([GObject.Parameter]) – Construction parameters for the Infinity.User (or derived) object.
Returns:: The new Infinity.User.
Return type:: Infinity.User

Adds a user to self. The user object is constructed via the user_new vfunc of Infinity.SessionClass. This will create a new Infinity.User object by default, but may be overridden by subclasses to create different kinds of users.

Note that this function does not tell the other participants that the user was added. To avoid conflicts, normally only the publisher of the session can add users and notifies others accordingly. This is handled by #InfdSessionProxy or #InfcSessionProxy, respectively.

You should not call this function unless you know what you are doing. If params comes from an untrusted source, they should be checked first with the validate_user_props virtual function.

cancel_synchronization(connection)¶

Parameters:: connection (Infinity.XmlConnection) – The Infinity.XmlConnection with which to cancel synchronization.

Cancells an ongaing synchronization to or from connection. If self is in state Infinity.SessionStatus.PRESYNC or Infinity.SessionStatus.SYNCHRONIZING, connection must match the connection that self is synchronizing with. If self is in state Infinity.SessionStatus.RUNNING, connection can be any connection that the session is currently being synchronized to.

In any case, the Infinity.Session ::synchronization-failed signal will be emitted for the cancelled synchronization. If the session is in state Infinity.SessionStatus.PRESYNC or Infinity.SessionStatus.SYNCHRONIZING, the session will also be closed, with the Infinity.Session ::close signal being emited.

close()¶: Closes a running session. When a session is closed, it unrefs all connections and no longer handles requests.

get_buffer()¶

Returns:: A Infinity.Buffer.
Return type:: Infinity.Buffer

Returns the buffer used by self.

get_communication_manager()¶

Returns:: A Infinity.CommunicationManager.
Return type:: Infinity.CommunicationManager

Returns the communication manager for self.

get_status()¶

Returns:: The status of self.
Return type:: Infinity.SessionStatus

Returns the session’s status.

get_subscription_group()¶

Returns:: A Infinity.CommunicationGroup, or None.
Return type:: Infinity.CommunicationGroup

Returns the subscription group for self, if any.

get_synchronization_progress(connection)¶

Parameters:: connection (Infinity.XmlConnection) – A Infinity.XmlConnection.
Returns:: A value between 0.0 and 1.0.
Return type:: float

This function requires that the synchronization status of connection is Infinity.SessionSyncStatus.IN_PROGRESS or Infinity.SessionSyncStatus.AWAITING_ACK (see Infinity.Session.get_synchronization_status()). Then, it returns a value between 0.0 and 1.0 specifying how much synchronization data has already been transferred to the remote site.

Note that if the session is in status Infinity.SessionStatus.RUNNING, it is possible that this function returns 1.0 (i.e. all data has been transmitted) but the synchronization is not yet complete, because the remote site must still acknowledge the synchronization. The synchronization then is in status Infinity.SessionSyncStatus.AWAITING_ACK.

get_synchronization_status(connection)¶

Parameters:: connection (Infinity.XmlConnection) – A Infinity.XmlConnection.
Returns:: The synchronization status of connection.
Return type:: Infinity.SessionSyncStatus

If self is in status Infinity.SessionStatus.SYNCHRONIZING, this always returns Infinity.SessionSyncStatus.IN_PROGRESS if connection is the connection with which the session is synchronized, and Infinity.SessionSyncStatus.NONE otherwise.

If self is in status Infinity.SessionStatus.RUNNING, this returns the status of the synchronization to connection. Infinity.SessionSyncStatus.NONE is returned, when there is currently no synchronization ongoing to connection, Infinity.SessionSyncStatus.IN_PROGRESS is returned, if there is one, and Infinity.SessionSyncStatus.AWAITING_ACK if the synchronization is finished but we are waiting for the acknowledgement from the remote site that all synchronization data has been progressed successfully. The synchronization can still fail in this state but it can no longer by cancelled.

If self is in status $:obj:Infinity.SessionStatus.CLOSED, this always returns Infinity.SessionSyncStatus.NONE.

get_user_table()¶

Returns:: A Infinity.UserTable.
Return type:: Infinity.UserTable

Returns the user table used by self.

has_synchronizations()¶

Returns:: Whether there are ongoing synchronizations.
Return type:: bool

Returns whether there are currently ongoing synchronizations. If the session is in status Infinity.SessionStatus.SYNCHRONIZING, then this returns always True, if it is in Infinity.SessionStatus.CLOSED, then it returns always False. If the session is in status Infinity.SessionStatus.RUNNING, then it returns True when the session is currently at least synchronized to one connection and False otherwise.

send_to_subscriptions(xml)¶

Parameters:: xml (libxml2.NodePtr) – The message to send.

Sends a XML message to the all members of self's subscription group. This function can only be called if the subscription group is non-None. It takes ownership of xml.

set_subscription_group(group)¶

Parameters:: group (Infinity.CommunicationGroup) – A Infinity.CommunicationGroup.

Sets the subscription group for self. The subscription group is the group in which all connections subscribed to the session are a member of.

Infinity.Session itself does not deal with subscriptions, so it is your job to keep group up-to-date (for example if you add non-local users to self). This is normally done by a so-called session proxy such as #InfcSessionProxy or #InfdSessionProxy, respectively.

set_user_status(user, status)¶

Parameters:

user (Infinity.User) – A local Infinity.User from self's user table.
status (Infinity.UserStatus) – New status for user.

Changes the status of the given user which needs to have the Infinity.UserFlags.LOCAL flag set for this function to be called. If the status is changed to Infinity.UserStatus.UNAVAILABLE, then the user leaves the session. To rejoin use Infinity.SessionProxy.join_user() for a proxy proxying self.

synchronize_from()¶: Switches self's status to Infinity.SessionStatus.SYNCHRONIZING. In Infinity.SessionStatus.PRESYNC, all messages from incoming the synchronizing connection are ignored, and no cancellation request is sent to the remote site if the status changes to Infinity.SessionStatus.CLOSED. The rationale behind that status is that one can prepare a session for synchronization but start the actual synchronization later, after having made sure that the remote site is ready to perform the synchronization.

synchronize_to(group, connection)¶

Parameters:

group (Infinity.CommunicationGroup) – A Infinity.CommunicationGroup.
connection (Infinity.XmlConnection) – A Infinity.XmlConnection.

Initiates a synchronization to connection. On the other end of connection, a new session with the sync-connection and sync-group construction properties set should have been created. group is used as a group in the communication manager. It is allowed for group to have another Infinity.CommunicationObject than self, however, you should forward the Infinity.CommunicationObject messages your object receives to self then. Also, connection must already be present in group, and should not be removed until synchronization finished.

A synchronization can only be initiated if self is in state Infinity.SessionStatus.RUNNING.

user_to_xml(user, xml)¶

Parameters:

user (Infinity.User) – A Infinity.User contained in self.
xml (libxml2.NodePtr) – An XML node to which to add user information.

This is a convenience function that queries user's properties and calls set_xml_user_props with them. This adds the properties of user to xml.

An equivalent user object may be built by calling the get_xml_user_props vfunc on xml and then calling the user_new vfunc with the resulting properties.

do_close() virtual¶: Closes a running session. When a session is closed, it unrefs all connections and no longer handles requests.

do_error(connection, xml, error) virtual¶

Parameters:

connection (Infinity.XmlConnection) –
xml (libxml2.NodePtr) –
error (GLib.Error) –

do_process_xml_run(connection, xml) virtual¶

Parameters:

connection (Infinity.XmlConnection) –
xml (libxml2.NodePtr) –

Return type:

Infinity.CommunicationScope

do_process_xml_sync(connection, xml) virtual¶

Parameters:

connection (Infinity.XmlConnection) –
xml (libxml2.NodePtr) –

Return type:

bool

do_set_xml_user_props(params, n_params, xml) virtual¶

Parameters:

params (GObject.Parameter) –
n_params (int) –
xml (libxml2.NodePtr) –

do_synchronization_begin(group, connection) virtual¶

Parameters:

group (Infinity.CommunicationGroup) –
connection (Infinity.XmlConnection) –

do_synchronization_complete(connection) virtual¶

Parameters:: connection (Infinity.XmlConnection) –

do_synchronization_failed(connection, error) virtual¶

Parameters:

connection (Infinity.XmlConnection) –
error (GLib.Error) –

do_synchronization_progress(connection, percentage) virtual¶

Parameters:

connection (Infinity.XmlConnection) –
percentage (float) –

do_to_xml_sync(parent) virtual¶

Parameters:: parent (libxml2.NodePtr) –

do_validate_user_props(params, n_params, exclude) virtual¶

Parameters:

params (GObject.Parameter) –
n_params (int) –
exclude (Infinity.User) –

Return type:

bool

Signal Details¶

Infinity.Session.signals.close(session)¶

Signal Name:: close
Flags:: RUN_LAST
Parameters:: session (Infinity.Session) – The object which received the signal

This signal is emitted if the session is closed. Note that this signal is not called as a client if the connection to the sessions has merely been lost, only the relevant Infinity.XmlConnection has its Infinity.XmlConnection :status property changed.

Infinity.Session.signals.error(session, connection, xml, error)¶

Signal Name:

error

Flags:

RUN_LAST

Parameters:

session (Infinity.Session) – The object which received the signal
connection (Infinity.XmlConnection) – The Infinity.XmlConnection which sent the erroneous request.
xml (object or None) – The XML request that produced the error.
error (GLib.Error) – A GLib.Error providing information about the error.

This signal is emitted when the session detects an error. The session itself does not know much about the nature of the error. It might mean the session is in an inconsistent state, or it might be recoverable. This signal can be used to handle the error or to write error information into a log file or bring to a user’s attention in another manner.

Infinity.Session.signals.synchronization_begin(session, group, connection)¶

Signal Name:

synchronization-begin

Flags:

RUN_LAST

Parameters:

session (Infinity.Session) – The object which received the signal
group (Infinity.CommunicationGroup) – The Infinity.CommunicationGroup used for synchronization.
connection (Infinity.XmlConnection) – The Infinity.XmlConnection to which the session is synchronized.

This signal is emitted whenever the session is started to be synchronized to another connection. Note that, in contrast to Infinity.Session ::synchronization-progress, Infinity.Session ::synchronization-failed and Infinity.Session ::synchronization-complete it cannot happen that the signal is emitted when session is being synchronized itself, because that can happen at construction time only when no one had a chance to connect signal handlers anyway.

Infinity.Session.signals.synchronization_complete(session, connection)¶

Signal Name:

synchronization-complete

Flags:

RUN_LAST

Parameters:

session (Infinity.Session) – The object which received the signal
connection (Infinity.XmlConnection) – The Infinity.XmlConnection through which synchronization happened

This signal is emitted when synchronization has completed, in addition to Infinity.Session ::synchronization-progress with a progress value of 1.0.

If a callback is connected before the default handler, it can find out whether the remote side is synchronizing the local side by comparing sessions's status with Infinity.SessionStatus.SYNCHRONIZING. The default signal handler sets the status to Infinity.SessionStatus.RUNNING, so checking afterwards is not too useful.

Infinity.Session.signals.synchronization_failed(session, connection, error)¶

Signal Name:

synchronization-failed

Flags:

RUN_LAST

Parameters:

session (Infinity.Session) – The object which received the signal
connection (Infinity.XmlConnection) – The Infinity.XmlConnection through which synchronization happened
error (GLib.Error) – A pointer to a GLib.Error object with details on the error

This signal is emitted when synchronization has failed before its completion due to malformed data from the other side or network failure.

If this happens during initial synchronization, Infinity.Session ::close is emitted as well at this point.

Infinity.Session.signals.synchronization_progress(session, connection, progress)¶

Signal Name:

synchronization-progress

Flags:

RUN_LAST

Parameters:

session (Infinity.Session) – The object which received the signal
connection (Infinity.XmlConnection) – The Infinity.XmlConnection through which progress is made
progress (float) – A float value ranging from 0.0 to 1.0.

This signal is emitted whenever a new XML node has been sent or received over connection as part of a synchronization. The process is completed when progress reaches the value 1.0. At this point, Infinity.Session ::synchronization-complete is also emitted.

If session's status is Infinity.SessionStatus.SYNCHRONIZING, the local side is being synchronized by the remote side. If the status is Infinity.SessionStatus.RUNNING, the local side is updating the remote side.