UpClient: UPower Reference Manual

## UpClient UpClient — Main client object for accessing the UPower daemon |

## Functions

UpClient * | up_client_new ()
UpClient * | up_client_new_full ()
void | up_client_new_async ()
UpClient * | up_client_new_finish ()
UpDevice * | up_client_get_display_device ()
char * | up_client_get_critical_action ()
GPtrArray * | up_client_get_devices ()
GPtrArray * | up_client_get_devices2 ()
void | up_client_get_devices_async ()
GPtrArray * | up_client_get_devices_finish ()
const gchar * | up_client_get_daemon_version ()
gboolean | up_client_get_lid_is_closed ()
gboolean | up_client_get_lid_is_present ()
gboolean | up_client_get_on_battery ()

## Properties

char * | daemon-version | Read
gboolean | lid-is-closed | Read
gboolean | lid-is-present | Read
gboolean | on-battery | Read

## Signals

void | device-added | Run Last
void | device-removed | Run Last

## Types and Values

#define | UP_CLIENT_ERROR
#define | UP_CLIENT_TYPE_ERROR

## Object Hierarchy

        GObject
        ╰── UpClient

## Description

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

## Functions

### up_client_new ()

    UpClient *
    up_client_new (void);

Creates a new UpClient object. If connecting to upowerd on D-Bus fails, this returns `NULL` and prints out a warning with the error message. Consider using `up_client_new_full()` instead which allows you to handle errors and cancelling long operations yourself.

#### Returns

a new UpClient object, or `NULL` on failure.

Since: 0.9.0

### up_client_new_full ()

    UpClient *
    up_client_new_full (GCancellable *cancellable,
                        GError **error);

Creates a new UpClient object. If connecting to upowerd on D-Bus fails, this returns `NULL` and sets `error` .

#### Parameters

cancellable | A GCancellable or `NULL`. | [allow-none]
error | Return location for error or `NULL`. |

#### Returns

a new UpClient object, or `NULL` on failure.

Since: 0.99.5

### up_client_new_async ()

    void
    up_client_new_async (GCancellable *cancellable,
                         GAsyncReadyCallback callback,
                         gpointer user_data);

Asynchronously creates a new UpClient object.

This is an asynchronous failable function.

#### Parameters

cancellable | a GCancellable or `NULL`. | [nullable]
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | the data to pass to `callback` |

Since: 0.99.14

### up_client_new_finish ()

    UpClient *
    up_client_new_finish (GAsyncResult *res,
                          GError **error);

Finishes an operation started with `up_client_new_async()`.

#### Parameters

res | a GAsyncResult obtained from the GAsyncReadyCallback passed to `up_client_new_async()` |
error | return location for error or `NULL` |

#### Returns

a UpClient or `NULL` if `error` is set. Free with `g_object_unref()`.

[transfer full]

Since: 0.99.14

### up_client_get_display_device ()

    UpDevice *
    up_client_get_display_device (UpClient *client);

Get the composite display device.

#### Parameters

client | a UpClient instance. |

#### Returns

a UpDevice object, or `NULL` on error.

[transfer full]

Since: 1.0

### up_client_get_critical_action ()

    char *
    up_client_get_critical_action (UpClient *client);

Gets a string representing the configured critical action, depending on availability.

#### Parameters

client | a UpClient instance. |

#### Returns

the action name, or `NULL` on error.

Since: 1.0

### up_client_get_devices ()

    GPtrArray *
    up_client_get_devices (UpClient *client);

`up_client_get_devices` has been deprecated since version 0.99.8 and should not be used in newly-written code.

Get a copy of the device objects. This function does not set the free function for the GPtrArray so you need use g_object_unref on all elements when you are finished with the array.

#### Parameters

client | a UpClient instance. |

#### Returns

an array of UpDevice objects or `NULL` on error, free with `g_ptr_array_unref()`.

[element-type UpDevice][transfer full]

Since: 0.9.0

### up_client_get_devices2 ()

    GPtrArray *
    up_client_get_devices2 (UpClient *client);

