### Install Packages Asynchronously

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkClient

Starts an asynchronous process to install one or more packages. This operation may require user interaction for EULA or GPG key acceptance, which needs to be handled separately.

```c
pk_client_install_packages_async (client, packages, cancellable, callback_ready, user_data);
```

--------------------------------

### Compile Example C Code for PackageKit Session and System Services

Source: https://www.freedesktop.org/software/PackageKit/pk-faq

These commands compile C example code for interacting with PackageKit's session and system services. The session service provides a simplified interface handling EULA and GPG callbacks, while the system service offers raw DBUS methods for fine-grained transaction control. Ensure libgio-2.0 and packagekit-glib are installed.

```bash
gcc -o session -Wall session.c `pkg-config --cflags --libs gio-2.0`
gcc -o system -Wall system.c `pkg-config --cflags --libs packagekit-glib`
```

--------------------------------

### Install Signature Asynchronously (C)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkClient

Starts an asynchronous process to install a software source signature. This function requires a PkClient, signature type, key ID, package ID, and parameters for cancellation, progress, and completion callbacks.

```c
void
pk_client_install_signature_async (_PkClient *client_,
                                   _PkSigTypeEnum type_,
                                   _const gchar *key_id_,
                                   _const gchar *package_id_,
                                   _GCancellable *cancellable_,
                                   _PkProgressCallback progress_callback_,
                                   _gpointer progress_user_data_,
                                   _GAsyncReadyCallback callback_ready_,
                                   _gpointer user_data_);
```

--------------------------------

### PackageKit DBUS Methods for Application Integration

Source: https://www.freedesktop.org/software/PackageKit/pk-faq

Illustrates common DBUS methods used via PackageKit's shared session interface to perform package management tasks. These methods abstract complexities like EULA acceptance and GPG verification, allowing applications to initiate installations synchronously or asynchronously. Example methods include installing packages by name, file, MIME type, or font.

```dbus
InstallPackageName("openoffice-clipart")
InstallProvideFile("/usr/share/fonts/sarai/Sarai_07.ttf")
InstallLocalFile("/home/dave/Desktop/lirc-0.6.6-4.rhfc1.dag.i686.rpm")
InstallMimeType("application/x-rpm")
InstallFont("lang(en_GB)")
```

--------------------------------

### Install Packages using PackageKit D-Bus API (C)

Source: https://www.freedesktop.org/software/PackageKit/files/session

This C code snippet demonstrates how to install packages using the PackageKit D-Bus API. It establishes a connection to the session bus, creates a D-Bus proxy for the PackageKit Modify interface, and then calls the 'InstallPackageNames' method with a list of package names. Error handling is included for D-Bus operations.

```c
#include <gio/gio.h>

int
main (int argc, char *argv[])
{
	const gchar *packages[] = {"openoffice-clipart",
				   "openoffice-clipart-extras",
				   NULL};
	GDBusProxy *proxy = NULL;
	GError *error = NULL;
	guint32 xid = 0;
	GVariant *retval = NULL;

	/* get a session bus proxy */
	proxy = g_dbus_proxy_new_for_bus_sync (G_BUS_TYPE_SESSION,
					       G_DBUS_PROXY_FLAGS_NONE, NULL,
					       "org.freedesktop.PackageKit",
					       "/org/freedesktop/PackageKit",
					       "org.freedesktop.PackageKit.Modify",
					       NULL, &error);
	if (proxy == NULL) {
		g_warning ("failed: %s", error->message);
		g_error_free (error);
		goto out;
	}

	/* get the window ID, or use 0 for non-modal */
	//xid = GDK_WINDOW_XID (gtk_widget_get_window (dialog));

	/* issue the sync request */
	retval = g_dbus_proxy_call_sync (proxy,
					 "InstallPackageNames",
					 g_variant_new ("(u^a&ss)",
								xid,
								packages,
								"hide-finished"),
					 G_DBUS_CALL_FLAGS_NONE,
					 -1, /* timeout */
					 NULL, /* cancellable */
					 &error);
	if (retval == NULL) {
		g_warning ("failed: %s", error->message);
		g_error_free (error);
		goto out;
	}
out:
	if (proxy != NULL)
		g_object_unref (proxy);
	if (retval != NULL)
		g_object_unref (retval);
	return 0;
}

```

--------------------------------

### Get Prepared Updates

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit

Retrieves a list of package IDs for updates that have been prepared and are ready to be installed.

```DBus
GetPrepared (out 'as' package_ids)
```

--------------------------------

### Install packages

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkClient

Initiates the asynchronous installation of one or more packages. This function requires a PkClient instance and returns PkResults upon completion.

```c
PkResults *
pk_client_install_packages ();
```

```c
void
pk_client_install_packages_async ();
```

--------------------------------

### Get Software Updates using PackageKit C API

Source: https://www.freedesktop.org/software/PackageKit/files/system

This C code snippet demonstrates how to use the PackageKit GLib API to check for available software updates. It initializes PackageKit, verifies support for the 'GetUpdates' action, retrieves a list of new updates, and prints the details of each update. It handles potential errors and ensures proper deallocation of resources.

