XdpPortal: libportal Reference Manual

## XdpPortal XdpPortal — context for portal calls |

## Functions

XdpPortal * | xdp_portal_new ()

## Signals

void | location-updated | Run First
void | notification-action-invoked | Run First
void | session-state-changed | Run First
void | spawn-exited | Run First
void | update-available | Run First
void | update-progress | Run First

## Types and Values

| XdpPortal

## Object Hierarchy

        GObject
        ╰── XdpPortal

## Description

The XdpPortal object provides the main context object for the portal operations of libportal.

Typically, an application will create a single XdpPortal object with `xdp_portal_new()` and use it throughout its lifetime.

## Functions

### xdp_portal_new ()

    XdpPortal *
    xdp_portal_new (void);

Creates a new XdpPortal object.

#### Returns

a newly created XdpPortal object

## Types and Values

### XdpPortal

    typedef struct _XdpPortal XdpPortal;

The XdpPortal struct contains only private fields and should not be accessed directly.

## Signal Details

### The `“location-updated”` signal

    void
    user_function (XdpPortal *portal,
                   int        latitude,
                   int        longitude,
                   int        altitude,
                   int        accuracy,
                   int        speed,
                   int        heading,
                   gint64     timestamp_s,
                   gint64     timestamp_ms,
                   gpointer   user_data)

The ::location-updated signal is emitted when location monitoring is enabled and the location changes.

#### Parameters

portal | the XdpPortal |
latitude | the latitude, in degrees |
longitude | the longitude, in degrees |
altitude | the altitude, in meters |
accuracy | the accuracy, in meters |
speed | the speed, in meters per second |
heading | the heading, in degrees |
timestamp_s | the timestamp seconds since the Unix epoch |
timestamp_ms | the microseconds fraction of the timestamp |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“notification-action-invoked”` signal

    void
    user_function (XdpPortal *portal,
                   char      *id,
                   char      *action,
                   GVariant  *parameter,
                   gpointer   user_data)

The ::notification-action-invoked signal is emitted when a non-exported action is activated on a notification.

#### Parameters

portal | the XdpPortal |
id | the notification ID |
action | the action name |
parameter | the target parameter for the action. | [nullable]
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“session-state-changed”` signal

    void
    user_function (XdpPortal           *portal,
                   gboolean             screensaver_active,
                   XdpLoginSessionState session_state,
                   gpointer             user_data)

This signal is emitted when session state monitoring is enabled and the state of the login session changes or the screensaver is activated or deactivated.

#### Parameters

portal | the XdpPortal object |
screensaver_active | whether the screensaver is active |
session_state | the current state of the login session |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“spawn-exited”` signal

    void
    user_function (XdpPortal *portal,
                   guint      pid,
                   guint      exit_status,
                   gpointer   user_data)

This signal is emitted when a process that was spawned with `xdp_portal_spawn()` exits.

#### Parameters

portal | the XdpPortal object |
pid | the pid of the process |
exit_status | the exit status of the process |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“update-available”` signal

    void
    user_function (XdpPortal *portal,
                   char      *running_commit,
                   char      *local_commit,
                   char      *remote_commit,
                   gpointer   user_data)

This signal is emitted when updates monitoring is enabled and a new update is available. It is only sent once with the same information, but it can be sent many times if new updates appear.

#### Parameters

portal | the XdpPortal object |
running_commit | the commit that the sandbox is running with |
local_commit | the commit that is currently deployed. Restarting the app will use this commit |
remote_commit | the commit that is available as an update. Updating the app will deloy this commit |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“update-progress”` signal

    void
    user_function (XdpPortal      *portal,
                   guint           n_ops,
                   guint           op,
                   guint           progress,
                   XdpUpdateStatus status,
                   char           *error,
                   char           *error_message,
                   gpointer        user_data)

This signal gets emitted to indicate progress of an update installation. It is undefined exactly how often it is sent, but it will be emitted at least once at the end with a non-zero `status` . For each successful operation in the update, we're also guaranteed to send exactly one signal with `progress` 100.

#### Parameters

portal | the XdpPortal object |
n_ops | the number of operations that the update consists of |
op | the position of the currently active operation |
progress | the progress of the currently active operation, as a number between 0 and 100 |
status | the overall status of the update |
error | the error name if the status is 'failed' |
error_message | the error message if the status is 'failed' |
user_data | user data set when the signal handler was connected. |

Flags: Run First