zif-utils

## zif-utils zif-utils — Simple utility functions |

## Synopsis

    #define             ZIF_PACKAGE_ID_ARCH
    #define             ZIF_PACKAGE_ID_DATA
    #define             ZIF_PACKAGE_ID_NAME
    #define             ZIF_PACKAGE_ID_VERSION
    #define             ZIF_UTILS_ERROR
    enum                ZifUtilsError;
    gboolean            zif_arch_is_native                  (const gchar *a,
                                                             const gchar *b);
    gboolean            zif_boolean_from_text               (const gchar *text);
    gint                zif_compare_evr                     (const gchar *a,
                                                             const gchar *b);
    gint                zif_compare_evr_full                (const gchar *a,
                                                             const gchar *b,
                                                             ZifPackageCompareMode compare_mode);
    gboolean            zif_file_decompress                 (const gchar *in,
                                                             const gchar *out,
                                                             ZifState *state,
                                                             GError **error);
    gchar *             zif_file_get_uncompressed_name      (const gchar *filename);
    gboolean            zif_file_is_compressed_name         (const gchar *filename);
    gboolean            zif_file_untar                      (const gchar *filename,
                                                             const gchar *directory,
                                                             GError **error);
    const gchar *       zif_guess_content_type              (const gchar *filename);
    void                zif_list_print_array                (GPtrArray *array);
    gboolean            zif_package_convert_evr             (gchar *evr,
                                                             const gchar **epoch,
                                                             const gchar **version,
                                                             const gchar **release);
    gboolean            zif_package_convert_evr_full        (gchar *evr,
                                                             const gchar **epoch,
                                                             const gchar **version,
                                                             const gchar **release,
                                                             const gchar **distro);
    gchar *             zif_package_id_build                (const gchar *name,
                                                             const gchar *version,
                                                             const gchar *arch,
                                                             const gchar *data);
    gboolean            zif_package_id_check                (const gchar *package_id);
    gboolean            zif_package_id_compare_nevra        (const gchar *package_id1,
                                                             const gchar *package_id2);
    gchar *             zif_package_id_convert_basic        (const gchar *package_id);
    gchar *             zif_package_id_from_nevra           (const gchar *name,
                                                             guint epoch,
                                                             const gchar *version,
                                                             const gchar *release,
                                                             const gchar *arch,
                                                             const gchar *data);
    gchar *             zif_package_id_get_name             (const gchar *package_id);
    gchar *             zif_package_id_get_printable        (const gchar *package_id);
    gchar **            zif_package_id_split                (const gchar *package_id);
    gboolean            zif_package_id_to_nevra             (const gchar *package_id,
                                                             gchar **name,
                                                             guint *epoch,
                                                             gchar **version,
                                                             gchar **release,
                                                             gchar **arch);
    guint               zif_time_string_to_seconds          (const gchar *value);
    GQuark              zif_utils_error_quark               (void);
    gboolean            zif_utils_gpg_verify                (const gchar *filename,
                                                             const gchar *filename_gpg,
                                                             GError **error);

## Description

Common, non-object functions are declared here.

## Details

### ZIF_PACKAGE_ID_ARCH

    #define ZIF_PACKAGE_ID_ARCH 2

### ZIF_PACKAGE_ID_DATA

    #define ZIF_PACKAGE_ID_DATA 3

### ZIF_PACKAGE_ID_NAME

    #define ZIF_PACKAGE_ID_NAME 0

### ZIF_PACKAGE_ID_VERSION

    #define ZIF_PACKAGE_ID_VERSION 1

### ZIF_UTILS_ERROR

    #define ZIF_UTILS_ERROR (zif_utils_error_quark ())

### enum ZifUtilsError

    typedef enum {
    	ZIF_UTILS_ERROR_FAILED,
    	ZIF_UTILS_ERROR_FAILED_TO_READ,
    	ZIF_UTILS_ERROR_FAILED_TO_WRITE,
    	ZIF_UTILS_ERROR_CANCELLED,
    	ZIF_UTILS_ERROR_LAST
    } ZifUtilsError;

`ZIF_UTILS_ERROR_FAILED` |
`ZIF_UTILS_ERROR_FAILED_TO_READ` |
`ZIF_UTILS_ERROR_FAILED_TO_WRITE` |
`ZIF_UTILS_ERROR_CANCELLED` |
`ZIF_UTILS_ERROR_LAST` |

