UpDevice: UPower Reference Manual

UpDevice

UpDevice — Client object for accessing information about UPower devices

Functions

UpDevice *	up_device_new ()
gchar *	up_device_to_text ()
gboolean	up_device_refresh_sync ()
gboolean	up_device_set_object_path_sync ()
GPtrArray *	up_device_get_history_sync ()
GPtrArray *	up_device_get_statistics_sync ()
const gchar *	up_device_get_object_path ()

Properties

guint	battery-level	Read / Write
gdouble	capacity	Read / Write
gdouble	energy	Read / Write
gdouble	energy-empty	Read / Write
gdouble	energy-full	Read / Write
gdouble	energy-full-design	Read / Write
gdouble	energy-rate	Read / Write
gboolean	has-history	Read / Write
gboolean	has-statistics	Read / Write
gchar *	icon-name	Read / Write
gboolean	is-present	Read / Write
gboolean	is-rechargeable	Read / Write
guint	kind	Read / Write
gdouble	luminosity	Read / Write
gchar *	model	Read / Write
gchar *	native-path	Read / Write
gboolean	online	Read / Write
gdouble	percentage	Read / Write
gboolean	power-supply	Read / Write
gchar *	serial	Read / Write
guint	state	Read / Write
guint	technology	Read / Write
gdouble	temperature	Read / Write
gint64	time-to-empty	Read / Write
gint64	time-to-full	Read / Write
guint64	update-time	Read / Write
gchar *	vendor	Read / Write
gdouble	voltage	Read / Write
guint	warning-level	Read / Write

Types and Values

#define	UP_DEVICE_ERROR
#define	UP_DEVICE_TYPE_ERROR

Object Hierarchy

    GObject
    ╰── UpDevice

Description

A helper GObject to use for accessing UPower devices, and to be notified when it is changed.

Functions

up_device_new ()

UpDevice *
up_device_new (void);

Creates a new UpDevice object.

Returns

a new UpDevice object.

Since: 0.9.0

up_device_to_text ()

gchar *
up_device_to_text (UpDevice *device);

Converts the device to a string description.

Parameters

device

a UpDevice instance.

Returns

text representation of UpDevice

Since: 0.9.0

up_device_refresh_sync ()

gboolean
up_device_refresh_sync (UpDevice *device,
                        GCancellable *cancellable,
                        GError **error);

Refreshes properties on the device. This function is normally not required.

Parameters

device	a UpDevice instance.
cancellable	a GCancellable or `NULL`
error	a GError, or `NULL`.

Returns

TRUE for success, else FALSE and error is used

Since: 0.9.0

up_device_set_object_path_sync ()

gboolean
up_device_set_object_path_sync (UpDevice *device,
                                const gchar *object_path,
                                GCancellable *cancellable,
                                GError **error);

Sets the object path of the object and fills up initial properties.

Parameters

device	a UpDevice instance.
object_path	The UPower object path.
cancellable	a GCancellable or `NULL`
error	a GError, or `NULL`.

Returns

TRUE for success, else FALSE and error is used

Since: 0.9.0

up_device_get_history_sync ()

GPtrArray *
up_device_get_history_sync (UpDevice *device,
                            const gchar *type,
                            guint timespec,
                            guint resolution,
                            GCancellable *cancellable,
                            GError **error);

Gets the device history.

Parameters

device	a UpDevice instance.
type	The type of history, known values are "rate" and "charge".
timespec	the amount of time to look back into time.
resolution	the resolution of data.
cancellable	a GCancellable or `NULL`
error	a GError, or `NULL`.

Returns

an array of UpHistoryItem's, with the most recent one being first; NULL if error is set or device is invalid.

[element-type UpHistoryItem][transfer full]

Since: 0.9.0

up_device_get_statistics_sync ()

GPtrArray *
up_device_get_statistics_sync (UpDevice *device,
                               const gchar *type,
                               GCancellable *cancellable,
                               GError **error);