```c
#include <packagekit-glib/packagekit.h>

int
main (int argc, char *argv[])
{
	guint i;
	guint length;
	guiint ret;
	GError *error = NULL;
	const PkPackageObj *obj;
	PkPackageList *list = NULL;
	PkControl *control = NULL;
	PkClient *client = NULL;
	PkBitfield roles;

	/* find out if we can do GetUpdates */
	control = pk_control_new ();
	roles = pk_control_get_actions (control, NULL);
	if (!pk_bitfield_contain (roles, PK_ROLE_ENUM_GET_UPDATES)) {
		g_warning ("Backend does not support GetUpdates()\n");
		goto out;
	}

	/* create a new client instance */
	client = pk_client_new ();

	/* save all the results as we are not using an async callback */
	pk_client_set_use_buffer (client, TRUE, NULL);

	/* block for the results, does not require gtk_main() or anything */
	pk_client_set_synchronous (client, TRUE, NULL);

	/* get the update list (but only return the newest updates) */
	ret = pk_client_get_updates (client, PK_FILTER_ENUM_NEWEST, &error);
	if (!ret) {
		g_warning ("failed: %s\n", error->message);
		g_error_free (error);
		goto out;
	}

	/* get the buffered package list */
	list = pk_client_get_package_list (client);
	if (list == NULL) {
		g_warning ("failed to get buffered list\n");
		goto out;
	}

	length = pk_package_list_get_size (list);
	for (i=0; i<length; i++) {
		/* get each package to be updated, and print to the screen */
		obj = pk_package_list_get_obj (list, i);
		g_print ("%i. %s-%s.%s\t%s\n", i, obj->id->name, obj->id->version, obj->id->arch, obj->summary);
	}

out:
	/* free any GObjects we used */
	if (list != NULL)
		g_object_unref (list);
	if (control != NULL)
		g_object_unref (control);
	if (client != NULL)
		g_object_unref (client);
	return 0;
}

```

--------------------------------

### Transaction Examples

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/introduction-ideas-transactions

Illustrates different transaction scenarios, including success, failure due to no network, and handling of trusted and untrusted package installations.

```APIDOC
## Transaction Scenarios

### Description
Examples demonstrating various transaction outcomes and handling strategies.

### Scenarios
- **Success**: Characterized by a series of `::Progress()`, `::Package()`, and eventually `::Finished()` signals.
- **Failure (No Network)**: A fatal error where the transaction fails due to a lack of network connectivity. The client cannot requeue the transaction.
- **Trusted Installation**: Demonstrates installing a package with the `only_trusted` flag. If it fails, the client can re-request with `non-trusted` for alternative PolicyKit authentication.
- **Auto Untrusted Simulation**: When using `SimulateInstallPackage` or `SimulateInstallFile`, the client might receive an `INFO_UNTRUSTED` package. This indicates that the action would require the untrusted authentication type, and the client should proceed with `only_trusted=FALSE` to ensure only one authentication prompt.
```

--------------------------------

### Install Files Asynchronously (C)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkClient

Initiates an asynchronous installation of local files, resolving dependencies from repositories. This is suitable for installing packages like .rpm or .deb files directly. It requires a PkClient, transaction flags, an array of file paths, and parameters for cancellation, progress, and completion.

```c
void
pk_client_install_files_async (_PkClient *client_,
                               _PkBitfield transaction_flags_,
                               _gchar **files_,
                               _GCancellable *cancellable_,
                               _PkProgressCallback progress_callback_,
                               _gpointer progress_user_data_,
                               _GAsyncReadyCallback callback_ready_,
                               _gpointer user_data_);
```

--------------------------------

### InstallPackages

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/Transaction

Installs new packages on the local system, with options for automatic dependency installation and trusted packages only.