### zif_arch_is_native ()

    gboolean            zif_arch_is_native                  (const gchar *a,
                                                             const gchar *b);

Compare two architectures to see if they are native, so for instance i386 is native on a i686 system, but x64 isn't.

`a` : | The first arch string
`b` : | The second arch string
Returns : | `TRUE` if the architecture is compatible

Since 0.1.3

### zif_boolean_from_text ()

    gboolean            zif_boolean_from_text               (const gchar *text);

Convert a text boolean into it's enumerated boolean state

`text` : | The input text
Returns : | `TRUE` for positive, `FALSE` for negative

Since 0.1.0

### zif_compare_evr ()

    gint                zif_compare_evr                     (const gchar *a,
                                                             const gchar *b);

Compare two [epoch:]version[-release] strings

`a` : | The first version string, or `NULL`
`b` : | The second version string, or `NULL`
Returns : | 1 for a>b, 0 for a==b, -1 for b>a

Since 0.1.0

### zif_compare_evr_full ()

    gint                zif_compare_evr_full                (const gchar *a,
                                                             const gchar *b,
                                                             ZifPackageCompareMode compare_mode);

Compare two [epoch:]version[-release] strings

`a` : | The first version string, or `NULL`
`b` : | The second version string, or `NULL`
`compare_mode` : | the way the versions are compared
Returns : | 1 for a>b, 0 for a==b, -1 for b>a

Since 0.2.1

### zif_file_decompress ()

    gboolean            zif_file_decompress                 (const gchar *in,
                                                             const gchar *out,
                                                             ZifState *state,
                                                             GError **error);

Decompress files into a directory

`in` : | A filename to unpack
`out` : | The file to create
`state` : | A ZifState to use for progress reporting
`error` : | A `GError`
Returns : | `TRUE` if the file was decompressed

Since 0.1.0

### zif_file_get_uncompressed_name ()

    gchar *             zif_file_get_uncompressed_name      (const gchar *filename);

Finds the uncompressed filename for a compressed file.

`filename` : | A filename, e.g. "/lib/dave.tar.gz"
Returns : | The uncompressed file name, e.g. /lib/dave.tar, use `g_free()` to free.

Since 0.1.0

### zif_file_is_compressed_name ()

    gboolean            zif_file_is_compressed_name         (const gchar *filename);

Finds out if the filename is compressed

`filename` : | A filename, e.g. /lib/dave.tar.gz
Returns : | `TRUE` if the file needs decompression

Since 0.1.0

### zif_file_untar ()

    gboolean            zif_file_untar                      (const gchar *filename,
                                                             const gchar *directory,
                                                             GError **error);

Untar files into a directory

`filename` : | A filename to unpack
`directory` : | The directory to unpack into
`error` : | A `GError`
Returns : | `TRUE` if the file was decompressed

Since 0.1.0

### zif_guess_content_type ()

    const gchar *       zif_guess_content_type              (const gchar *filename);

Guesses a content type, based on the filename ending.

`filename` : | The target filename
Returns : | a content type, or `NULL`

Since 0.1.5

### zif_list_print_array ()

    void                zif_list_print_array                (GPtrArray *array);

Print an array of strings to `STDOUT`.

`array` : | An array of ZifPackage's to print

Since 0.1.0

### zif_package_convert_evr ()

    gboolean            zif_package_convert_evr             (gchar *evr,
                                                             const gchar **epoch,
                                                             const gchar **version,
                                                             const gchar **release);

Modifies evr, so pass in copy

`evr` : | epoch, version, release
`epoch` : | The package epoch
`version` : | The package version
`release` : | The package release (note: with any distro)
Returns : | `TRUE` if the EVR was parsed

Since 0.1.0

### zif_package_convert_evr_full ()

    gboolean            zif_package_convert_evr_full        (gchar *evr,
                                                             const gchar **epoch,
                                                             const gchar **version,
                                                             const gchar **release,
                                                             const gchar **distro);

Modifies evr, so pass in copy

`evr` : | epoch, version, release
`epoch` : | The package epoch
`version` : | The package version
`release` : | The package release
`distro` : | The package distro, or `NULL`
Returns : | `TRUE` if the EVR was parsed

Since 0.2.1

### zif_package_id_build ()

    gchar *             zif_package_id_build                (const gchar *name,
                                                             const gchar *version,
                                                             const gchar *arch,
                                                             const gchar *data);

Formats a PackageId structure.

