pk-common

pk-common — Common utility functions for PackageKit

Synopsis




#define             PK_DBUS_SERVICE
#define             PK_DBUS_PATH
#define             PK_DBUS_INTERFACE
#define             PK_DBUS_INTERFACE_TRANSACTION
guint               pk_strlen                           (const gchar *text,
                                                         guint len);
gboolean            pk_strzero                          (const gchar *text);
gboolean            pk_strvalidate                      (const gchar *text);
gboolean            pk_strequal                         (const gchar *id1,
                                                         const gchar *id2);
gboolean            pk_strnumber                        (const gchar *text);
gboolean            pk_strtoint                         (const gchar *text,
                                                         gint *value);
gboolean            pk_strtouint                        (const gchar *text,
                                                         guint *value);
gchar*              pk_strpad                           (const gchar *data,
                                                         guint length);
gchar*              pk_strpad_extra                     (const gchar *data,
                                                         guint length,
                                                         guint *extra);
gchar*              pk_strsafe                          (const gchar *text);
gchar**             pk_strsplit                         (const gchar *id,
                                                         guint parts);
gchar*              pk_strbuild_va                      (const gchar *first_element,
                                                         va_list *args);
gchar*              pk_strreplace                       (const gchar *text,
                                                         const gchar *find,
                                                         const gchar *replace);
gint                pk_ptr_array_find_string            (GPtrArray *array,
                                                         const gchar *string);
gboolean            pk_ptr_array_remove_string          (GPtrArray *array,
                                                         const gchar *string);
gchar**             pk_ptr_array_to_argv                (GPtrArray *array);
gchar**             pk_va_list_to_argv                  (const gchar *string_first,
                                                         va_list *args);
gboolean            pk_strcmp_sections                  (const gchar *id1,
                                                         const gchar *id2,
                                                         guint parts,
                                                         guint compare);
gchar*              pk_iso8601_present                  (void);
guint               pk_iso8601_difference               (const gchar *isodate);
gboolean            pk_delay_yield                      (gfloat delay);
gchar*              pk_get_distro_id                    (void);

Description

This file contains functions that may be useful.

Details

PK_DBUS_SERVICE

#define	PK_DBUS_SERVICE			"org.freedesktop.PackageKit"

The SYSTEM service DBUS name

PK_DBUS_PATH

#define	PK_DBUS_PATH			"/org/freedesktop/PackageKit"

The DBUS path

PK_DBUS_INTERFACE

#define	PK_DBUS_INTERFACE		"org.freedesktop.PackageKit"

The DBUS interface

PK_DBUS_INTERFACE_TRANSACTION

#define	PK_DBUS_INTERFACE_TRANSACTION	"org.freedesktop.PackageKit.Transaction"

The DBUS interface for the transactions

pk_strlen ()

guint               pk_strlen                           (const gchar *text,
                                                         guint len);

This function is a much safer way of doing strlen as it checks for NULL and a stupidly long string.

text :

 The text to check

len :

 The maximum length of the string

Returns :

 the length of the string, or len if the string is too long.

pk_strzero ()

gboolean            pk_strzero                          (const gchar *text);

This function is a much safer way of doing "if (strlen (text) == 0))" as it does not rely on text being NULL terminated. It's also much quicker as it only checks the first byte rather than scanning the whole string just to verify it's not zero length.

text :

 The text to check

Returns :

 TRUE if the string was converted correctly

pk_strvalidate ()

gboolean            pk_strvalidate                      (const gchar *text);

Tests a string to see if it may be dangerous or invalid.

text :

 The text to check for validity

Returns :

 TRUE if the string is valid

pk_strequal ()

gboolean            pk_strequal                         (const gchar *id1,
                                                         const gchar *id2);

This function is a much safer way of doing strcmp as it checks for NULL first, and returns boolean TRUE, not zero for success.

id1 :

 the first item of text to test

id2 :

 the second item of text to test

Returns :

 TRUE if the string are both non-NULL and the same.

pk_strnumber ()

gboolean            pk_strnumber                        (const gchar *text);

Tests a string to see if it is a number. Both positive and negative numbers are allowed.

text :

 The text the validate

Returns :

 TRUE if the string represents a numeric value

pk_strtoint ()

gboolean            pk_strtoint                         (const gchar *text,
                                                         gint *value);

Converts a string into a signed integer value in a safe way.

text :

 The text the convert

value :

 The return numeric return value, or 0 if invalid.

Returns :

 TRUE if the string was converted correctly