Gets the device current statistics.

Parameters

device	a UpDevice instance.
type	the type of statistics.
cancellable	a GCancellable or `NULL`
error	a GError, or `NULL`.

Returns

an array of UpStatsItem's, else NULL and error is used.

[element-type UpStatsItem][transfer full]

Since: 0.9.0

up_device_get_object_path ()

const gchar *
up_device_get_object_path (UpDevice *device);

Gets the object path for the device.

Parameters

device

a UpDevice instance.

Returns

the object path, or NULL

Since: 0.9.0

Types and Values

UP_DEVICE_ERROR

#define UP_DEVICE_ERROR		(up_device_error_quark ())

UP_DEVICE_TYPE_ERROR

#define UP_DEVICE_TYPE_ERROR (up_device_error_get_type ())

Property Details

The `“battery-level”` property

  “battery-level”            guint

The battery level, e.g. UP_DEVICE_LEVEL_CRITICAL. If this is something other than UP_DEVICE_LEVEL_NONE, then User Interfaces should use this approximate level instead of percentages.

Flags: Read / Write

Allowed values: <= 9

Default value: 1

Since: 1.0

The `“capacity”` property

  “capacity”                 gdouble

The percentage capacity of the device where 100% means the device has the same charge potential as when it was manufactured.

Flags: Read / Write

Allowed values: [0,100]

Default value: 100

Since: 0.9.0

The `“energy”` property

  “energy”                   gdouble

The energy left in the device. Measured in mWh.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.0

The `“energy-empty”` property

  “energy-empty”             gdouble

The energy the device will have when it is empty. This is usually zero. Measured in mWh.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.0

The `“energy-full”` property

  “energy-full”              gdouble

The amount of energy when the device is fully charged. Measured in mWh.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.0

The `“energy-full-design”` property

  “energy-full-design”       gdouble

The amount of energy when the device was brand new. Measured in mWh.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.0

The `“energy-rate”` property

  “energy-rate”              gdouble

The rate of discharge or charge. Measured in mW.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.0

The `“has-history”` property

  “has-history”              gboolean

If the device has history data that might be useful.

Flags: Read / Write

Default value: FALSE

Since: 0.9.0

The `“has-statistics”` property

  “has-statistics”           gboolean

If the device has statistics data that might be useful.

Flags: Read / Write

Default value: FALSE

Since: 0.9.0

The `“icon-name”` property

  “icon-name”                gchar *

The icon name, following the Icon Naming Speficiation

Flags: Read / Write

Default value: NULL

Since: 1.0

The `“is-present”` property

  “is-present”               gboolean

If the device is present, as some devices like laptop batteries can be removed, leaving an empty bay that is still technically a device.

Flags: Read / Write

Default value: FALSE

Since: 0.9.0

The `“is-rechargeable”` property

  “is-rechargeable”          gboolean

If the device has a rechargable battery.

Flags: Read / Write

Default value: FALSE

Since: 0.9.0

The `“kind”` property

  “kind”                     guint

The device kind, e.g. UP_DEVICE_KIND_KEYBOARD.

Flags: Read / Write

Allowed values: <= 13

Default value: 0

Since: 0.9.0

The `“luminosity”` property

  “luminosity”               gdouble

The current luminosity of the device.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.19

The `“model”` property

  “model”                    gchar *

The model of the device.

Flags: Read / Write

Default value: NULL

Since: 0.9.0

The `“native-path”` property

  “native-path”              gchar *

The native path of the device, useful for direct device access.

Flags: Read / Write

Default value: NULL

Since: 0.9.0

The `“online”` property

  “online”                   gboolean

If the device is online, i.e. connected.

Flags: Read / Write

Default value: FALSE

Since: 0.9.0

The `“percentage”` property

  “percentage”               gdouble