`name` : | The package name, e.g. "hal"
`version` : | The package version, e.g. "1.0.0-fc14"
`arch` : | The package architecture, e.g. "i386"
`data` : | The package data, typically the repo name, or "installed"
Returns : | A PackageId value, or `NULL` if invalid

Since 0.2.4

### zif_package_id_check ()

    gboolean            zif_package_id_check                (const gchar *package_id);

`package_id` : | A PackageID to check
Returns : | `TRUE` if the PackageID was well formed.

Since 0.1.0

### zif_package_id_compare_nevra ()

    gboolean            zif_package_id_compare_nevra        (const gchar *package_id1,
                                                             const gchar *package_id2);

Compares the NEVRA sections in two package ID strings, ignoring the fourth data section.

`package_id1` : | The package ID, e.g. "hal;1:1.01-3;i386;fedora"
`package_id2` : | The package ID, e.g. "hal;1:1.01-3;i386;updates-testing"
Returns : | `TRUE` if the NEVRA are equal

Since 0.2.5

### zif_package_id_convert_basic ()

    gchar *             zif_package_id_convert_basic        (const gchar *package_id);

Returns a "basic" package-id that does not have the repo appended. For instance, "hal;0.1.2;i386;installed:fedora" would be converted to "hal;0.1.2;i386;installed".

`package_id` : | A package ID
Returns : | The basic package-id.

Since 0.2.5

### zif_package_id_from_nevra ()

    gchar *             zif_package_id_from_nevra           (const gchar *name,
                                                             guint epoch,
                                                             const gchar *version,
                                                             const gchar *release,
                                                             const gchar *arch,
                                                             const gchar *data);

Formats a PackageId structure from a NEVRA.

`name` : | The package name, e.g. "hal"
`epoch` : | The package epoch, e.g. 1 or 0 for none.
`version` : | The package version, e.g. "1.0.0"
`release` : | The package release, e.g. "2"
`arch` : | The package architecture, e.g. "i386"
`data` : | The package data, typically the repo name, or "installed"
Returns : | A PackageId value, or `NULL` if invalid

Since 0.1.0

### zif_package_id_get_name ()

    gchar *             zif_package_id_get_name             (const gchar *package_id);

Gets the package name for a PackageID. This is 9x faster than using `zif_package_id_split()` where you only need the `ZIF_PACKAGE_ID_NAME` component.

`package_id` : | The ';' delimited PackageID to split
Returns : | A string or `NULL` if invalid, use `g_free()` to free

Since 0.1.1

### zif_package_id_get_printable ()

    gchar *             zif_package_id_get_printable        (const gchar *package_id);

Formats the package ID in a way that is suitable to show the user.

`package_id` : | A PackageID to format
Returns : | A string or `NULL` if invalid, use `g_free()` to free

Since 0.1.3

### zif_package_id_split ()

    gchar **            zif_package_id_split                (const gchar *package_id);

Splits a PackageID into the correct number of parts, checking the correct number of delimiters are present.

`package_id` : | The ';' delimited PackageID to split
Returns : | A GStrv or `NULL` if invalid. [element-type utf8][transfer full]

Since 0.1.0

### zif_package_id_to_nevra ()

    gboolean            zif_package_id_to_nevra             (const gchar *package_id,
                                                             gchar **name,
                                                             guint *epoch,
                                                             gchar **version,
                                                             gchar **release,
                                                             gchar **arch);

Parses a PackageId structure to a NEVRA.

`package_id` : | The package ID, e.g. "hal;1:1.01-3;i386;fedora"
`name` : | The returned package name, e.g. "hal"
`epoch` : | The returned package epoch, e.g. 1 or 0 for none.
`version` : | The returned package version, e.g. "1.0.0"
`release` : | The returned package release, e.g. "2"
`arch` : | The returned package architecture, e.g. "i386"
Returns : | `TRUE` if the string was parsed okay

Since 0.1.3

### zif_time_string_to_seconds ()

    guint               zif_time_string_to_seconds          (const gchar *value);

Converts a yum time string into the number of seconds.

`value` : | A yum time string, e.g. "7h"
Returns : | A number of seconds, or zero for failure to parse.

Since 0.1.0

### zif_utils_error_quark ()

    GQuark              zif_utils_error_quark               (void);

Returns : | An error quark.

Since 0.1.0

### zif_utils_gpg_verify ()

    gboolean            zif_utils_gpg_verify                (const gchar *filename,
                                                             const gchar *filename_gpg,
                                                             GError **error);