pk_strtouint ()

gboolean            pk_strtouint                        (const gchar *text,
                                                         guint *value);

Converts a string into a unsigned integer value in a safe way.

text :

 The text the convert

value :

 The return numeric return value, or 0 if invalid.

Returns :

 TRUE if the string was converted correctly

pk_strpad ()

gchar*              pk_strpad                           (const gchar *data,
                                                         guint length);

Returns the text padded to a length with spaces. If the string is longer than length then a longer string is returned.

data :

 the input string

length :

 the desired length of the output string, with padding

Returns :

 The padded string

pk_strpad_extra ()

gchar*              pk_strpad_extra                     (const gchar *data,
                                                         guint length,
                                                         guint *extra);

This function pads a string, but allows a follow-on value. This is useful if the function is being used to print columns of text, and one oversize one has to be absorbed into the next where possible.

data :

 the input string

length :

 the desired length of the output string, with padding

extra :

 if we are running with a deficit, we might have a positive offset

Returns :

 The padded string

pk_strsafe ()

gchar*              pk_strsafe                          (const gchar *text);

Replaces chars in the text that may be dangerous, or that may print incorrectly. These chars include new lines, tabs and quotes, and are replaced by spaces.

text :

 The input text to make safe

Returns :

 the new string with no insane chars

pk_strsplit ()

gchar**             pk_strsplit                         (const gchar *id,
                                                         guint parts);

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

id :

 the ; delimited string to split

parts :

 how many parts the delimted string should be split into

Returns :

 a char array is split correctly, NULL if invalid Note: You need to use g_strfreev on the returned value

pk_strbuild_va ()

gchar*              pk_strbuild_va                      (const gchar *first_element,
                                                         va_list *args);

This function converts a va_list into a string in a safe and efficient way, e.g. pk_strbuild_va("foo","bar","baz") == "foo bar baz"

first_element :

 The first string item, or NULL

args :

 the va_list

Returns :

 the single string

pk_strreplace ()

gchar*              pk_strreplace                       (const gchar *text,
                                                         const gchar *find,
                                                         const gchar *replace);

Replaces chars in the text with a replacement. The find and replace variables to not have to be of the same length

text :

 The input text to make safe

find :

 What to search for

replace :

 What to replace with

Returns :

 the new string (copied)

pk_ptr_array_find_string ()

gint                pk_ptr_array_find_string            (GPtrArray *array,
                                                         const gchar *string);

array :

 The GPtrArray to operate on

string :

 The string to search for

Returns :

 The array index, or -1 if not found

pk_ptr_array_remove_string ()

gboolean            pk_ptr_array_remove_string          (GPtrArray *array,
                                                         const gchar *string);

array :

 The GPtrArray to operate on

string :

 The string to search for

Returns :

 TRUE if we removed any strings

pk_ptr_array_to_argv ()

gchar**             pk_ptr_array_to_argv                (GPtrArray *array);

Form a composite string array of strings. The data in the GPtrArray is copied.

array :

 the GPtrArray of strings

Returns :

 the string array, or NULL if invalid

pk_va_list_to_argv ()

gchar**             pk_va_list_to_argv                  (const gchar *string_first,
                                                         va_list *args);

Form a composite string array of string, with a special twist; if the entry contains a '|', then it is split as seporate parts of the array.

string_first :

 the first string

args :

 any subsequant string's

Returns :

 the string array, or NULL if invalid

pk_strcmp_sections ()

gboolean            pk_strcmp_sections                  (const gchar *id1,
                                                         const gchar *id2,
                                                         guint parts,
                                                         guint compare);

We only want to compare some first sections, not all the data when comparing package_id's and transaction_id's.

id1 :

 the first item of text to test

id2 :

 the second item of text to test

parts :

 the number of parts each id should have

compare :

 the leading number of parts to compare

Returns :

 TRUE if the strings can be considered the same.

pk_iso8601_present ()

gchar*              pk_iso8601_present                  (void);

Returns :

 The current iso8601 date and time

pk_iso8601_difference ()

guint               pk_iso8601_difference               (const gchar *isodate);

isodate :

 The ISO8601 date to compare

Returns :

 The difference in seconds between the iso8601 date and current

pk_delay_yield ()

gboolean            pk_delay_yield                      (gfloat delay);

delay :

 the desired delay in seconds

Returns :

 success

pk_get_distro_id ()

gchar*              pk_get_distro_id                    (void);

Returns :

 The current distro-id, e.g. fedora-8-i386, or NULL for an error or not known