Get a copy of the device objects.

#### Parameters

client | a UpClient instance. |

#### Returns

an array of UpDevice objects or `NULL` on error, free with `g_ptr_array_unref()`.

[element-type UpDevice][transfer full]

Since: 0.99.8

### up_client_get_devices_async ()

    void
    up_client_get_devices_async (UpClient *client,
                                 GCancellable *cancellable,
                                 GAsyncReadyCallback callback,
                                 gpointer user_data);

Asynchronously fetches the list of UpDevice objects.

#### Parameters

client | a UpClient instance. |
cancellable | a GCancellable or `NULL`. | [nullable]
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | the data to pass to `callback` |

Since: 0.99.14

### up_client_get_devices_finish ()

    GPtrArray *
    up_client_get_devices_finish (UpClient *client,
                                  GAsyncResult *res,
                                  GError **error);

Finishes an operation started with `up_client_get_devices_async()`.

#### Parameters

client | a UpClient instance. |
res | a GAsyncResult obtained from the GAsyncReadyCallback passed to `up_client_get_devices_async()` |

#### Returns

an array of UpDevice objects or `NULL` on error.

[element-type UpDevice][transfer full]

### up_client_get_daemon_version ()

    const gchar *
    up_client_get_daemon_version (UpClient *client);

Get UPower daemon version.

#### Parameters

client | a UpClient instance. |

#### Returns

string containing the daemon version, e.g. 008

Since: 0.9.0

### up_client_get_lid_is_closed ()

    gboolean
    up_client_get_lid_is_closed (UpClient *client);

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

Get whether the laptop lid is closed.

#### Parameters

client | a UpClient instance. |

#### Returns

`TRUE` if lid is closed or `FALSE` otherwise.

Since: 0.9.0

### up_client_get_lid_is_present ()

    gboolean
    up_client_get_lid_is_present (UpClient *client);

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

Get whether a laptop lid is present on this machine.

#### Parameters

client | a UpClient instance. |

#### Returns

`TRUE` if the machine has a laptop lid

Since: 0.9.2

### up_client_get_on_battery ()

    gboolean
    up_client_get_on_battery (UpClient *client);

Get whether the system is running on battery power.

#### Parameters

client | a UpClient instance. |

#### Returns

`TRUE` if the system is currently running on battery, `FALSE` otherwise.

Since: 0.9.0

## Types and Values

### UP_CLIENT_ERROR

    #define UP_CLIENT_ERROR			(up_client_error_quark ())

### UP_CLIENT_TYPE_ERROR

    #define UP_CLIENT_TYPE_ERROR		(up_client_error_get_type ())

## Property Details

### The `“daemon-version”` property

      “daemon-version”           char *

The daemon version.

Owner: UpClient

Flags: Read

Default value: NULL

Since: 0.9.0

### The `“lid-is-closed”` property

      “lid-is-closed”            gboolean

If the laptop lid is closed.

Owner: UpClient

Flags: Read

Default value: FALSE

Since: 0.9.0

### The `“lid-is-present”` property

      “lid-is-present”           gboolean

If a laptop lid is present.

Owner: UpClient

Flags: Read

Default value: FALSE

Since: 0.9.0

### The `“on-battery”` property

      “on-battery”               gboolean

If the computer is on battery power.

Owner: UpClient

Flags: Read

Default value: FALSE

Since: 0.9.0

## Signal Details

### The `“device-added”` signal

    void
    user_function (UpClient *client,
                   UpDevice *device,
                   gpointer  user_data)

The ::device-added signal is emitted when a power device is added.

#### Parameters

client | the UpClient instance that emitted the signal |
device | the UpDevice that was added. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.9.0

### The `“device-removed”` signal

    void
    user_function (UpClient *client,
                   char     *object_path,
                   gpointer  user_data)

The ::device-removed signal is emitted when a power device is removed.

#### Parameters

client | the UpClient instance that emitted the signal |
object_path | the object path of the UpDevice that was removed. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0

## See Also

UpDevice