```APIDOC
## POST /websites/freedesktop_software_packagekit/InstallPackages

### Description
Installs new packages on the local system. It can automatically install extra packages if dependencies are found. This method typically emits Progress, Status, Error, and Package signals. The `transaction_flags` parameter can enforce installation of only trusted packages.

### Method
POST

### Endpoint
/websites/freedesktop_software_packagekit/InstallPackages

### Parameters
#### Query Parameters
- **transaction_flags** (int) - Required - If the transaction is only allowed to install trusted packages. Unsigned packages should not be installed if this transaction_flags has ONLY_TRUSTED.
- **package_ids** (array of strings) - Required - An array of package IDs to install.

### Request Example
```json
{
  "transaction_flags": 0, 
  "package_ids": ["package1", "package2"]
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation.

#### Response Example
```json
{
  "status": "completed"
}
```
```

--------------------------------

### Start PkClientHelper Process

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkClientHelper

Starts the helper process associated with a PkClientHelper instance. This function sets up a socket for communication and launches the specified executable with its arguments and environment. Returns TRUE on success and requires a GError pointer for error details. Available since 0.6.10.

```c
gboolean
pk_client_helper_start (_PkClientHelper *client_helper_,
                        _const gchar *socket_filename_,
                        _gchar **argv_,
                        _gchar **envp_,
                        _GError **error_);
```

--------------------------------

### Install Packages Asynchronously (C)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkClient

Initiates an asynchronous operation to install one or more packages. It takes a PkClient instance, transaction flags, an array of package IDs, cancellation and progress handling parameters, and a callback for completion.

```c
void
pk_client_install_packages_async (_PkClient *client_,
                                  _PkBitfield transaction_flags_,
                                  _gchar **package_ids_,
                                  _GCancellable *cancellable_,
                                  _PkProgressCallback progress_callback_,
                                  _gpointer progress_user_data_,
                                  _GAsyncReadyCallback callback_ready_,
                                  _gpointer user_data_);
```

--------------------------------

### Install Packages (Asynchronous)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkClient

Installs packages asynchronously. This is suitable for GUI applications as it does not block the main thread.

```APIDOC
## POST /pk_client_install_packages_async

### Description
Installs a package of the newest and most correct version asynchronously. This function is suitable for GUI applications.

### Method
POST

### Endpoint
/pk_client_install_packages_async

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **client** (_PkClient_*) - Required - A valid PkClient instance.
- **transaction_flags** (_PkBitfield_) - Required - A transaction type bitfield.
- **package_ids** (_gchar **_) - Required - A null-terminated array of package ID structures such as "hal;0.0.1;i386;fedora".
- **cancellable** (_GCancellable_*) - Optional - A GCancellable or NULL.
- **progress_callback** (_PkProgressCallback_*) - Optional - The function to run when the progress changes.
- **progress_user_data** (_gpointer_) - Optional - Data to pass to `progress_callback`.
- **callback_ready** (_GAsyncReadyCallback_*) - Required - The function to run on completion.
- **user_data** (_gpointer_) - Optional - Data to pass to `callback_ready`.

### Request Example
```json
{
  "client": "<PkClient_instance>",
  "transaction_flags": "<transaction_flags>",
  "package_ids": [
    "hal;0.0.1;i386;fedora"
  ],
  "cancellable": null,
  "progress_callback": null,
  "progress_user_data": null,
  "callback_ready": "<GAsyncReadyCallback_function>",
  "user_data": null
}
```

### Response
#### Success Response (200)
This endpoint does not return a value directly upon success. The result is delivered to the `callback_ready` function.

#### Response Example
N/A
```

--------------------------------

### Install Local Package Files

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/Transaction

Installs local package files onto the system, automatically handling dependencies. This method typically emits Progress, Status, Error, and Package. It requires transaction flags and an array of full file paths.

```PackageKit API
InstallFiles (in  't'  transaction_flags,
              in  'as' full_paths)
```

--------------------------------

### Get PkDetails Size (C)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkDetails

Retrieves the size of the package. For installed packages, it returns the installed size; otherwise, it returns the package size.

```c
guint64 pk_details_get_size (_PkDetails *details_);
```

--------------------------------

### Install packages programmatically using libpackagekit in C

Source: https://www.freedesktop.org/software/PackageKit/pk-using

This C code snippet demonstrates how to use the `libpackagekit` library to resolve and install packages. It utilizes `pk_task_new`, `pk_task_resolve_sync`, and `pk_task_install_packages_sync` functions. Error handling is included to report issues during the process. Requires GLib/GObject.

```c
GError *error = NULL;
PkError *error_code = NULL;
PkResults *results = NULL;
GPtrArray *array = NULL;
PkPackage *item;
gchar **values = NULL;
gchar **package_ids = NULL;
uint i;
PkTask *task;

task = pk_task_new ();

/* resolve the package name */
values = g_new0 (gchar*, 1 + 1);
values[0] = g_strdup ("openoffice-clipart");
values[1] = NULL;
results = pk_task_resolve_sync (task, PK_FILTER_ENUM_NOT_INSTALLED, values, NULL, NULL, NULL, &error);

/* check error code */
error_code = pk_results_get_error_code (results);
if (error_code != NULL) {
	g_printerr ("%s: %s, %s\n", "Resolving of packages failed",
		    pk_error_enum_to_string (pk_error_get_code (error_code)),
		    pk_error_get_details (error_code));
	goto out;
}

/* get the packages returned */
array = pk_results_get_package_array (results);
package_ids = g_new0 (gchar *, array->len+1);
for (i = 0; i < array->len; i++) {
	item = g_ptr_array_index (array, i);
	package_ids[i] = g_strdup (pk_package_get_id (item));
}

/* install the packages */
results = pk_task_install_packages_sync (task, package_ids , NULL, NULL, NULL, &error);

/* check error code */
error_code = pk_results_get_error_code (results);
if (error_code != NULL) {
	g_printerr ("%s: %s, %s\n", _("Error installing package(s)!"),
		pk_error_enum_to_string (pk_error_get_code (error_code)),
		pk_error_get_details (error_code));
	goto out;
}

out:
	g_strfreev (values);
	g_object_unref (task);
	if (error_code != NULL)
		g_object_unref (error_code);
	if (array != NULL)
		g_ptr_array_unref (array);
	if (package_ids != NULL)
		g_strfreev (package_ids);
	if (results != NULL)
		g_object_unref (results);


```

--------------------------------

### Install Packages (Synchronous)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkClient

Installs packages synchronously. This function may block and should not be used in GUI applications.

```APIDOC
## POST /pk_client_install_packages

### Description
Installs a package of the newest and most correct version. This function is synchronous and may block. Do not use it in GUI applications.

### Method
POST

### Endpoint
/pk_client_install_packages

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **client** (_PkClient_*) - Required - A valid PkClient instance.
- **transaction_flags** (_PkBitfield_) - Required - A transaction type bitfield.
- **package_ids** (_gchar **_) - Required - A null-terminated array of package ID structures such as "hal;0.0.1;i386;fedora".
- **cancellable** (_GCancellable_*) - Optional - A GCancellable or NULL.
- **progress_callback** (_PkProgressCallback_*) - Optional - The function to run when the progress changes.
- **progress_user_data** (_gpointer_) - Optional - Data to pass to `progress_callback`.
- **error** (_GError **_) - Optional - The GError to store any failure, or NULL.

### Request Example
```json
{
  "client": "<PkClient_instance>",
  "transaction_flags": "<transaction_flags>",
  "package_ids": [
    "hal;0.0.1;i386;fedora"
  ],
  "cancellable": null,
  "progress_callback": null,
  "progress_user_data": null,
  "error": null
}
```

### Response
#### Success Response (200)
- **PkResults** (_PkResults_*) - A PkResults object containing the results of the installation, or NULL if an error occurred.

#### Response Example
```json
{
  "result": "<PkResults_object>"
}
```

### Errors
- Standard GError information will be returned in the `error` parameter upon failure.
```

--------------------------------

### Install Packages Asynchronously

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkTask

Initiates an asynchronous operation to install a list of specified packages. It utilizes a progress callback for updates and a completion callback for notification.

```c
void
 pk_task_install_packages_async (_PkTask *task_,
                                _gchar **package_ids_,
                                _GCancellable *cancellable_,
                                _PkProgressCallback progress_callback_,
                                _gpointer progress_user_data_,
                                _GAsyncReadyCallback callback_ready_,
                                _gpointer user_data_);
```

--------------------------------

### InstallSignature

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/Transaction

Installs new security keys for package verification.

```APIDOC
## POST /websites/freedesktop_software_packagekit/InstallSignature

### Description
Allows the installation of new security keys, such as GPG keys, used for verifying package authenticity.

### Method
POST

### Endpoint
/websites/freedesktop_software_packagekit/InstallSignature

### Parameters
#### Query Parameters
- **sig_type** (string) - Required - A key type enum, e.g., 'gpg'.
- **key_id** (string) - Required - A key ID, e.g., 'BB7576AC'.
- **package_id** (string) - Required - The PackageID for the package that the user is trying to install.

### Request Example
```json
{
  "sig_type": "gpg", 
  "key_id": "BB7576AC",
  "package_id": "example-package"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation.

#### Response Example
```json
{
  "status": "completed"
}
```
```

--------------------------------

### Install Signature (Asynchronous)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkClient

Installs a software repository signature asynchronously. This is suitable for GUI applications as it does not block the main thread.

```APIDOC
## POST /pk_client_install_signature_async

### Description
Installs a software repository signature of the newest and most correct version asynchronously.

### Method
POST

### Endpoint
/pk_client_install_signature_async

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **client** (_PkClient_*) - Required - A valid PkClient instance.
- **type** (_PkSigTypeEnum_*) - Required - The signature type, e.g. `PK_SIGTYPE_ENUM_GPG`.
- **key_id** (_const gchar *_) - Required - A key ID such as "0df23df".
- **package_id** (_const gchar *_) - Required - A signature ID structure such as "hal;0.0.1;i386;fedora".
- **cancellable** (_GCancellable_*) - Optional - A GCancellable or NULL.
- **progress_callback** (_PkProgressCallback_*) - Optional - The function to run when the progress changes.
- **progress_user_data** (_gpointer_) - Optional - Data to pass to `progress_callback`.
- **callback_ready** (_GAsyncReadyCallback_*) - Required - The function to run on completion.
- **user_data** (_gpointer_) - Optional - Data to pass to `callback_ready`.

### Request Example
```json
{
  "client": "<PkClient_instance>",
  "type": "PK_SIGTYPE_ENUM_GPG",
  "key_id": "0df23df",
  "package_id": "hal;0.0.1;i386;fedora",
  "cancellable": null,
  "progress_callback": null,
  "progress_user_data": null,
  "callback_ready": "<GAsyncReadyCallback_function>",
  "user_data": null
}
```

### Response
#### Success Response (200)
This endpoint does not return a value directly upon success. The result is delivered to the `callback_ready` function.

#### Response Example
N/A
```

--------------------------------

### pk_client_install_files_async

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkClient

Asynchronously installs a local file and resolves its dependencies from repositories.

```APIDOC
## pk_client_install_files_async

### Description
Install a file locally, and get the deps from the repositories. This is useful for double clicking on a .rpm or .deb file.

### Method
[ASYNCHRONOUS]

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- client (_PkClient) - a valid PkClient instance
- transaction_flags (_PkBitfield) - a transaction type bitfield
- files (_gchar **) - a file such as "/home/hughsie/Desktop/hal-devel-0.10.0.rpm".
- cancellable (_GCancellable or NULL)
- progress_callback (_PkProgressCallback) - the function to run when the progress changes.
- progress_user_data (_gpointer) - data to pass to _`progress_callback`_
- callback_ready (_GAsyncReadyCallback) - the function to run on completion
- user_data (_gpointer) - the data to pass to _`callback_ready`_

### Request Example
```c
pk_client_install_files_async(client, transaction_flags, files, cancellable, progress_callback, progress_user_data, callback_ready, user_data);
```

### Response
#### Success Response
- None (operation is asynchronous)

#### Response Example
```c
// The result will be delivered to the callback_ready function.
```
```

--------------------------------

### Get Package Files (C)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkClient

Synchronously retrieves the list of files installed for specified packages. It takes a PkClient instance, an array of package IDs, a cancellable object, and progress/error callbacks. Warning: This function is synchronous and may block; do not use in GUI applications.

```c
PkResults *
pk_client_get_files (_PkClient *client_,
                     _gchar **package_ids_,
                     _GCancellable *cancellable_,
                     _PkProgressCallback progress_callback_,
                     _gpointer progress_user_data_,
                     _GError **error_);
```

--------------------------------

### Get Installed Files for Packages (C)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-pk-client-sync

Retrieves a list of files installed by specified packages. This is a synchronous function that may block and should be avoided in GUI applications. It takes a client instance, an array of package IDs, and optional cancellable, progress callback, and error parameters.

```c
PkResults *
_pk_client_get_files (_PkClient *client_,
                     _gchar **package_ids_,
                     _GCancellable *cancellable_,
                     _PkProgressCallback progress_callback_,
                     _gpointer progress_user_data_,
                     _GError **error_);
```

--------------------------------

### Install Packages Async

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkTask

Asynchronously installs packages. This function merges in details about packages using resolve.

```APIDOC
## pk_task_install_packages_async

### Description
Asynchronously installs packages. This function merges in details about packages using resolve.

### Method
Asynchronous function call

### Endpoint
N/A (Function call)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
N/A (Asynchronous operation, completion is signaled via callback)

#### Response Example
N/A
```

--------------------------------

### Get Package File List Asynchronously

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkClient

Retrieves the list of files installed for a given set of package IDs asynchronously. It requires a PkClient instance, an array of package IDs, and optional cancellable and progress callback parameters. The result is returned via a completion callback.

```c
void
pk_client_get_files_async (_PkClient *client_,
                           _gchar **package_ids_,
                           _GCancellable *cancellable_,
                           _PkProgressCallback progress_callback_,
                           _gpointer progress_user_data_,
                           _GAsyncReadyCallback callback_ready_,
                           _gpointer user_data_);
```

--------------------------------

### PackageKit Resolve with Newest and Installed Filter

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/introduction-ideas-filters

Demonstrates resolving a package ('kernel') with a combined filter 'newest;installed', prioritizing the newest installed version.

```text
Resolve("kernel",filter="newest;installed")

Expected output:
kernel-2.6.29.5-191 (installed)
```

--------------------------------

### Install Signature (Synchronous)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkClient

Installs a software repository signature synchronously. This function may block and should not be used in GUI applications.

```APIDOC
## POST /pk_client_install_signature

### Description
Installs a software repository signature of the newest and most correct version. This function is synchronous and may block. Do not use it in GUI applications.

### Method
POST

### Endpoint
/pk_client_install_signature

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **client** (_PkClient_*) - Required - A valid PkClient instance.
- **type** (_PkSigTypeEnum_*) - Required - The signature type, e.g. `PK_SIGTYPE_ENUM_GPG`.
- **key_id** (_const gchar *_) - Required - A key ID such as "0df23df".
- **package_id** (_const gchar *_) - Required - A signature ID structure such as "hal;0.0.1;i386;fedora".
- **cancellable** (_GCancellable_*) - Optional - A GCancellable or NULL.
- **progress_callback** (_PkProgressCallback_*) - Optional - The function to run when the progress changes.
- **progress_user_data** (_gpointer_) - Optional - Data to pass to `progress_callback`.
- **error** (_GError **_) - Optional - The GError to store any failure, or NULL.

### Request Example
```json
{
  "client": "<PkClient_instance>",
  "type": "PK_SIGTYPE_ENUM_GPG",
  "key_id": "0df23df",
  "package_id": "hal;0.0.1;i386;fedora",
  "cancellable": null,
  "progress_callback": null,
  "progress_user_data": null,
  "error": null
}
```

### Response
#### Success Response (200)
- **PkResults** (_PkResults_*) - A PkResults object containing the results of the installation, or NULL if an error occurred.

#### Response Example
```json
{
  "result": "<PkResults_object>"
}
```

### Errors
- Standard GError information will be returned in the `error` parameter upon failure.
```

--------------------------------

### Get Repository List Synchronous - C

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkClient

Retrieves a list of installed system repositories synchronously. This function may block and should be avoided in GUI applications. It takes a PkClient instance, a bitfield of filters, an optional GCancellable, and progress callback details. Returns a PkResults object or NULL on error.

```c
PkResults *
pk_client_get_repo_list (_PkClient *client_,
                         _PkBitfield filters_,
                         _GCancellable *cancellable_,
                         _PkProgressCallback progress_callback_,
                         _gpointer progress_user_data_,
                         _GError **error_);
```

--------------------------------

### Install Files Synchronously with PackageKit

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkClient

Synchronously installs a local file (e.g., .rpm, .deb) and resolves its dependencies from repositories. This function may block and is not suitable for GUI applications. It returns a PkResults object or NULL on error and requires a PkClient instance and an array of file paths.

```c
PkResults *
pk_client_install_files (_PkClient *client_,
                         _PkBitfield transaction_flags_,
                         _gchar **files_,
                         _GCancellable *cancellable_,
                         _PkProgressCallback progress_callback_,
                         _gpointer progress_user_data_,
                         _GError **error_);
```

--------------------------------

### Install PackageKit Packages

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-pk-client-sync

Installs the newest and most correct version of specified packages. This function is synchronous and may block, making it unsuitable for GUI applications. It requires a client instance, transaction flags, an array of package IDs, a cancellable object, and callbacks for progress and error handling.

```c
PkResults *
pk_client_install_packages (_PkClient *client_,
                            _PkBitfield transaction_flags_,
                            _gchar **package_ids_,
                            _GCancellable *cancellable_,
                            _PkProgressCallback progress_callback_,
                            _gpointer progress_user_data_,
                            _GError **error_);
```

--------------------------------

### Install Packages Synchronously (C)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-pk-task-sync

Installs the newest and most correct versions of specified packages. This is a synchronous operation and may block, making it unsuitable for GUI applications. It returns a PkResults object upon successful installation or NULL if an error occurs.

```c
PkResults *
pk_task_install_packages_sync (_PkTask *task_,
                               _gchar **package_ids_,
                               _GCancellable *cancellable_,
                               _PkProgressCallback progress_callback_,
                               _gpointer progress_user_data_,
                               _GError **error_);
```

--------------------------------

### PkTask API

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/api-index-0-5-3

Synchronous task functions for installing, removing, and updating packages.

```APIDOC
## PkTask Functions

### Description
Provides synchronous functions for performing common package management tasks such as installing, removing, and updating packages.

### Functions
- **pk_task_install_files_sync**: Synchronously installs packages using a list of files.
- **pk_task_install_packages_sync**: Synchronously installs specified packages.
- **pk_task_remove_packages_sync**: Synchronously removes specified packages.
- **pk_task_update_packages_sync**: Synchronously updates specified packages.
```

--------------------------------

### Install Files Asynchronously with PackageKit

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkTask

Installs local files (e.g., .rpm, .deb) asynchronously, resolving dependencies from repositories. This is useful for operations like double-clicking package files. It takes a task instance, a list of file paths, and callbacks for progress and completion.

```c
void
pk_task_install_files_async (_PkTask *task_,
                             _gchar **files_,
                             _GCancellable *cancellable_,
                             _PkProgressCallback progress_callback_,
                             _gpointer progress_user_data_,
                             _GAsyncReadyCallback callback_ready_,
                             _gpointer user_data_);
```

--------------------------------

### PkClientHelper Functions

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/api-index-0-6-10

Functions for managing the PackageKit client helper, including starting and stopping its operations.

```APIDOC
## PkClientHelper API

### Description
Provides functions to manage the PackageKit client helper instance.

### Functions

#### `pk_client_helper_new`
Creates a new instance of the PkClientHelper.

#### `pk_client_helper_start`
Starts the operations of the PkClientHelper.

#### `pk_client_helper_stop`
Stops the operations of the PkClientHelper.
```

--------------------------------

### Get Packages with Filter

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/Transaction

Returns all available packages based on a specified filter. This method typically emits Progress, Error, and Package. The filter parameter is a bitfield, for example, 'none' or 'installed;~devel'.

```PackageKit API
GetPackages (in  't' filter)
```

--------------------------------

### Synchronously install packages using PkTask

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkTask

Installs the newest and most correct version of specified packages. This is a synchronous function and should not be used in GUI applications due to potential blocking. It requires a PkTask instance, a null-terminated array of package IDs, and optional parameters for cancellation and progress callbacks.

```c
PkResults *
pk_task_install_packages_sync (_PkTask *task_,
                               _gchar **package_ids_,
                               _GCancellable *cancellable_,
                               _PkProgressCallback progress_callback_,
                               _gpointer progress_user_data_,
                               _GError **error_);

```

--------------------------------

### Capture PackageKitd Crash Backtrace with GDB (Shell)

Source: https://www.freedesktop.org/software/PackageKit/pk-bugs

This guide explains how to use the GNU Debugger (gdb) to obtain a backtrace when the PackageKit daemon crashes. It requires installing debug information packages and involves starting gdb, running the daemon, triggering the crash, and then requesting the backtrace.

```shell
gdb /usr/libexec/packagekitd
(gdb) run --verbose
# In another window:
pkcon get updates
# Back in gdb shell:
bt
```

--------------------------------

### Install Files Synchronously with PackageKit

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-pk-task-sync

Installs a local file (e.g., RPM, DEB) and resolves its dependencies from repositories. This synchronous function may block and should not be used in GUI applications. It takes a task instance, an array of file paths, a cancellable object, progress callback details, and an error pointer.

```c
PkResults *
pk_task_install_files_sync (_PkTask *task_,
                            _gchar **files_,
                            _GCancellable *cancellable_,
                            _PkProgressCallback progress_callback_,
                            _gpointer progress_user_data_,
                            _GError **error_);
```

--------------------------------

### Get PkDetails Size (C)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkDetails

Retrieves the size of the software package from a PkDetails object. For installed packages, it returns the installed size; otherwise, it returns the package size. This function takes a PkDetails instance.

```c
guint64
pk_details_get_size (_PkDetails *details_);
```

--------------------------------

### Get Transaction UID (C)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkProgress

Retrieves the UID of the entity that started the transaction associated with the PkProgress instance. This helps in identifying the source of the operation.

```c
guint
pk_progress_get_uid (_PkProgress *progress_);
```

--------------------------------

### Get Repository List with Filter

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/Transaction

Retrieves the list of repositories configured on the system. This method should emit RepoDetail. It accepts a filter bitfield as input, such as 'none' or 'installed;~devel'.

```PackageKit API
GetRepoList (in  't' filter)
```

--------------------------------

### PK_TASK_REPAIR_SYSTEM_ASYNC

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkTask

Asynchronously initiates a system repair process to recover from broken dependencies and aborted installations.

```APIDOC
## pk_task_repair_system_async ()

### Description
Recover the system from broken dependencies and aborted installations.

### Method
ASYNC CALL

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
void pk_task_repair_system_async (
    _PkTask *task_,
    _GCancellable *cancellable_,
    _PkProgressCallback progress_callback_,
    _gpointer progress_user_data_,
    _GAsyncReadyCallback callback_ready_,
    _gpointer user_data_
);
```

### Response
#### Success Response (200)
N/A (Asynchronous callback)

#### Response Example
N/A
```

--------------------------------

### Get Total Bytes of PkPackageSack

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkPackageSack

Retrieves the total size, in bytes, of all packages contained within a PkPackageSack. This function is available starting from version 0.5.2.

```c
guint64
pk_package_sack_get_total_bytes (_PkPackageSack *sack_);
```

--------------------------------

### Get Available Updates

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/Transaction

Returns a list of installed packages that have available updates. It should only return the newest update for each package. Emits Progress, Error, and Package. Accepts a filter bitfield.

```PackageKit API
GetUpdates (in  't' filter)
```

--------------------------------

### PkDesktop: Create New Instance

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkDesktop

Creates a new PkDesktop instance. This method is currently unused and scheduled for removal in future library versions. It takes no arguments.

```c
PkDesktop *
_pk_desktop_new (_void_);

```

--------------------------------

### Set and Get PackageKit Progress Role (C)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkProgress

Functions to set and retrieve the role of a PackageKit progress operation. The role specifies the purpose of the operation, such as installation or removal.

```c
gboolean
pk_progress_set_role (_PkProgress *progress_, _PkRoleEnum role_);

PkRoleEnum
pk_progress_get_role (_PkProgress *progress_);
```

--------------------------------

### Get Package Data - C

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkPackage

Retrieves the data associated with a PkPackage, often the repository ID. Returns NULL if not set. Special IDs like 'installed' and 'local' are supported.

```c
const gchar *
packagekit_package_get_data (_PkPackage *package_);
```

--------------------------------

### PkClient Initialization and Error Handling

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkClient

This section covers the initialization of a PkClient instance and retrieving the error quark for PkClient errors.

```APIDOC
## PkClient Initialization and Error Quark

### Description
Provides functions to create a new PkClient instance and to obtain the error quark associated with PkClient errors.

### Functions

#### `pk_client_new (void)`

##### Description
Creates and returns a new PkClient instance. This instance serves as a GObject wrapper for PackageKit, simplifying the development of frontends.

##### Returns
A new PkClient instance.

##### Since
0.5.2

#### `pk_client_error_quark (void)`

##### Description
Returns the error quark for PkClientError. This is useful for handling specific errors returned by PkClient operations.

##### Returns
An error quark.

##### Since
0.5.2
```

--------------------------------

### PkDesktop API

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/api-index-0-5-3

Functions for desktop integration with PackageKit, including file association and database operations.

```APIDOC
## PkDesktop Functions

### Description
Functions for desktop-specific PackageKit operations, such as managing file associations and opening the package database.

### Functions
- **pk_desktop_get_files_for_package**: Retrieves files associated with a package for desktop use.
- **pk_desktop_get_package_for_file**: Determines the package that owns a given file.
- **pk_desktop_get_shown_for_package**: Checks if a package is currently displayed or managed.
- **pk_desktop_new**: Creates a new PkDesktop object.
- **pk_desktop_open_database**: Opens the PackageKit database for desktop access.
```

--------------------------------

### Get Package Data (C)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkPackage

Retrieves the data associated with a PkPackage, typically the repository ID. Special IDs like 'installed' and 'local' are supported. Returns NULL if the data is unset. Available since 0.6.4.

```c
const gchar *
pk_package_get_data (_PkPackage *package_);

```

--------------------------------

### Get Repository List Asynchronously with PackageKit Client

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkClient

Asynchronously retrieves a list of all repositories installed on the system. This function allows filtering the repository list based on provided criteria. It takes a PkClient instance and a PkBitfield for filters.

```c
void
pk_client_get_repo_list_async (_PkClient *client_,
                               _PkBitfield filters_,
                               _GCancellable *cancellable_,
                               _PkProgressCallback progress_callback_,
                               _gpointer progress_user_data_,
                               _GAsyncReadyCallback callback_ready_,
                               _gpointer user_data_);
```

--------------------------------

### Initialize PkClient

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkClient

Creates a new PkClient instance, which serves as a wrapper for PackageKit operations. This function is essential for initiating any interaction with the PackageKit system.

```c
PkClient *client = pk_client_new ();
```

--------------------------------

### Create New PkDetails Object (C)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkDetails

Constructs and returns a new PkDetails object. This function is the entry point for creating instances that will hold transaction details. It does not take any parameters.

```c
PkDetails *
pk_details_new (_void_);
```

--------------------------------

### Upgrade the entire system

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkClient

Initiates an asynchronous system-wide upgrade. This function requires a PkClient instance and can result in significant changes to installed packages.

```c
PkResults *
pk_client_upgrade_system ();
```

```c
void
pk_client_upgrade_system_async ();
```

--------------------------------

### Repair Package Management System Asynchronously - C

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkClient

Starts an asynchronous transaction to attempt recovery from a corrupted package management system, often caused by interrupted installations or forced package operations. It requires a PkClient, transaction flags, an optional cancellable object, a progress callback, and a completion callback with user data. Since version 0.8.1.

```c
void
pk_client_repair_system_async (_PkClient *client_,
                               _PkBitfield transaction_flags_,
                               _GCancellable *cancellable_,
                               _PkProgressCallback progress_callback_,
                               _gpointer progress_user_data_,
                               _GAsyncReadyCallback callback_ready_,
                               _gpointer user_data_);
```

--------------------------------

### Enable a repository

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkClient

Asynchronously enables a specified software repository. This function takes a PkClient instance and repository data as input.

```c
PkResults *
pk_client_repo_enable ();
```

```c
void
pk_client_repo_enable_async ();
```

--------------------------------

### PkTask - Install Packages (Asynchronous)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkTask

Initiates an asynchronous operation to install packages.

```APIDOC
## PK_TASK_INSTALL_PACKAGES_ASYNC

### Description
Asynchronously installs a package.

### Method
N/A (Asynchronous function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
N/A

### Response
#### Success Response (200)
N/A (This is an async operation initiator)

#### Response Example
N/A

### Parameters
- **task** (PkTask*) - A valid PkTask instance.
- **package_ids** (gchar**) - A null terminated array of package_id structures such as "hal;0.0.1;i386;fedora". [array zero-terminated=1]
- **cancellable** (GCancellable*) - A GCancellable or NULL.
- **progress_callback** (gpointer) - The function to run when the progress changes. [scope call]
- **progress_user_data** (gpointer) - Data to pass to _`progress_callback`_.
- **error** (GError**) - The GError to store any failure, or NULL.
```

--------------------------------

### Create a new PkPackage object

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkPackage

Initializes and returns a new PkPackage object. This is a fundamental step before manipulating package data.

```c
PkPackage *pk_package_new (void);
```

--------------------------------

### PackageKit Resolve with Installed Filter

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/introduction-ideas-filters

Shows how to resolve a package ('kernel') specifically filtering for only the installed versions.

```text
Resolve("kernel",filter="installed")

Expected output:
kernel-2.6.29.4-167 (installed)
kernel-2.6.29.5-191 (installed)
```

--------------------------------

### Get Package Summary - C

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PkPackage

Retrieves the summary of a PkPackage. Returns NULL if the summary is not set.

```c
const gchar *
packagekit_package_get_summary (_PkPackage *package_);
```

--------------------------------

### PkTask - Install Packages (Synchronous)

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/PackageKit-PkTask

Installs packages synchronously. This function is blocking and should not be used in GUI applications.

```APIDOC
## PK_TASK_INSTALL_PACKAGES_SYNC

### Description
Installs a package of the newest and most correct version. Warning: this function is synchronous, and may block. Do not use it in GUI applications.

### Method
N/A (Synchronous function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
N/A

### Response
#### Success Response (200)
- **PkResults** (*object*) - A PkResults object, or NULL for error.

#### Response Example
N/A

### Parameters
- **task** (PkTask) - A valid PkTask instance.
- **package_ids** (gchar**) - A null terminated array of package_id structures such as "hal;0.0.1;i386;fedora". [array zero-terminated=1]
- **cancellable** (GCancellable*) - A GCancellable or NULL.
- **progress_callback** (gpointer) - The function to run when the progress changes. [scope call]
- **progress_user_data** (gpointer) - Data to pass to _`progress_callback`_.
- **error** (GError**) - The GError to store any failure, or NULL.

Since: 0.5.3
```

--------------------------------

### PackageKit Resolve with Not Installed Filter

Source: https://www.freedesktop.org/software/PackageKit/gtk-doc/introduction-ideas-filters

Illustrates resolving a package ('kernel') using the '~installed' filter, which returns versions that are not currently installed.

```text
Resolve("kernel",filter="~installed")

Expected output:
kernel-2.6.30.1-203 (fedora-updates)
```