The percentage charge of the device. Note that if the battery level property is something other than UP_DEVICE_LEVEL_NONE, then this percentage is an approximation, and should not be used a number to display to the user.

Flags: Read / Write

Allowed values: [0,100]

Default value: 100

Since: 0.9.0

The `“power-supply”` property

  “power-supply”             gboolean

If the device is powering the system.

Flags: Read / Write

Default value: FALSE

Since: 0.9.0

The `“serial”` property

  “serial”                   gchar *

The serial number of the device.

Flags: Read / Write

Default value: NULL

Since: 0.9.0

The `“state”` property

  “state”                    guint

The state the device is in at this time, e.g. UP_DEVICE_STATE_EMPTY.

Flags: Read / Write

Allowed values: <= 7

Default value: 0

Since: 0.9.0

The `“technology”` property

  “technology”               guint

The battery technology e.g. UP_DEVICE_TECHNOLOGY_LITHIUM_ION.

Flags: Read / Write

Allowed values: <= 7

Default value: 0

Since: 0.9.0

The `“temperature”` property

  “temperature”              gdouble

The temperature of the device in degrees Celsius.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.22

The `“time-to-empty”` property

  “time-to-empty”            gint64

The amount of time until the device is empty.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.0

The `“time-to-full”` property

  “time-to-full”             gint64

The amount of time until the device is fully charged.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.0

The `“update-time”` property

  “update-time”              guint64

The last time the device was updated.

Flags: Read / Write

Default value: 0

Since: 0.9.0

The `“vendor”` property

  “vendor”                   gchar *

The vendor of the device.

Flags: Read / Write

Default value: NULL

Since: 0.9.0

The `“voltage”` property

  “voltage”                  gdouble

The current voltage of the device.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.0

The `“warning-level”` property

  “warning-level”            guint

The warning level e.g. UP_DEVICE_LEVEL_CRITICAL.

Flags: Read / Write

Allowed values: <= 9

Default value: 0

Since: 1.0

UpDevice

Functions

Properties

Types and Values

Object Hierarchy

Description

Functions

up_device_new ()

Returns

up_device_to_text ()

Parameters

Returns

up_device_refresh_sync ()

Parameters

Returns

up_device_set_object_path_sync ()

Parameters

Returns

up_device_get_history_sync ()

Parameters

Returns

up_device_get_statistics_sync ()

Parameters

Returns

up_device_get_object_path ()

Parameters

Returns

Types and Values

UP_DEVICE_ERROR

UP_DEVICE_TYPE_ERROR

Property Details

The “battery-level” property

The “capacity” property

The “energy” property

The “energy-empty” property

The “energy-full” property

The “energy-full-design” property

The “energy-rate” property

The “has-history” property

The “has-statistics” property

The “icon-name” property

The “is-present” property

The “is-rechargeable” property

The “kind” property

The “luminosity” property

The “model” property

The “native-path” property

The “online” property

The “percentage” property

The “power-supply” property

The “serial” property

The “state” property

The “technology” property

The “temperature” property

The “time-to-empty” property

The “time-to-full” property

The “update-time” property

The “vendor” property

The “voltage” property

The “warning-level” property

See Also

The `“battery-level”` property

The `“capacity”` property

The `“energy”` property

The `“energy-empty”` property

The `“energy-full”` property

The `“energy-full-design”` property

The `“energy-rate”` property

The `“has-history”` property

The `“has-statistics”` property

The `“icon-name”` property

The `“is-present”` property

The `“is-rechargeable”` property

The `“kind”` property

The `“luminosity”` property

The `“model”` property

The `“native-path”` property

The `“online”` property

The `“percentage”` property

The `“power-supply”` property

The `“serial”` property

The `“state”` property

The `“technology”` property

The `“temperature”` property

The `“time-to-empty”` property

The `“time-to-full”` property

The `“update-time”` property

The `“vendor”` property

The `“voltage”` property

The `“warning-level”` property