Session: libportal Reference Manual

## Session Session — session state changes |

## Functions

void | xdp_portal_session_inhibit ()
int | xdp_portal_session_inhibit_finish ()
void | xdp_portal_session_uninhibit ()
void | xdp_portal_session_monitor_start ()
gboolean | xdp_portal_session_monitor_start_finish ()
void | xdp_portal_session_monitor_stop ()
void | xdp_portal_session_monitor_query_end_response ()

## Types and Values

enum | XdpInhibitFlags
enum | XdpSessionState
enum | XdpSessionMonitorFlags

## Description

These functions let applications inhibit certain login session state changes, and be informed about the impending end of the session.

A typical use for this functionality is to prevent the session from locking while a video is playing.

The underlying portal is org.freedesktop.portal.Inhibit.

## Functions

### xdp_portal_session_inhibit ()

    void
    xdp_portal_session_inhibit (XdpPortal *portal,
                                XdpParent *parent,
                                const char *reason,
                                XdpInhibitFlags inhibit,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer data);

Inhibits various session status changes.

To obtain an ID that can be used to undo the inhibition, use `xdp_portal_session_inhibit_finish()` in the callback.

To remove an active inhibitor, call `xdp_portal_session_uninhibit()` with the same ID.

#### Parameters

portal | a XdpPortal |
parent | parent window information. | [nullable]
reason | user-visible reason for the inhibition. | [nullable]
flags | information about what to inhibit |
cancellable | optional GCancellable. | [nullable]
callback | a callback to call when the request is done. | [scope async]
data | data to pass to `callback` . | [closure]

### xdp_portal_session_inhibit_finish ()

    int
    xdp_portal_session_inhibit_finish (XdpPortal *portal,
                                       GAsyncResult *result,
                                       GError **error);

Finishes the inhbit request, and returns the ID of the inhibition as a positive integer. The ID can be passed to `xdg_portal_session_uninhibit()` to undo the inhibition.

#### Parameters

portal | a XdpPortal |
result | a GAsyncResult |
error | return location for an error |

#### Returns

the ID of the inhibition, or -1 if there was an error

### xdp_portal_session_uninhibit ()

    void
    xdp_portal_session_uninhibit (XdpPortal *portal,
                                  int id);

Removes an inhibitor that was created by a call to `xdp_portal_session_inhibit()`.

#### Parameters

portal | a XdpPortal |
id | unique ID for an active inhibition |

### xdp_portal_session_monitor_start ()

    void
    xdp_portal_session_monitor_start (XdpPortal *portal,
                                      XdpParent *parent,
                                      XdpSessionMonitorFlags flags,
                                      GCancellable *cancellable,
                                      GAsyncReadyCallback callback,
                                      gpointer data);

Makes XdpPortal start monitoring the login session state.

When the state changes, the “session-state-changed” signal is emitted.

Use `xdp_portal_session_monitor_stop()` to stop monitoring.

#### Parameters

portal | a XdpPortal |
parent | a XdpParent, or `NULL`. | [nullable]
flags | options for this call |
cancellable | optional GCancellable. | [nullable]
callback | a callback to call when the request is done. | [scope async]
data | data to pass to `callback` . | [closure]

### xdp_portal_session_monitor_start_finish ()

    gboolean
    xdp_portal_session_monitor_start_finish
                                   (XdpPortal *portal,
                                    GAsyncResult *result,
                                    GError **error);

Finishes a session-monitor request, and returns the result in the form of boolean.

#### Parameters

portal | a XdpPortal |
result | a GAsyncResult |
error | return location for an error |

#### Returns

`TRUE` if the request succeeded

### xdp_portal_session_monitor_stop ()

    void
    xdp_portal_session_monitor_stop (XdpPortal *portal);

Stops session state monitoring that was started with `xdp_portal_session_monitor_start()`.

#### Parameters

portal | a XdpPortal |

### xdp_portal_session_monitor_query_end_response ()

    void
    xdp_portal_session_monitor_query_end_response
                                   (XdpPortal *portal);

This method should be called within one second of receiving a “session-state-changed” signal with the 'Query End' state, to acknowledge that they have handled the state change.

Possible ways to handle the state change are either to call `xdp_portal_session_inhibit()` to prevent the session from ending, or to save your state and get ready for the session to end.

#### Parameters

portal | a XdpPortal |

## Types and Values

### enum XdpInhibitFlags

Flags that determine what session status changes are inhibited.

#### Members

XDP_INHIBIT_FLAG_LOGOUT | Inhibit logout |
XDP_INHIBIT_FLAG_USER_SWITCH | Inhibit user switching |
XDP_INHIBIT_FLAG_SUSPEND | Inhibit suspend |
XDP_INHIBIT_FLAG_IDLE | Inhibit the session going idle |

### enum XdpSessionState

The state of a session.

#### Members

XDP_SESSION_INITIAL | the session has not been started. |
XDP_SESSION_ACTIVE | the session is active. |
XDP_SESSION_CLOSED | the session is no longer active. |

### enum XdpSessionMonitorFlags

#### Members

XDP_SESSION_MONITOR_FLAG_NONE |  |