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
double | capacity | Read / Write
char * | capacity-level | Read / Write
int | charge-cycles | Read / Write
guint | charge-end-threshold | Read / Write
guint | charge-start-threshold | Read / Write
gboolean | charge-threshold-enabled | Read / Write
gboolean | charge-threshold-supported | Read / Write
double | energy | Read / Write
double | energy-empty | Read / Write
double | energy-full | Read / Write
double | energy-full-design | Read / Write
double | energy-rate | Read / Write
gboolean | has-history | Read / Write
gboolean | has-statistics | Read / Write
char * | icon-name | Read / Write
gboolean | is-present | Read / Write
gboolean | is-rechargeable | Read / Write
guint | kind | Read / Write
double | luminosity | Read / Write
char * | model | Read / Write
char * | native-path | Read / Write
gboolean | online | Read / Write
double | percentage | Read / Write
gboolean | power-supply | Read / Write
char * | serial | Read / Write
guint | state | Read / Write
guint | technology | Read / Write
double | temperature | Read / Write
gint64 | time-to-empty | Read / Write
gint64 | time-to-full | Read / Write
guint64 | update-time | Read / Write
char * | vendor | Read / Write
double | voltage | Read / Write
double | voltage-max-design | Read / Write
double | voltage-min-design | 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);

`up_device_refresh_sync` is deprecated and should not be used in newly-written code.

Refreshes properties on the device. This function is normally not required and will only return without an error if the daemon was started in debug mode.

#### 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", "charge" and "voltage". |
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.

Owner: UpDevice

Flags: Read / Write

Allowed values: <= 9

Default value: 1

Since: 1.0

### The `“capacity”` property

      “capacity”                 double

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

Owner: UpDevice

Flags: Read / Write

Allowed values: [0,100]

Default value: 100

Since: 0.9.0

### The `“capacity-level”` property

      “capacity-level”           char *

Coarse representation of battery capacity. The value is one of the following: Unknown, Critical, Low, Normal, High, and Full.

Owner: UpDevice

Flags: Read / Write

Default value: NULL

Since: 1.90.10

### The `“charge-cycles”` property

      “charge-cycles”            int

The number of charge cycles for the battery, or -1 if unknown or non-applicable.

Owner: UpDevice

Flags: Read / Write

Allowed values: >= -1

Default value: -1

Since: 1.0

### The `“charge-end-threshold”` property

      “charge-end-threshold”     guint

The charge end threshold of a battery.

Owner: UpDevice

Flags: Read / Write

Allowed values: <= 100

Default value: 100

Since: 1.90.5

### The `“charge-start-threshold”` property

      “charge-start-threshold”   guint

The charge start threshold of a battery.

Owner: UpDevice

Flags: Read / Write

Allowed values: <= 100

Default value: 0

Since: 1.90.5

### The `“charge-threshold-enabled”` property

      “charge-threshold-enabled” gboolean

The charge threshold of a battery is enabled, or false if unknown or non-applicable.

Owner: UpDevice

Flags: Read / Write

Default value: FALSE

Since: 1.90.5

### The `“charge-threshold-supported”` property

      “charge-threshold-supported” gboolean

The charge threshold of a battery is supported, or false if unknown or non-applicable.

Owner: UpDevice

Flags: Read / Write

Default value: FALSE

Since: 1.90.5

### The `“energy”` property

      “energy”                   double

The energy left in the device. Measured in mWh.

Owner: UpDevice

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.0

### The `“energy-empty”` property

      “energy-empty”             double

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

Owner: UpDevice

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.0

### The `“energy-full”` property

      “energy-full”              double

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

Owner: UpDevice

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.0

### The `“energy-full-design”` property

      “energy-full-design”       double

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

Owner: UpDevice

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.0

### The `“energy-rate”` property

      “energy-rate”              double

The rate of discharge or charge. Measured in mW.

Owner: UpDevice

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.

Owner: UpDevice

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.

Owner: UpDevice

Flags: Read / Write

Default value: FALSE

Since: 0.9.0

### The `“icon-name”` property

      “icon-name”                char *

The icon name, following the Icon Naming Specification

Owner: UpDevice

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.

Owner: UpDevice

Flags: Read / Write

Default value: FALSE

Since: 0.9.0

### The `“is-rechargeable”` property

      “is-rechargeable”          gboolean

If the device has a rechargeable battery.

Owner: UpDevice

Flags: Read / Write

Default value: FALSE

Since: 0.9.0

### The `“kind”` property

      “kind”                     guint

The device kind, e.g. `UP_DEVICE_KIND_KEYBOARD`.

Owner: UpDevice

Flags: Read / Write

Allowed values: <= 29

Default value: 0

Since: 0.9.0

### The `“luminosity”` property

      “luminosity”               double

The current luminosity of the device.

NOTE: As of 1.91.1, this property is deprecated since the code it depends on was removed in 0.99.12.

Owner: UpDevice

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.19

### The `“model”` property

      “model”                    char *

The model of the device.

Owner: UpDevice

Flags: Read / Write

Default value: NULL

Since: 0.9.0

### The `“native-path”` property

      “native-path”              char *

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

Owner: UpDevice

Flags: Read / Write

Default value: NULL

Since: 0.9.0

### The `“online”` property

      “online”                   gboolean

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

Owner: UpDevice

Flags: Read / Write

Default value: FALSE

Since: 0.9.0

### The `“percentage”` property

      “percentage”               double

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.

Owner: UpDevice

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.

Owner: UpDevice

Flags: Read / Write

Default value: FALSE

Since: 0.9.0

### The `“serial”` property

      “serial”                   char *

The serial number of the device.

Owner: UpDevice

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`.

Owner: UpDevice

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`.

Owner: UpDevice

Flags: Read / Write

Allowed values: <= 7

Default value: 0

Since: 0.9.0

### The `“temperature”` property

      “temperature”              double

The temperature of the device in degrees Celsius.

Owner: UpDevice

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.

Owner: UpDevice

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.

Owner: UpDevice

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.

Owner: UpDevice

Flags: Read / Write

Default value: 0

Since: 0.9.0

### The `“vendor”` property

      “vendor”                   char *

The vendor of the device.

Owner: UpDevice

Flags: Read / Write

Default value: NULL

Since: 0.9.0

### The `“voltage”` property

      “voltage”                  double

The current voltage of the device.

Owner: UpDevice

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9.0

### The `“voltage-max-design”` property

      “voltage-max-design”       double

Owner: UpDevice

Flags: Read / Write

Allowed values: >= 0

Default value: 0

### The `“voltage-min-design”` property

      “voltage-min-design”       double

Owner: UpDevice

Flags: Read / Write

Allowed values: >= 0

Default value: 0

### The `“warning-level”` property

      “warning-level”            guint

The warning level e.g. `UP_DEVICE_LEVEL_CRITICAL`.

Owner: UpDevice

Flags: Read / Write

Allowed values: <= 9

Default value: 0

Since: 1.0

## See Also

UpClient