# Python X2Go (Client) API Documentation (v0.6.1.3)

## x2go.client module

`x2go.client.X2GoClient` is a public API class. Use this class in your Python X2Go based applications. Use it as a parent class for your own object oriented `x2go.client.X2GoClient`’ish class implementation.

## Supported Features

> Supported features are:

> > - X2Go multi-session management
> > - keep track of initiated sessions
> > - grant access to X2Go client config files: `settings`, `printing`, `sessions` and `xconfig` (Windows only) as normally found in `~/.x2goclient`
> > - communicate with X2Go Session Broker via http(s) or SSH
> > - instantiate an X2Go session by a set of Python parameters
> > - load a session profile from x2goclient’s `sessions` configuration file and start the—profile-based pre-configured—session
> > - sharing of local folders with remote X2Go sessions
> > - enabling and mangaging X2Go printing (real printing, viewing as PDF, saving to a local folder or executing a custom »print« command
> > - transparent tunneling of audio (Pulseaudio, ESD)
> > - sharing of other desktops
> > - published applications support

## Non-Profile Sessions

> A new non-profile based X2Go session within an `x2go.client.X2GoClient` instance is setup in the following way:

> > - import the Python X2Go module and call the session constructor:

> >       import x2go
> >       x2go_client = x2go.X2GoClient()

> > - register a new `x2go.client.X2GoClient` session; this creates an `x2go.session.X2GoSession` instance and calls its constructor method:

> >       x2go_sess_uuid = x2go_client.register_session(<many-options>)

> > - connect to the session’s remote X2Go server (SSH/Paramiko):

> >       x2go_client.connect_session(x2go_sess_uuid)

> > - via the connected X2Go client session you can start or resume a remote X-windows session on an X2Go server now:

> >       x2go_client.start_session(x2go_sess_uuid)

> >   resp.:

> >       x2go_client.resume_session(x2go_sess_uuid, session_name=<session_name_of_resumable_session>)

> > - a list of available sessions on the respective server (for resuming) can be obtained in this way:

> >       x2go_client.list_sessions(x2go_sess_uuid, session_name=<session_name_of_resumable_session>)

## Profiled Sessions

> A new profile based X2Go session (i.e. using pre-defined session profiles) within an `x2go.client.X2GoClient` instance is setup in a much easier way:

> > - import the Python X2Go module and call the session constructor:

> >       import x2go
> >       x2go_client = x2go.X2GoClient()

> > - register an X2GoClient session based on a pre-configured session profile:

> >       x2go_sess_uuid = x2go_client.register_session(profile_name=<session_profile_name>)

> > - or alternatively by the profile id in the »sessions« file (the name of the [<section>] in the »sessions« file:

> >       x2go_sess_uuid = x2go_client.register_session(profile_id=<session_profile_id>)

> > - now you proceed in a similar way as shown above:

> >       x2go_client.connect_session(x2go_sess_uuid)
> >       x2go_client.start_session(x2go_sess_uuid)

> >   resp.:

> >       x2go_client.resume_session(x2go_sess_uuid, session_name=<session_name_of_resumable_session>)

## Session Suspending / Terminating

> You can suspend or terminate your sessions by calling the follwing commands:

>     x2go_client.suspend_session(x2go_sess_uuid)

> resp.:

>     x2go_client.terminate_session(x2go_sess_uuid)

class `x2go.client.``X2GoClient`(control_backend='PLAIN', terminal_backend='PLAIN', info_backend='PLAIN', list_backend='PLAIN', proxy_backend='NX3', profiles_backend='FILE', settings_backend='FILE', printing_backend='FILE', broker_url=None, broker_password=None, broker_noauth=False, client_rootdir=None, sessions_rootdir=None, ssh_rootdir=None, start_xserver=False, start_pulseaudio=False, use_cache=False, use_listsessions_cache=False, auto_update_listsessions_cache=False, auto_update_listdesktops_cache=False, auto_update_listmounts_cache=False, auto_update_sessionregistry=False, auto_register_sessions=False, no_auto_reg_pubapp_sessions=False, refresh_interval=5, pulseaudio_installdir=None, logger=None, loglevel=56)

  Bases: `object`

  The X2GoClient implements _THE_ public Python X2Go API. With it you can construct your own X2Go client application in Python.

  Most methods in this class require that you have registered a session with a remote X2Go server (passing of session options, initialization of the session object etc.) and connected to it (authentication). For these two steps use these methods: `X2GoClient.register_session()` and `X2GoClient.connect_session()`.

  `HOOK_broker_connection_exception`(profile_name='UNKNOWN')

    HOOK method: called if a session demands to auto connect the session profile.

    Parameters: | profile_name (`str`) – profile name of a session that triggered this hook method (Default value = ‘UNKNOWN’)

  `HOOK_broker_ignore_connection_problems`(profile_name='UNKNOWN', is_profile_connected=False)

    HOOK method: called after a broker connection failed for a certain profile. This hook can be used to allow the user to decide how to proceed after connection problems with the broker.

    Parameters:

    - profile_name (`str`) – profile name of a session that triggered this hook method (Default value = ‘UNKNOWN’)
    - is_profile_connected (`bool`) – `True` if the given session profile is already conneced to the server (Default value = False)

    Returns: | If this hook returns `True`, the session startup/resumption will be continued, even if the broker connection is down. (Default: broker connection problems cause session start-up to fail).
    Return type: | `bool`

  `HOOK_check_host_dialog`(profile_name='UNKNOWN', host='UNKNOWN', port=22, fingerprint='no fingerprint', fingerprint_type='UNKNOWN')

    HOOK method: called if a host check is requested. This hook has to either return `True` (default) or `False`.

    Parameters:

    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - host (`str`) – SSH server name to validate (Default value = ‘UNKNOWN’)
    - port (`int`) – SSH server port to validate (Default value = 22)
    - fingerprint (`str`) – the server’s fingerprint (Default value = ‘no fingerprint’)
    - fingerprint_type (`str`) – finger print type (like RSA, DSA, …) (Default value = ‘UNKNOWN’)

    Returns: | if host validity is verified, this hook method should return `True`
    Return type: | `bool`

  `HOOK_desktop_sharing_denied`(profile_name='UNKNOWN')

    HOOK method: called if the startup of a shadow session was denied by the other user.

    Parameters: | profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)

  `HOOK_foldersharing_not_available`(profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK method: called if X2Go client-side folder-sharing is not available.

    Parameters:

    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `HOOK_forwarding_tunnel_setup_failed`(profile_name='UNKNOWN', session_name='UNKNOWN', chain_host='UNKNOWN', chain_port=0, subsystem=None)

    HOOK method: called if a port forwarding tunnel setup failed.

    Parameters:

    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)
    - chain_host (`str`) – hostname of chain host (forwarding tunnel end point) (Default value = ‘UNKNOWN’)
    - chain_port (`str`) – port of chain host (forwarding tunnel end point) (Default value = 0)
    - subsystem (`str`) – information on the subsystem that provoked this hook call (Default value = None)

  `HOOK_list_desktops_timeout`(profile_name='UNKNOWN')

    HOOK method: called if the x2golistdesktops command generates a timeout due to long execution time.

    Parameters: | profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)

  `HOOK_mimebox_not_available`(profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK method: called if the X2Go MIME box is not available.

    Parameters:

    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `HOOK_no_installed_xservers_found`()

    HOOK method: called if the Python X2Go module could not find any usable XServer application to start. You will not be able to start X2Go sessions without an XServer.

  `HOOK_no_known_xserver_found`()
  `HOOK_no_such_command`(cmd, profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK: the command <cmd> is not available on the connected X2Go server.

    Parameters:

    - cmd (`str`) – the command that failed
    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `HOOK_no_such_desktop`(profile_name='UNKNOWN', desktop='UNKNOWN')

    HOOK method: called if it is tried to connect to a (seen before) sharable desktop that’s not available (anymore).

    Parameters:

    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - desktop (`str`) – desktop identifier (the X session’s $DISPLAY) (Default value = ‘UNKNOWN’)

  `HOOK_on_control_session_death`(profile_name)

    HOOK method: called if a control session (server connection) has unexpectedly encountered a failure.

    Parameters: | profile_name (`str`) – profile name of session that called this hook method

  `HOOK_on_failing_SFTP_client`(profile_name, session_name)

    HOOK method: called SFTP client support is unavailable for the session.

    Parameters:

    - profile_name (`str`) – profile name of the session that experiences failing SFTP client support
    - session_name (`str`) – name of session experiencing failing SFTP client support

  `HOOK_on_found_session_running_after_connect`(session_uuid='UNKNOWN', profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK method: called after server connect if an already running session has been found.

    Parameters:

    - session_uuid (`str`) – unique session identifier of the calling session (Default value = ‘UNKNOWN’)
    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `HOOK_on_session_has_been_suspended`(session_uuid='UNKNOWN', profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK method: called if a session has been suspended by this instance of `x2go.client.X2GoClient`.

    Parameters:

    - session_uuid (`str`) – unique session identifier of the calling session (Default value = ‘UNKNOWN’)
    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `HOOK_on_session_has_resumed_by_me`(session_uuid='UNKNOWN', profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK method: called if a session has been resumed by this instance of `x2go.client.X2GoClient`.

    Parameters:

    - session_uuid (`str`) – unique session identifier of the calling session (Default value = ‘UNKNOWN’)
    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `HOOK_on_session_has_resumed_by_other`(session_uuid='UNKNOWN', profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK method: called if a session has been resumed by another `x2goclient`.

    Parameters:

    - session_uuid (`str`) – unique session identifier of the calling session (Default value = ‘UNKNOWN’)
    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `HOOK_on_session_has_started_by_me`(session_uuid='UNKNOWN', profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK method: called if a session has been started by this instance of `x2go.client.X2GoClient`.

    Parameters:

    - session_uuid (`str`) – unique session identifier of the calling session (Default value = ‘UNKNOWN’)
    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `HOOK_on_session_has_started_by_other`(session_uuid='UNKNOWN', profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK method: called if a session has been started by another `x2goclient`.

    Parameters:

    - session_uuid (`str`) – unique session identifier of the calling session (Default value = ‘UNKNOWN’)
    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `HOOK_on_session_has_terminated`(session_uuid='UNKNOWN', profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK method: called if a session has been suspended by another `x2goclient`.

    Parameters:

    - session_uuid (`str`) – unique session identifier of the calling session (Default value = ‘UNKNOWN’)
    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `HOOK_on_sound_tunnel_failed`(profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK method: called if a sound tunnel setup failed.

    Parameters:

    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `HOOK_open_mimebox_saveas_dialog`(filename, profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK method: called on detection of an incoming MIME box job ,,<filename>’’.

    Parameters:

    - filename (`str`) – file name of the incoming MIME box job
    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `HOOK_open_print_dialog`(profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK method: called if an incoming print job has been detected by `x2go.printing.X2GoPrintQueue` and a print dialog box is requested.

    Parameters:

    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `HOOK_printaction_error`(filename, profile_name='UNKNOWN', session_name='UNKNOWN', err_msg='GENERIC_ERROR', printer=None)

    HOOK method: called if an incoming print job caused an error.

    Parameters:

    - filename (`str`) – file name of the print job that failed
    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)
    - err_msg (`str`) – if available, an appropriate error message (Default value = ‘GENERIC_ERROR’)
    - printer (`str`) – if available, the printer name the print job failed on (Default value = None)

  `HOOK_printing_not_available`(profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK method: called if X2Go client-side printing is not available.

    Parameters:

    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `HOOK_profile_auto_connect`(profile_name='UNKNOWN')

    HOOK method: called if a session demands to auto connect the session profile.

    Parameters: | profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)

  `HOOK_pulseaudio_not_supported_in_RDPsession`()

    HOOK method: called if trying to run the Pulseaudio daemon within an RDP session, which is not supported by Pulseaudio.

  `HOOK_pulseaudio_server_died`()

    HOOK method: called if the Pulseaudio daemon has died away unexpectedly.

  `HOOK_pulseaudio_server_startup_failed`()

    HOOK method: called if the Pulseaudio daemon startup failed.

  `HOOK_rforward_request_denied`(profile_name='UNKNOWN', session_name='UNKNOWN', server_port=0)

    HOOK method: called if a reverse port forwarding request has been denied.

    Parameters:

    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)
    - server_port (`str`) – remote server port (starting point of reverse forwarding tunnel) (Default value = 0)

  `HOOK_session_startup_failed`(profile_name='UNKNOWN')

    HOOK method: called if the startup of a session failed.

    Parameters: | profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)

  `HOOK_sshfs_not_available`(profile_name='UNKNOWN', session_name='UNKNOWN')

    HOOK method: called if the X2Go server denies SSHFS access.

    Parameters:

    - profile_name (`str`) – profile name of session that called this hook method (Default value = ‘UNKNOWN’)
    - session_name (`str`) – X2Go session name (Default value = ‘UNKNOWN’)

  `all_servers_are_alive`()

    Test vitality of all connected X2Go servers.

    Returns: | `True` if all connected X2Go servers are alive.
    Return type: | `bool`

  `check_session_host`(session_uuid)

    Provide a mechanism to evaluate the validity of an X2Go server host.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | returns `True` if host validation has been successful.
    Return type: | `bool`

  `clean_sessions`(session_uuid, published_applications=False)

    Find running X2Go sessions that have previously been started by the connected user on the remote X2Go server and terminate them.

    Before calling this method you have to setup a pro forma remote X2Go session with `X2GoClient.register_session()` (even if you do not intend to open a real X2Go session window on the remote server) and connect to this session (with `X2GoClient.connect_session()`.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - published_applications (`bool`) – if `True`, also terminate sessions that are published applications provider (Default value = False)

  `client_associated_sessions`(return_objects=False, return_profile_names=False, return_profile_ids=False, return_session_names=False)

    Retrieve a list of X2Go sessions associated to this `x2go.client.X2GoClient` instance.

    Parameters:

    - return_objects (`bool`) – return as list of X2Go session objects (Default value = False)
    - return_profile_names (`bool`) – return as list of session profile names (Default value = False)
    - return_profile_ids (`bool`) – return as list of session profile IDs (Default value = False)
    - return_session_names (`bool`) – return as list of session names (Default value = False)

    Returns: | list of associated sessions
    Return type: | `list`

  `client_associated_sessions_of_profile_name`(profile_name, return_objects=False, return_session_names=False)

    Retrieve associated X2Go sessions of profile name <profile_name>.

    Parameters:

    - profile_name (`str`) – profile name
    - return_objects (`bool`) – return as list of X2Go session objects (Default value = False)
    - return_session_names (`bool`) – return as list of session names (Default value = False)

    Returns: | list of associated sessions of profile name
    Return type: | `list`

  `client_connected_profiles`(return_profile_names=False)

    Retrieve a list of session profiles that are currently connected to an X2Go server.

    Parameters: | return_profile_names (`bool`) – return as list of session profile names (Default value = False)
    Returns: | a list of profile names or IDs
    Return type: | `list`

  `client_connected_sessions`(return_objects=False, return_profile_names=False, return_profile_ids=False, return_session_names=False)

    Retrieve a list of X2Go sessions that this `x2go.client.X2GoClient` instance is connected to.

    Parameters:

    - return_objects (`bool`) – return as list of X2Go session objects (Default value = False)
    - return_profile_names (`bool`) – return as list of session profile names (Default value = False)
    - return_profile_ids (`bool`) – return as list of session profile IDs (Default value = False)
    - return_session_names (`bool`) – return as list of session names (Default value = False)

    Returns: | list of connected sessions
    Return type: | `list`

  `client_connected_sessions_of_profile_name`(profile_name, return_objects=False, return_session_names=False)

    Retrieve connected X2Go sessions of profile name <profile_name>.

    Parameters:

    - profile_name (`str`) – profile name
    - return_objects (`bool`) – return as list of X2Go session objects (Default value = False)
    - return_session_names (`bool`) – return as list of session names (Default value = False)

    Returns: | list of connected sessions of profile name
    Return type: | `list`

  `client_control_session_of_profile_name`(profile_name)

    Retrieve control session for profile name <profile_name>.

    Parameters: | profile_name (`str`) – profile name
    Returns: | control session instance
    Return type: | `X2GoControlSession` instance

  `client_control_sessions`

    Equals a list of all registered X2Go control sessions.

  `client_has_associated_sessions`

    Equals `True` if there are any associated sessions with this `x2go.client.X2GoClient` instance.

  `client_has_connected_sessions`

    Equals `True` if there are any connected sessions with this `x2go.client.X2GoClient` instance.

  `client_has_registered_session_of_name`(session_name)

    Equals `True` if there is a registered session of name <session_name>.

    Parameters: | session_name (`str`) – session name
    Returns: | `True` if the given session is registered
    Return type: | `bool`

  `client_has_running_sessions`

    Equals `True` if there are any running sessions with this `x2go.client.X2GoClient` instance.

  `client_has_suspended_sessions`

    Equals `True` if there are any suspended sessions with this `x2go.client.X2GoClient` instance.

  `client_pubapp_sessions_of_profile_name`(profile_name, return_objects=False, return_session_names=False)

    Retrieve X2Go sessions of profile name <profile_name> that provide published applications.

    Parameters:

    - profile_name (`str`) – profile name
    - return_objects (`bool`) – return as list of X2Go session objects (Default value = False)
    - return_session_names (`bool`) – return as list of session names (Default value = False)

    Returns: | list of application publishing sessions of profile name
    Return type: | `list`

  `client_registered_session_of_name`(session_name, return_object=False)

    Retrieve X2Go session of a given session name.

    Parameters:

    - session_name (`str`) – session name
    - return_object (`bool`) – return as X2Go session object (Default value = False)

    Returns: | session instance of the given name
    Return type: | `X2GoSession` or `str`

  `client_registered_sessions`(return_objects=True, return_profile_names=False, return_profile_ids=False, return_session_names=False)

    Retrieve a list of registered X2Go sessions.

    Parameters:

    - return_objects (`bool`) – return as list of X2Go session objects (Default value = True)
    - return_profile_names (`bool`) – return as list of session profile names (Default value = False)
    - return_profile_ids (`bool`) – return as list of session profile IDs (Default value = False)
    - return_session_names (`bool`) – return as list of session names (Default value = False)

    Returns: | list of registered sessions
    Return type: | `list`

  `client_registered_sessions_of_profile_name`(profile_name, return_objects=False, return_session_names=False)

    Retrieve registered X2Go sessions of profile name <profile_name>.

    Parameters:

    - profile_name (`str`) – profile name
    - return_objects (`bool`) – return as list of X2Go session objects (Default value = False)
    - return_session_names (`bool`) – return as list of session names (Default value = False)

    Returns: | list of registered sessions of profile name
    Return type: | `list`

  `client_running_sessions`(return_objects=False, return_profile_names=False, return_profile_ids=False, return_session_names=False)

    Retrieve a list of running X2Go sessions.

    Parameters:

    - return_objects (`bool`) – return as list of X2Go session objects (Default value = False)
    - return_profile_names (`bool`) – return as list of session profile names (Default value = False)
    - return_profile_ids (`bool`) – return as list of session profile IDs (Default value = False)
    - return_session_names (`bool`) – return as list of session names (Default value = False)

    Returns: | list of running sessions
    Return type: | `list`

  `client_running_sessions_of_profile_name`(profile_name, return_objects=False, return_session_names=False)

    Retrieve running X2Go sessions of profile name <profile_name>.

    Parameters:

    - profile_name (`str`) – profile name
    - return_objects (`bool`) – return as list of X2Go session objects (Default value = False)
    - return_session_names (`bool`) – return as list of session names (Default value = False)

    Returns: | list of running sessions of profile name
    Return type: | `list`

  `client_suspended_sessions`(return_objects=False, return_profile_names=False, return_profile_ids=False, return_session_names=False)

    Retrieve a list of suspended X2Go sessions.

    Parameters:

    - return_objects (`bool`) – return as list of X2Go session objects (Default value = False)
    - return_profile_names (`bool`) – return as list of session profile names (Default value = False)
    - return_profile_ids (`bool`) – return as list of session profile IDs (Default value = False)
    - return_session_names (`bool`) – return as list of session names (Default value = False)

    Returns: | list of suspended sessions
    Return type: | `list`

  `client_suspended_sessions_of_profile_name`(profile_name, return_objects=False, return_session_names=False)

    Retrieve suspended X2Go sessions of profile name <profile_name>.

    Parameters:

    - profile_name (`str`) – profile name
    - return_objects (`bool`) – return as list of X2Go session objects (Default value = False)
    - return_session_names (`bool`) – return as list of session names (Default value = False)

    Returns: | list of suspended sessions of profile name
    Return type: | `list`

  `connect_session`(session_uuid, username=None, password=None, passphrase=None, sshproxy_user=None, sshproxy_password=None, sshproxy_passphrase=None, add_to_known_hosts=False, force_password_auth=False, sshproxy_force_password_auth=False)

    Connect to a registered X2Go session with registry hash `session_uuid` This method basically wraps around paramiko.SSHClient.connect() for the corresponding session.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - username (`str`) – user name to be used for session authentication (Default value = None)
    - password (`str`) – the user’s password for the X2Go server that is going to be connected to (Default value = None)
    - passphrase (`str`) – a passphrase to use for unlocking a private key in case the password is already needed for two-factor authentication (Default value = None)
    - sshproxy_user (`str`) – user name to be used for SSH proxy authentication (Default value = None)
    - sshproxy_password (`str`) – the SSH proxy user’s password (Default value = None)
    - sshproxy_passphrase (`str`) – a passphrase to use for unlocking a private key needed for the SSH proxy host in case the sshproxy_password is already needed for two-factor authentication (Default value = None)
    - add_to_known_hosts (`bool`) – non-Paramiko option, if `True` `paramiko.AutoAddPolicy()` is used as missing-host-key-policy. If set to `False` `checkhosts.X2GoInteractiveAddPolicy()` is used (Default value = False)
    - force_password_auth (`bool`) – disable SSH pub/priv key authentication mechanisms completely (Default value = False)
    - sshproxy_force_password_auth (`bool`) – disable SSH pub/priv key authentication mechanisms completely for SSH proxy connection (Default value = False)

    Returns: | returns True if this method has been successful
    Return type: | `bool`

  `disconnect_profile`(profile_name)

    Disconnect all `x2go.session.X2GoSession` instances that relate to `profile_name` by closing down their Paramiko/SSH Transport thread.

    Parameters: | profile_name (`str`) – the X2Go session profile name
    Returns: | a return value
    Return type: | `bool`

  `disconnect_session`(session_uuid)

    Disconnect an `x2go.session.X2GoSession` by closing down its Paramiko/SSH Transport thread.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash

  `get_client_printing`()

    Returns the `x2go.client.X2GoClient` instance’s `X2GoClientPrinting*` object.

    Use this method for object retrieval if you want to modify the printing configuration node (e.g. in ~/.x2goclient with the FILE backend) from within your Python X2Go based application.

    Returns: | a `X2GoClientPrinting*` instance
    Return type: | `bool`

  `get_client_rootdir`()

    Retrieve the settings root directory of this `x2go.client.X2GoClient` instance.

    Returns: | X2Go client root directory
    Return type: | `str`

  `get_client_settings`()

    Returns the `x2go.client.X2GoClient` instance’s `X2GoClientSettings*` object.

    Use this method for object retrieval if you want to modify the »settings« configuration node (e.g. in ~/.x2goclient with the FILE backend) from within your Python X2Go based application.

    Returns: | a `X2GoClientSettings*` instance
    Return type: | `obj`

  `get_client_username`()

    Query the local user’s username (i.e. the user running the X2Go client).

    Returns: | the local username this `x2go.client.X2GoClient` instance runs as
    Return type: | `str`

  `get_master_session`(profile_name, return_object=True, return_session_name=False)

    Retrieve the master session of a specific profile.

    Parameters:

    - profile_name (`str`) – the profile name that we query the master session of
    - return_object (`bool`) – return `x2go.session.X2GoSession` instance (Default value = True)
    - return_session_name (`bool`) – return X2Go session name (Default value = False)

    Returns: | a session list (as UUID hashes, objects, profile names/IDs or session names)
    Return type: | `list`

  `get_profile_config`(profile_id_or_name, parameter=None)

    Returns a dictionary with session options and values that represent the session profile for `profile_id_or_name`.

    Parameters:

    - profile_id_or_name (`str`) – name or id of an X2Go session profile as found in the sessions configuration file
    - parameter (`str`) – if specified, only the value for the given parameter is returned (Default value = None)

    Returns: | a Python dictionary with session profile options
    Return type: | `dict` or `bool`, `int`, `str`

  `get_profile_metatype`(profile_name)

    Evaluate a session profile and return a human readable meta type (classification) for the session profile `profile_name`.

    Parameters: | profile_name (`str`) – a profile name
    Returns: | the profile’s meta type
    Return type: | `str`

  `get_profiles`()

    Returns the `x2go.client.X2GoClient` instance’s `X2GoSessionProfiles*` object.

    Use this method for object retrieval if you want to modify the »sessions« configuration node (e.g. in ~/.x2goclient with the FILE backend) from within your Python X2Go based application.

    Returns: | a `X2GoSessionProfiles*` instance
    Return type: | `obj`

  `get_published_applications`(session_uuid=None, profile_name=None, lang=None, refresh=False, raw=False, very_raw=False, max_no_submenus=10)

    Retrieve the server-side X2Go published applications menu for the session registered under `session_uuid` or for profile name `profile_name`.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - profile_name (`str`) – a valid session profile name (Default value = None)
    - lang (`str`) – locale/language identifier (Default value = None)
    - refresh (`bool`) – force reload of the menu tree from X2Go server (Default value = False)
    - raw (`bool`) – retrieve a raw output of the server list of published applications (Default value = False)
    - very_raw (`bool`) – retrieve a very raw output of the server list of published applications (Default value = False)
    - max_no_submenus (`int`) – Number of applications before applications are put into XDG category submenus (Default value = defaults.PUBAPP_MAX_NO_SUBMENUS)

    Returns: | an i18n capable menu tree packed as a Python dictionary
    Return type: | `list`

  `get_server_components`(profile_name, component=None, force=False)

    Query the server configured in session profile <profile_name> for the list of install X2Go components and its versions.

    Parameters:

    - profile_name (`str`) – use the control session of this profile to query the X2Go server for its component list
    - component (`str`) – only return the version of a specific component (Default value = None)
    - force (`bool`) – refresh component/version data by a query to the server (Default value = False)

    Returns: | dictionary of server components (as keys) and their versions (as values) or the version of the given <component>
    Return type: | `dict` or `str`
    Raises: | X2GoClientException – if component is not available on the X2Go Server.

  `get_server_features`(profile_name, force=False)

    Query the server configured in session profile <profile_name> for the list of server-side X2Go features.

    Parameters:

    - profile_name (`str`) – use the control session of this profile to query the X2Go server for its feature list
    - force (`bool`) – refresh feature list by a query to the server (Default value = False)

    Returns: | list of server feature names (as returned by server-side command ,,x2gofeaturelist’’
    Return type: | `list`

  `get_server_versions`(profile_name, component=None, force=False)

    Query the server configured in session profile <profile_name> for the list of install X2Go components and its versions.

    Parameters:

    - profile_name (`str`) – use the control session of this profile to query the X2Go server for its component list
    - component (`str`) – only return the version of a specific component (Default value = None)
    - force (`bool`) – refresh component/version data by a query to the server (Default value = False)

    Returns: | dictionary of server components (as keys) and their versions (as values) or the version of the given <component>
    Return type: | `dict` or `str`
    Raises: | X2GoClientException – if component is not available on the X2Go Server.

  `get_session`(session_uuid)

    Retrieve the complete `x2go.session.X2GoSession` object that has been registered under the given session registry hash.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | the `x2go.session.X2GoSession` instance
    Return type: | obj

  `get_session_info`(session_uuid)

    Retrieve the server-side X2Go session information object for the session that has been registered under `session_uuid`.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | X2Go session info
    Return type: | `obj`

  `get_session_name`(session_uuid)

    Retrieve the server-side X2Go session name for the session that has been registered under `session_uuid`.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | X2Go session name
    Return type: | `str`

  `get_session_of_session_name`(session_name, return_object=False, match_profile_name=None)

    Retrieve session UUID or `x2go.session.X2GoSession` for session name <session_name> from the session registry.

    Parameters:

    - session_name (`str`) – the X2Go session’s UUID registry hash
    - return_object (`bool`) – session UUID hash or `x2go.session.X2GoSession` instance wanted? (Default value = False)
    - match_profile_name (`str`) – only return sessions that match this profile name (Default value = None)

    Returns: | the X2Go session’s UUID registry hash or `x2go.session.X2GoSession` instance
    Return type: | `str` or `x2go.session.X2GoSession` instance

  `get_session_profile_id`(session_uuid)

    Retrieve the profile id of the session that has been registered under `session_uuid`.

    For profile based sessions this will be the profile id as used in x2goclient’s »sessions« configuration node (section header of a session profile in the config, normally a timestamp created on session profile creation/modification).

    For non-profile based sessions this will be a timestamp created on X2Go session registration by `register_session`.

    Parameters: | session_uuid (`str`) – the session profile name
    Returns: | the X2Go session profile’s id
    Return type: | `str`

  `get_session_profile_name`(session_uuid)

    Retrieve the profile name of the session that has been registered under `session_uuid`.

    For profile based sessions this will be the profile name as used in x2goclient’s »sessions« configuration file.

    For non-profile based session this will either be a `profile_name` that was passed to `register_session()` or it will be the application that instantiated this `x2go.client.X2GoClient` instance.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | X2Go session profile name
    Return type: | `str`

  `get_session_profiles`()

    Alias for `get_profiles()`.

  `get_session_server_hostname`(session_uuid)

    Retrieve the server hostname as provided by the calling application (e.g. like it has been specified in the session profile).

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | the hostname for the queried X2Go session as specified by the calling application
    Return type: | str

  `get_session_server_peername`(session_uuid)

    After a session has been set up you can query the hostname of the host the session is connected to (or about to connect to).

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | the host an X2Go session is connected to (as an `(addr,port)` tuple)
    Return type: | tuple

  `get_session_summary`(session_uuid)

    Retrieves a Python dictionary, containing a short session summary (session status, names, etc.)

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash

  `get_session_username`(session_uuid)

    After an `x2go.session.X2GoSession` has been set up you can query the username that the remote sessions runs as.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | the remote username the X2Go session runs as
    Return type: | `str`

  `get_sessions_rootdir`()

    Retrieve the sessions root directory of this `x2go.client.X2GoClient` instance.

    Returns: | X2Go sessions root directory
    Return type: | `str`

  `get_shared_folders`(session_uuid=None, profile_name=None, check_list_mounts=False)

    Get a list of local folders mounted within X2Go session with session hash <session_uuid> from this client.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - profile_name (`str`) – alternatively, the profile name can be used to get mounted folders of a session connected profile (Default value = None)
    - check_list_mounts (`bool`) – query the server-side mount list for up-to-date information (Default value = False)

    Returns: | returns a `list` of those local folder names that are mounted within X2Go session <session_uuid>.
    Return type: | `list`

  `get_ssh_rootdir`()

    Retrieve the SSH client root dir used with this `x2go.client.X2GoClient` instance.

    Returns: | SSH client root directory
    Return type: | `str`

  `has_custom_client_rootdir`

    Does this `x2go.client.X2GoClient` instance have a customized root dir path? Equals `True` in case it has.

  `has_server_feature`(profile_name, feature)

    Query the server configured in session profile <profile_name> for the availability of a certain server feature.

    Parameters:

    - profile_name (`str`) – use the control session of this profile to query the X2Go server for its feature
    - feature (`str`) – test the availability of this feature on the X2Go server

    Returns: | `True` if the feature is available on the queried server
    Return type: | `bool`

  `has_session_terminated`(session_uuid, session_name=None)

    Test if the X2Go session registered as `session_uuid` has terminated.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - session_name (`str`) – the server-side name of an X2Go session (Default value = None)

    Returns: | `True` if session has terminated, `False` otherwise
    Return type: | `bool`

  `is_folder_sharing_available`(session_uuid=None, profile_name=None)

    Test if local folder sharing is available for X2Go session with unique ID <session_uuid> or session profile <profile_name>.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - profile_name (`str`) – alternatively, the profile name can be used to perform this query (Default value = None)

    Returns: | returns `True` if the profile/session supports local folder sharing
    Return type: | `bool`

  `is_profile_connected`(profile_name)

    Test if the X2Go given session profile has open connections to the X2Go server.

    Parameters: | profile_name (`str`) – a valid session profile name
    Returns: | `True` if profile has a connected session, `False` otherwise
    Return type: | `bool`

  `is_session_connected`(session_uuid)

    Test if the X2Go session registered as `session_uuid` connected to the X2Go server.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | `True` if session is connected, `False` otherwise
    Return type: | `bool`

  `is_session_profile`(profile_id_or_name)

    Test if the X2Go given session profile is configured in the client’s `sessions` file.

    Parameters: | profile_id_or_name (`str`) – test existence of this session profile name (or id)
    Returns: | `True` if session profile exists, `False` otherwise
    Return type: | `bool`

  `is_session_running`(session_uuid, session_name=None)

    Test if the X2Go session registered as `session_uuid` is up and running.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - session_name (`str`) – the server-side name of an X2Go session (Default value = None)

    Returns: | `True` if session is running, `False` otherwise
    Return type: | `bool`

  `is_session_suspended`(session_uuid, session_name=None)

    Test if the X2Go session registered as `session_uuid` is in suspended state.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - session_name (`str`) – the server-side name of an X2Go session (Default value = None)

    Returns: | `True` if session is suspended, `False` otherwise
    Return type: | `bool`

  `is_x2goserver`(session_uuid, force=False)

    Check a remote and connected server (identified by the session_uuid hash) if it really is an X2Go Server (i.e., if it has the X2Go Server software installed.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - force (`bool`) – reinforce the lookup, don’t use cached information

    Returns: | `True` if the remote server has X2Go Server installed, `False` otherwise.
    Return type: | `bool`

  `lang` = 'en'
  `list_desktops`(session_uuid=None, profile_name=None, profile_id=None, no_cache=False, refresh_cache=False, exclude_session_types=[], raw=False)

    Use the X2Go session registered under `session_uuid` to retrieve a list of X2Go desktop sessions that are available for desktop sharing.

    Before calling this method you have to setup a pro forma remote X2Go session with `X2GoClient.register_session()` (even if you do not intend to open a real X2Go session window on the remote server) and connect to this session (with `X2GoClient.connect_session()`.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - profile_name (`str`) – use profile name instead of <session_uuid> (Default value = None)
    - profile_id (`str`) – use profile id instead of <profile_name> or <session_uuid> (Default value = None)
    - no_cache (`bool`) – do not get the desktop list from cache, query the X2Go server directly (Default value = False)
    - refresh_cache (`bool`) – query the X2Go server directly and update the desktop list cache with the new information (Default value = False)
    - exclude_session_types (`list`) – session types (e.g. “D”, “K”, “R”, “S” or “P”) to be excluded from the returned list of sharable desktops (this only works for sharing someone’s own sessions, for sharing other users’ sessions, the X2Go Desktop Sharing decides on what is sharable and what not). (Default value = [])
    - raw (`bool`) – output the session list in X2Go’s raw `x2golistdesktops` format (Default value = False)

    Returns: | a list of available desktops to be shared
    Return type: | `list`
    Raises: | X2GoClientException – if the session profile specified by `session_uuid`, `profile_name` or `profile_id` is not connected or if none of the named parameters has been specified

  `list_mounts`(session_uuid, no_cache=False, refresh_cache=False, raw=False)

    Use the X2Go session registered under `session_uuid` to retrieve its list of mounted client shares for that session.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - no_cache (`bool`) – do not get the session list from cache, query the X2Go server directly (Default value = False)
    - raw (`bool`) – output the session list in X2Go’s raw `x2golistmounts` format (Default value = False)
    - refresh_cache – Default value = False)

    Returns: | list of server-side mounted shares for a given session UUID
    Return type: | `list`

  `list_mounts_by_profile_name`(profile_name, no_cache=False, refresh_cache=False, raw=False)

    For a given profil `profile_name` to retrieve its list of mounted client shares for that session.

    Parameters:

    - profile_name (`str`) – a valid profile name
    - no_cache (`bool`) – do not get the session list from cache, query the X2Go server directly (Default value = False)
    - raw (`bool`) – output the session list in X2Go’s raw `x2golistmounts` format (Default value = False)
    - refresh_cache – Default value = False)

    Returns: | list of server-side mounted shares for a given profile name
    Return type: | `list`

  `list_sessions`(session_uuid=None, profile_name=None, profile_id=None, no_cache=False, refresh_cache=False, update_sessionregistry=True, register_sessions=False, with_command=None, raw=False)

    Use the X2Go session registered under `session_uuid` to retrieve a list of running or suspended X2Go sessions from the connected X2Go server (for the authenticated user).

    Before calling this method you have to setup a pro forma remote X2Go session with `X2GoClient.register_session()` (even if you do not intend to open a real X2Go session window on the remote server) and connect to this session (with `X2GoClient.connect_session()`.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - profile_name (`str`) – use profile name instead of <session_uuid> (Default value = None)
    - profile_id (`str`) – use profile id instead of <profile_name> or <session_uuid> (Default value = None)
    - no_cache (`bool`) – do not get the session list from cache, query the X2Go server directly (Default value = False)
    - refresh_cache (`bool`) – query the X2Go server directly and update the session list cache with the new information (Default value = False)
    - update_sessionregistry (`bool`) – query the X2Go server directly and update the session registry according to the obtained information (Default value = True)
    - register_sessions (`bool`) – query the X2Go server directly and register newly found X2Go session as `x2go.session.X2GoSession` instances associated to this `x2go.client.X2GoClient` instance (Default value = False)
    - raw (`bool`) – output the session list in X2Go’s raw `x2golistsessions` format (Default value = False)

    Raises: | X2GoClientException – if the session profile specified by `session_uuid`, `profile_name` or `profile_id` is not connected or if none of the named parameters has been specified

  `profile_get_published_applications`(session_uuid=None, profile_name=None, lang=None, refresh=False, raw=False, very_raw=False, max_no_submenus=10)

    Retrieve the server-side X2Go published applications menu for the session registered under `session_uuid` or for profile name `profile_name`.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - profile_name (`str`) – a valid session profile name (Default value = None)
    - lang (`str`) – locale/language identifier (Default value = None)
    - refresh (`bool`) – force reload of the menu tree from X2Go server (Default value = False)
    - raw (`bool`) – retrieve a raw output of the server list of published applications (Default value = False)
    - very_raw (`bool`) – retrieve a very raw output of the server list of published applications (Default value = False)
    - max_no_submenus (`int`) – Number of applications before applications are put into XDG category submenus (Default value = defaults.PUBAPP_MAX_NO_SUBMENUS)

    Returns: | an i18n capable menu tree packed as a Python dictionary
    Return type: | `list`

  `profile_get_shared_folders`(session_uuid=None, profile_name=None, check_list_mounts=False)

    Get a list of local folders mounted within X2Go session with session hash <session_uuid> from this client.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - profile_name (`str`) – alternatively, the profile name can be used to get mounted folders of a session connected profile (Default value = None)
    - check_list_mounts (`bool`) – query the server-side mount list for up-to-date information (Default value = False)

    Returns: | returns a `list` of those local folder names that are mounted within X2Go session <session_uuid>.
    Return type: | `list`

  `profile_master_session`(profile_name, return_object=True, return_session_name=False)

    Retrieve the master session of a specific profile.

    Parameters:

    - profile_name (`str`) – the profile name that we query the master session of
    - return_object (`bool`) – return `x2go.session.X2GoSession` instance (Default value = True)
    - return_session_name (`bool`) – return X2Go session name (Default value = False)

    Returns: | a session list (as UUID hashes, objects, profile names/IDs or session names)
    Return type: | `list`

  `profile_names`

    Equals a list of all profile names that are known to this `x2go.client.X2GoClient` instance.

  `raise_session_window`(session_uuid)

    Try to lift the session window above all other windows and bring it to focus.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash

  `register_all_session_profiles`(return_objects=False)

    Register all session profiles found in the `sessions` configuration node as potential X2Go sessions.

    Parameters: | return_objects (`bool`) – if set to `True` this methods returns a list of `x2go.session.X2GoSession` instances, otherwise a list of session UUIDs representing the corresponding registered sessions is returned (Default value = False)
    Returns: | a Python dictionary containing one registered session for each available session profile configuration, whereas the profile names are used as dictionary keys and `x2go.session.X2GoSession` instances as their values
    Return type: | `list`

  `register_available_server_sessions_all_profiles`(skip_pubapp_sessions=False)

    Register all available sessions found on an X2Go server for each session profile.

    Parameters: | skip_pubapp_sessions (`bool`) – Do not auto-register published applications sessions. (Default value = False)

  `register_available_server_sessions_by_profile_name`(profile_name, re_register=False, skip_pubapp_sessions=False)

    Register available sessions that are found on the X2Go server the profile of name `profile_name` is connected to.

    Parameters:

    - profile_name (`str`) – the X2Go session profile name
    - re_register (`bool`) – re-register available sessions, needs to be done after session profile changes (Default value = False)
    - skip_pubapp_sessions (`bool`) – Do not auto-register published applications sessions. (Default value = False)

  `register_available_server_sessions_by_session_uuid`(session_uuid, skip_pubapp_sessions=False)

    Register available sessions that are found on the X2Go server that the `x2go.session.X2GoSession` instance with session identifier <session_uuid> is connected to.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - skip_pubapp_sessions (`bool`) – Do not auto-register published applications sessions. (Default value = False)

  `register_session`(server=None, profile_id=None, profile_name=None, session_name=None, allow_printing=False, allow_share_local_folders=False, share_local_folders=[], allow_mimebox=False, mimebox_extensions=[], mimebox_action='OPEN', add_to_known_hosts=False, known_hosts=None, forward_sshagent=False, proxy_options={}, return_object=False, **kwargs)

    Register a new `x2go.session.X2GoSession`. Within one `x2go.client.X2GoClient` instance you can manage several `x2go.session.X2GoSession` instances on serveral remote X2Go servers under different user names.

    These sessions can be instantiated by passing direct `x2go.session.X2GoSession` parameters to this method or by specifying the name of an existing session profile (as found in the `x2go.client.X2GoClient`’s `sessions` configuration node.

    A session profile is a pre-defined set of session options stored in a sessions profile node (e.g. a configuration file). With the FILE backend such session profiles are stored as a file (by default: `~/.x2goclient/sessions` or globally (for all users on the client) in `/etc/x2goclient/sessions`).

    Python X2Go also supports starting multiple X2Go sessions for the same session profile simultaneously.

    This method (`X2GoClient.register_session()`) accepts a similar set of parameters as the `x2go.session.X2GoSession` constructor itself. For a complete set of session options refer there.

    Alternatively, you can also pass a profile name or a profile id to this method. If you do this, Python X2Go tries to find the specified session in the `sessions` configuration node and then derives the necessary session parameters from the session profile configuration. Additional `x2go.session.X2GoSession` parameters can also be passed to this method—they will override the option values retrieved from the session profile.

    Parameters:

    - server (`str`) – hostname of the remote X2Go server (Default value = None)
    - profile_id (`str`) – id (config section name) of a session profile to load from your session config (Default value = None)
    - profile_name (`str`) – name of a session profile to load from your session config (Default value = None)
    - session_name (`str`) – session name to register (by its name) (Default value = None)
    - allow_printing (`bool`) – enable X2Go printing support for the to-be-registered X2Go session (Default value = False)
    - allow_share_local_folders (`bool`) – set local folder sharing to enabled/disabled (Default value = False)
    - share_local_folders (`list`) – a list of local folders (as strings) to be shared directly after session start up (Default value = [])
    - allow_mimebox (`bool`) – enable X2Go MIME box support for the to-be-registered X2Go session (Default value = False)
    - mimebox_extensions (`list`) – MIME box support is only allowed for the given file extensions (Default value = [])
    - mimebox_action (`str`) – MIME box action to use on incoming MIME job files (Default value = ‘OPEN’)
    - add_to_known_hosts (`bool`) – add unknown host keys to the `known_hosts` file and accept the connection automatically (Default value = False)
    - known_hosts (`str`) – full path to `known_hosts` file (Default value = None)
    - forward_sshagent (`bool`) – forward SSH agent authentication requests to the X2Go client-side (Default value = False)
    - proxy_options (`dict`) – a set of very `X2GoProxy*` backend specific options; any option that is not known to the `X2GoProxy*` backend will simply be ignored (Default value = {})
    - return_object (`bool`) – normally this method returns a unique session UUID. If `return_object` is set to `True` an X2GoSession object will be returned instead (Default value = False)
    - kwargs (`dict`) – any option that is also valid for the `x2go.session.X2GoSession` constructor

    Returns: | a unique identifier (UUID) for the newly registered X2Go session (or an X2GoSession object if `return_object` is set to True
    Return type: | `str`

  `resume_session`(session_uuid=None, session_name=None, match_profile_name=None, **sessionopts)

    Resume or continue a suspended / running X2Go session on a remote X2Go server (as specified when `register_session()` was called).

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - session_name (`str`) – the server-side name of an X2Go session (Default value = None)
    - match_profile_name (`str`) – only resume a session if this profile name matches (Default value = None)
    - sessionopts (`dict`) – pass-through of options directly to the session instance’s `X2GoSession.resume()` method

    Returns: | returns True if this method has been successful
    Return type: | `bool`
    Raises: | X2GoClientException – if the method does not know what session to resume

  `server_has_running_session_of_name`(session_uuid, session_name)

    Equals `True` if the X2Go server has a running session of name <session_name>.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - session_name (`str`) – session name

  `server_has_running_sessions`(session_uuid)

    Equals `True` if the X2Go server has any running sessions.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | `True`, if there are running sessions
    Return type: | `bool`

  `server_has_suspended_session_of_name`(session_uuid, session_name)

    Equals `True` if the X2Go server has a suspended session of name <session_name>.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - session_name (`str`) – session name

    Returns: | `True`, if there are running sessions
    Return type: | `bool`

  `server_has_suspended_sessions`(session_uuid)

    Equals `True` if the X2Go server has any suspended sessions.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash

  `server_is_alive`(session_uuid)

    Test if server that corresponds to the terminal session `session_uuid` is alive.

    If the session is not connected anymore the `X2GoClient.HOOK_on_control_session_death()` gets called.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | `True` if X2Go server connection for `x2go.session.X2GoSession` instance with <session_uuid> is alive.
    Return type: | `bool`
    Raises: | X2GoControlSessionException – if the session is not connected anymore; in that case the `HOOK_on_control_session_death()` gets called.

  `server_running_sessions`(session_uuid)

    Retrieve a list of session names of all server-side running sessions (including those not instantiated by our `x2go.client.X2GoClient` instance).

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | list of session names
    Return type: | `list`
    Raises: | X2GoClientException – if the session with UUID `session_uuid` is not connected

  `server_suspended_sessions`(session_uuid)

    Retrieve a list of session names of all server-side suspended sessions (including those not instantiated by our `x2go.client.X2GoClient` instance).

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | list of session names
    Return type: | `list`
    Raises: | X2GoClientException – if the session with UUID `session_uuid` is not connected

  `server_valid_x2gouser`(session_uuid, username=None)

    Check if user is allowed to start an X2Go session on a remote server.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - username (`str`) – user name to test validity for (Default value = None)

    Returns: | Is remote user allowed to start an X2Go session?
    Return type: | `str`

  `session_auto_connect`(session_uuid)

    Auto-connect a given session. This method is called from within the session itself and can be used to override the auto-connect procedure from within your client implementation.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | returns `True` if the session could be auto-connected.
    Return type: | `bool`

  `session_auto_start_or_resume`(session_uuid, newest=True, oldest=False, all_suspended=False, start=True)

    Automatically start or resume one or several sessions.

    This method is called from within the session itself on session registration, so this method can be used to handle auto-start/-resume events.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - newest (`bool`) – if resuming, only resume newest/youngest session (Default value = True)
    - oldest (`bool`) – if resuming, only resume oldest session (Default value = False)
    - all_suspended (`bool`) – if resuming, resume all suspended sessions (Default value = False)
    - start (`bool`) – if no session is to be resumed, start a new session (Default value = True)

  `session_can_auto_connect`(session_uuid)

    Check if session with unique identifier <session_uuid> is configured adequately to be able to auto-connect to the X2Go server (e.g. by public key authentication).

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | returns `True` if the session can auto-connect, `False` otherwise, `None` if no control session has been set up yet.
    Return type: | `bool`

  `session_can_sshproxy_auto_connect`(session_uuid)

    Check if the SSH proxy of session with unique identifier <session_uuid> is configured adequately to be able to auto-connect to the SSH proxy server (e.g. by public key authentication).

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | returns `True` if the session’s SSH proxy can auto-connect, `False` otherwise, `None` if no control session has been set up yet.
    Return type: | `bool`

  `session_get_shared_folders`(session_uuid=None, profile_name=None, check_list_mounts=False)

    Get a list of local folders mounted within X2Go session with session hash <session_uuid> from this client.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - profile_name (`str`) – alternatively, the profile name can be used to get mounted folders of a session connected profile (Default value = None)
    - check_list_mounts (`bool`) – query the server-side mount list for up-to-date information (Default value = False)

    Returns: | returns a `list` of those local folder names that are mounted within X2Go session <session_uuid>.
    Return type: | `list`

  `session_ok`(session_uuid)

    Test if the X2Go session registered as `session_uuid` is in a healthy state.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | `True` if session is ok, `False` otherwise
    Return type: | `bool`

  `session_reuses_sshproxy_authinfo`(session_uuid)

    Check if session with unique identifier <session_uuid> is configured to re-use the X2Go session’s password / key for proxy authentication, as well.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | returns `True` if the session is configured to re-use session password / key for proxy authentication
    Return type: | `bool`

  `session_uses_sshproxy`(session_uuid)

    Check if session with unique identifier <session_uuid> is configured to use an intermediate SSH proxy server.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash
    Returns: | returns `True` if the session is configured to use an SSH proxy, `False` otherwise.
    Return type: | `bool`

  `set_profile_config`(profile_id_or_name, parameter, value)

    Set individual session profile parameters for session profile `profile_id_or_name`.

    Parameters:

    - profile_id_or_name (`str`) – name or id of an X2Go session profile as found in the sessions configuration file
    - parameter (`str`) – set this parameter with the given `value`
    - value (`bool`, `int`, `str`, `list` or `dict`) – set this value for the given `parameter`

    Returns: | returns `True` if this operation has been successful
    Return type: | `dict`

  `set_session_print_action`(session_uuid, print_action, **kwargs)

    If X2Go client-side printing is enable within an X2Go session you can use this method to alter the way how incoming print spool jobs are handled/processed.

    Currently, there are five different print actions available, each defined as an individual print action class:

    > - PDFVIEW (`x2go.printactions.X2GoPrintActionPDFVIEW`): view an incoming spool job (a PDF file) locally in a PDF viewer
    > - PDFSAVE (`x2go.printactions.X2GoPrintActionPDFSAVE`): save an incoming spool job (a PDF file) under a nice name in a designated folder
    > - PRINT (`x2go.printactions.X2GoPrintActionPRINT`): really print the incoming spool job on a real printing device
    > - PRINTCMD `x2go.printactions.X2GoPrintActionPRINTCMD`: on each incoming spool job execute an external command that lets the client user handle the further processing of the print job (PDF) file
    > - DIALOG (`x2go.printactions.X2GoPrintActionDIALOG`): on each incoming spool job this print action will call `X2GoClient.HOOK_open_print_dialog()`

    Each of the print action classes accepts different print action arguments. For detail information on these print action arguments please refer to the constructor methods of each class individually.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - print_action (`str` or `instance`) – one of the named above print actions, either as string or class instance
    - kwargs (`dict`) – additional information for the given print action (print action arguments), for possible print action arguments and their values see each individual print action class

  `set_session_username`(session_uuid, username)

    Set the session username for the `x2go.session.X2GoSession` that has been registered under `session_uuid`. This can be helpful for modifying user credentials during an authentication phase.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - username (`str`) – new user name to be used for session authentication

    Returns: | returns `True` on success
    Return type: | `bool`

  `set_session_window_title`(session_uuid, title='')

    Modify session window title. If the session ID does not occur in the given title, it will be prepended, so that every X2Go session window always contains the X2Go session ID of that window.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - title (`str`) – new title for session window (Default value = ‘’)

  `share_desktop_session`(session_uuid, desktop=None, user=None, display=None, share_mode=0, check_desktop_list=False, **sessionopts)

    Share another already running desktop session. Desktop sharing can be run in two different modes: view-only and full-access mode. Like new sessions a to-be-shared session has be registered first with the `x2go.client.X2GoClient` instance.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - desktop (`str`) – desktop ID of a sharable desktop in format <user>@<display> (Default value = None)
    - user (`str`) – user name and display number can be given separately, here give the name of the user who wants to share a session with you. (Default value = None)
    - display (`str`) – user name and display number can be given separately, here give the number of the display that a user allows you to be shared with. (Default value = None)
    - share_mode (`int`) – desktop sharing mode, 0 is VIEW-ONLY, 1 is FULL-ACCESS. (Default value = 0)
    - sessionopts (`dict`) – pass-through of options directly to the session instance’s `X2GoSession.share_desktop()` method
    - check_desktop_list – check if the given desktop is available on the X2Go server; handle with care as the server-side `x2golistdesktops` command might block client I/O. (Default value = False)

    Returns: | True if the session could be successfully shared.
    Return type: | `bool`
    Raises: | X2GoDesktopSharingException – if a given desktop ID does not specify an available desktop session

  `share_local_folder`(session_uuid=None, local_path=None, profile_name=None, folder_name=None)

    Share a local folder with the X2Go session registered as `session_uuid`.

    When calling this method the given client-side folder is mounted on the X2Go server (via sshfs) and (if in desktop mode) provided as a desktop icon on your remote session’s desktop.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - local_path (`str`) – the full path to an existing folder on the local (client-side) file system (Default value = None)
    - folder_name (`str`) – synonymous to `local_path` (Default value = None)
    - profile_name (`str`) – alternatively, the profile name can be used to share local folders (Default value = None)

    Returns: | returns `True` if the local folder has been successfully mounted
    Return type: | `bool`

  `start_session`(session_uuid, **sessionopts)

    Start a new X2Go session on the remote X2Go server. This method will open—if everything has been successful till here—the X2Go session window.

    Before calling this method you have to register your desired session with `register_session()` (initialization of session parameters) and connect to it with `connect_session()` (authentication).

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - sessionopts (`dict`) – pass-through of options directly to the session instance’s `X2GoSession.start()` method

    Returns: | returns True if this method has been successful
    Return type: | `bool`

  `suspend_session`(session_uuid, session_name=None, match_profile_name=None, **sessionopts)

    Suspend an X2Go session.

    Normally, you will use this method to suspend a registered session that you have formerly started/resumed from within your recent `x2go.client.X2GoClient` instance. For this you simply call this method using the session’s `session_uuid`, leave the `session_name` empty.

    Alternatively, you can suspend a non-associated X2Go session: To do this you simply neeed to register (with the `register_session()` method) an X2Go session on the to-be-addressed remote X2Go server and connect (`connect_session()`) to it. Then call this method with the freshly obtained `session_uuid` and the remote X2Go session name (as shown e.g. in x2golistsessions output).

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - session_name (`str`) – the server-side name of an X2Go session (for non-associated session suspend) (Default value = None)
    - match_profile_name (`str`) – only suspend a session if this profile name matches (Default value = None)
    - sessionopts (`dict`) – pass-through of options directly to the session instance’s `X2GoSession.suspend()` method

    Returns: | returns True if this method has been successful
    Return type: | `bool`

  `terminate_session`(session_uuid, session_name=None, match_profile_name=None, **sessionopts)

    Terminate an X2Go session.

    Normally you will use this method to terminate a registered session that you have formerly started/resumed from within your recent `x2go.client.X2GoClient` instance. For this you simply call this method using the session’s `session_uuid`, leave the `session_name` empty.

    Alternatively, you can terminate a non-associated X2Go session: To do this you simply neeed to register (`register_session()`) an X2Go session on the to-be-addressed remote X2Go server and connect (`connect_session()`) to it. Then call this method with the freshly obtained `session_uuid` and the remote X2Go session name (as shown in e.g. x2golistsessions output).

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - session_name (`str`) – the server-side name of an X2Go session (Default value = None)
    - match_profile_name (`str`) – only terminate a session if this profile name matches (Default value = None)
    - sessionopts (`dict`) – pass-through of options directly to the session instance’s `X2GoSession.terminate()` method

    Returns: | returns True if this method has been successful
    Return type: | `bool`

  `to_profile_id`(profile_name)

    Retrieve the session profile ID of the session whose profile name is `profile_name`

    Parameters: | profile_name (`str`) – the session profile name
    Returns: | the session profile’s ID
    Return type: | `str`

  `to_profile_name`(profile_id)

    Retrieve the session profile name of the session whose profile ID is `profile_id`

    Parameters: | profile_id (`str`) – the session profile ID
    Returns: | the session profile’s name
    Return type: | `str`

  `unshare_all_local_folders`(session_uuid=None, profile_name=None)

    Unshare all local folders mounted in X2Go session registered as `session_uuid`.

    When calling this method all client-side mounted folders on the X2Go server (via sshfs) for session with ID <session_uuid> will get unmounted.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - profile_name (`str`) – alternatively, the profile name can be used to unshare mounted folders (Default value = None)

    Returns: | returns `True` if all local folders could be successfully unmounted
    Return type: | `bool`

  `unshare_all_local_folders_from_profile`(session_uuid=None, profile_name=None)

    Unshare all local folders mounted in X2Go session registered as `session_uuid`.

    When calling this method all client-side mounted folders on the X2Go server (via sshfs) for session with ID <session_uuid> will get unmounted.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - profile_name (`str`) – alternatively, the profile name can be used to unshare mounted folders (Default value = None)

    Returns: | returns `True` if all local folders could be successfully unmounted
    Return type: | `bool`

  `unshare_all_local_folders_from_session`(session_uuid=None, profile_name=None)

    Unshare all local folders mounted in X2Go session registered as `session_uuid`.

    When calling this method all client-side mounted folders on the X2Go server (via sshfs) for session with ID <session_uuid> will get unmounted.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - profile_name (`str`) – alternatively, the profile name can be used to unshare mounted folders (Default value = None)

    Returns: | returns `True` if all local folders could be successfully unmounted
    Return type: | `bool`

  `unshare_local_folder`(session_uuid=None, profile_name=None, local_path=None)

    Unshare local folder that is mounted in the X2Go session registered as `session_uuid`.

    When calling this method the given client-side mounted folder on the X2Go server (via sshfs) for session with ID <session_uuid> will get unmounted.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - profile_name (`str`) – alternatively, the profile name can be used to unshare mounted folders (Default value = None)
    - local_path (`str`) – the full path of a local folder that is mounted within X2Go session with session ID <session_uuid> (or recognized via profile name) and that shall be unmounted from that session. (Default value = None)

    Returns: | returns `True` if all local folders could be successfully unmounted
    Return type: | `bool`

  `unshare_local_folder_from_profile`(session_uuid=None, profile_name=None, local_path=None)

    Unshare local folder that is mounted in the X2Go session registered as `session_uuid`.

    When calling this method the given client-side mounted folder on the X2Go server (via sshfs) for session with ID <session_uuid> will get unmounted.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - profile_name (`str`) – alternatively, the profile name can be used to unshare mounted folders (Default value = None)
    - local_path (`str`) – the full path of a local folder that is mounted within X2Go session with session ID <session_uuid> (or recognized via profile name) and that shall be unmounted from that session. (Default value = None)

    Returns: | returns `True` if all local folders could be successfully unmounted
    Return type: | `bool`

  `unshare_local_folder_from_session`(session_uuid=None, profile_name=None, local_path=None)

    Unshare local folder that is mounted in the X2Go session registered as `session_uuid`.

    When calling this method the given client-side mounted folder on the X2Go server (via sshfs) for session with ID <session_uuid> will get unmounted.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)
    - profile_name (`str`) – alternatively, the profile name can be used to unshare mounted folders (Default value = None)
    - local_path (`str`) – the full path of a local folder that is mounted within X2Go session with session ID <session_uuid> (or recognized via profile name) and that shall be unmounted from that session. (Default value = None)

    Returns: | returns `True` if all local folders could be successfully unmounted
    Return type: | `bool`

  `update_cache_all_profiles`(cache_types='sessions', update_sessions=None, update_desktops=None, update_mounts=None)

    Update the session list cache of all session profiles.

    Parameters:

    - cache_types (`tuple` or `list`) – specify what cache type to update (available: `sessions`, `desktops`, `mounts`) (Default value = (‘sessions’)
    - update_sessions (`bool`) – instead of giving a list of cache types, plainly say `True` here, if you want to update sessions in the session list cache.
    - update_desktops (`bool`) – instead of giving a list of cache types, plainly say `True` here, if you want to update available desktops in the desktop list cache.
    - update_mounts (`bool`) – instead of giving a list of cache types, plainly say `True` here, if you want to update mounted shares in the mount list cache.

  `update_cache_by_profile_name`(profile_name, cache_types='sessions', update_sessions=None, update_desktops=None, update_mounts=None)

    Update the session list cache by profile name.

    Parameters:

    - profile_name (`str`) – the X2Go session profile name
    - cache_types (`tuple` or `list`) – specify what cache type to update (available: `sessions`, `desktops`, `mounts`) (Default value = (‘sessions’)
    - update_sessions (`bool`) – instead of giving a list of cache types, plainly say `True` here, if you want to update sessions in the session list cache.
    - update_desktops (`bool`) – instead of giving a list of cache types, plainly say `True` here, if you want to update available desktops in the desktop list cache.
    - update_mounts (`bool`) – instead of giving a list of cache types, plainly say `True` here, if you want to update mounted shares in the mount list cache.

  `update_cache_by_session_uuid`(session_uuid, cache_types='sessions', update_sessions=None, update_desktops=None, update_mounts=None)

    Update the session list cache of a specific `x2go.session.X2GoSession` instance with session identifier <session_uuid>.

    Parameters:

    - session_uuid (`str`) – the X2Go session’s UUID registry hash
    - cache_types (`tuple` or `list`) – specify what cache type to update (available: `sessions`, `desktops`, `mounts`) (Default value = (‘sessions’)
    - update_sessions (`bool`) – instead of giving a list of cache types, plainly say `True` here, if you want to update sessions in the session list cache.
    - update_desktops (`bool`) – instead of giving a list of cache types, plainly say `True` here, if you want to update available desktops in the desktop list cache.
    - update_mounts (`bool`) – instead of giving a list of cache types, plainly say `True` here, if you want to update mounted shares in the mount list cache.

  `update_sessionregistry_status_all_profiles`()

    Update the session registry stati of all session profiles.

  `update_sessionregistry_status_by_profile_name`(profile_name, session_list=None)

    Update the session registry stati by profile name.

    Parameters:

    - profile_name (`str`) – the X2Go session profile name
    - session_list (`X2GoServerList*` instances) – a manually passed on list of X2Go sessions (Default value = None)

  `update_sessionregistry_status_by_session_uuid`(session_uuid)

    Update the session registry status of a specific `x2go.session.X2GoSession` instance with session identifier <session_uuid>.

    Parameters: | session_uuid (`str`) – the X2Go session’s UUID registry hash

  `with_profile_config`(profile_id_or_name, parameter=None)

    Returns a dictionary with session options and values that represent the session profile for `profile_id_or_name`.

    Parameters:

    - profile_id_or_name (`str`) – name or id of an X2Go session profile as found in the sessions configuration file
    - parameter (`str`) – if specified, only the value for the given parameter is returned (Default value = None)

    Returns: | a Python dictionary with session profile options
    Return type: | `dict` or `bool`, `int`, `str`

  `with_session`(session_uuid)

    Alias for `get_session()`.