## seahorse-util

seahorse-util

## Synopsis

    const AvahiPoll*    seahorse_util_dns_sd_get_poll       ();
    enum                SeahorseSuffix;
    #define             SEAHORSE_EXT_ASC
    #define             SEAHORSE_EXT_SIG
    #define             SEAHORSE_EXT_PGP
    #define             SEAHORSE_EXT_GPG
    gchar*              seahorse_util_get_date_string       (const time_t time);
    gchar*              seahorse_util_get_display_date_string
                                                            (const time_t time);
    #define             SEAHORSE_ERROR
    GQuark              seahorse_util_error_domain          ();
    void                seahorse_util_show_error            (GtkWidget *parent,
                                                             const gchar *heading,
                                                             const gchar *message);
    void                seahorse_util_handle_error          (GError *err,
                                                             const char *desc,
                                                             ...);
    gboolean            seahorse_util_prompt_delete         (const gchar *text,
                                                             GtkWidget *parent);
    guchar*             seahorse_util_read_to_memory        (GInputStream *input,
                                                             guint *len);
    guint               seahorse_util_read_data_block       (GString *buf,
                                                             GInputStream *input,
                                                             const gchar *start,
                                                             const gchar *end);
    GMemoryInputStream * seahorse_util_memory_input_string  (const gchar *string,
                                                             gsize length);
    gsize               seahorse_util_memory_output_length  (GMemoryOutputStream *output);
    gboolean            seahorse_util_print_fd              (int fd,
                                                             const char *data);
    gboolean            seahorse_util_printf_fd             (int fd,
                                                             const char *data,
                                                             ...);
    gchar*              seahorse_util_filename_for_objects  (GList *objects);
    gboolean            seahorse_util_uri_exists            (const gchar *uri);
    gchar*              seahorse_util_uri_unique            (const gchar *uri);
    gchar*              seahorse_util_uri_replace_ext       (const gchar *uri,
                                                             const gchar *ext);
    const gchar*        seahorse_util_uri_get_last          (const gchar *uri);
    const gchar*        seahorse_util_uri_split_last        (gchar *uri);
    gboolean            seahorse_util_uris_package          (const gchar *package,
                                                             const gchar **uris);
    GQuark              seahorse_util_detect_mime_type      (const gchar *mime);
    GQuark              seahorse_util_detect_data_type      (const gchar *data,
                                                             guint length);
    GQuark              seahorse_util_detect_file_type      (const gchar *uri);
    gboolean            seahorse_util_write_file_private    (const gchar *filename,
                                                             const gchar *contents,
                                                             GError **err);
    GtkDialog*          seahorse_util_chooser_open_new      (const gchar *title,
                                                             GtkWindow *parent);
    GtkDialog*          seahorse_util_chooser_save_new      (const gchar *title,
                                                             GtkWindow *parent);
    void                seahorse_util_chooser_show_key_files
                                                            (GtkDialog *dialog);
    void                seahorse_util_chooser_show_archive_files
                                                            (GtkDialog *dialog);
    void                seahorse_util_chooser_set_filename_full
                                                            (GtkDialog *dialog,
                                                             GList *objects);
    void                seahorse_util_chooser_set_filename  (GtkDialog *dialog,
                                                             struct _SeahorseObject *object);
    gchar*              seahorse_util_chooser_open_prompt   (GtkDialog *dialog);
    gchar*              seahorse_util_chooser_save_prompt   (GtkDialog *dialog);
    gboolean            seahorse_util_check_suffix          (const gchar *path,
                                                             SeahorseSuffix suffix);
    gchar*              seahorse_util_add_suffix            (const gchar *path,
                                                             SeahorseSuffix suffix,
                                                             const gchar *prompt);
    gchar*              seahorse_util_remove_suffix         (const gchar *path,
                                                             const gchar *prompt);
    gchar**             seahorse_util_strvec_dup            (const gchar **vec);
    guint               seahorse_util_strvec_length         (const gchar **vec);
    GList*              seahorse_util_objects_sort          (GList *objects);
    GList*              seahorse_util_objects_splice        (GList *objects);
    gboolean            seahorse_util_string_equals         (const gchar *s1,
                                                             const gchar *s2);
    gchar*              seahorse_util_string_up_first       (const gchar *orig);
    void                seahorse_util_string_lower          (gchar *s);
    GSList*             seahorse_util_string_slist_free     (GSList *slist);
    GSList*             seahorse_util_string_slist_copy     (GSList *slist);
    gboolean            seahorse_util_string_slist_equal    (GSList *sl1,
                                                             GSList *sl2);
    gboolean            seahorse_util_string_is_whitespace  (const gchar *text);
    void                seahorse_util_string_trim_whitespace
                                                            (gchar *text);
    gchar*              seahorse_util_hex_encode            (gconstpointer value,
                                                             gsize length);
    void                seahorse_util_determine_popup_menu_position
                                                            (GtkMenu *menu,
                                                             int *x,
                                                             int *y,
                                                             gboolean *push_in,
                                                             gpointer gdata);
    #define             seahorse_util_wait_until            (expr)
    #define             DBG_PRINT                           (x)

## Description

## Details

### seahorse_util_dns_sd_get_poll ()

    const AvahiPoll*    seahorse_util_dns_sd_get_poll       ();

Returns : |

### enum SeahorseSuffix

    typedef enum {
        SEAHORSE_CRYPT_SUFFIX,
        SEAHORSE_SIG_SUFFIX,
    } SeahorseSuffix;

### SEAHORSE_EXT_ASC

    #define SEAHORSE_EXT_ASC ".asc"

### SEAHORSE_EXT_SIG

    #define SEAHORSE_EXT_SIG ".sig"

### SEAHORSE_EXT_PGP

    #define SEAHORSE_EXT_PGP ".pgp"

### SEAHORSE_EXT_GPG

    #define SEAHORSE_EXT_GPG ".gpg"

### seahorse_util_get_date_string ()

    gchar*              seahorse_util_get_date_string       (const time_t time);

Creates a string representation of `time` for use with gpg.

`time` : | Time value to parse
Returns : | A string representing `time`. The returned string should be freed with g_free when no longer needed.

### seahorse_util_get_display_date_string ()

    gchar*              seahorse_util_get_display_date_string
                                                            (const time_t time);

Creates a string representation of `time` for display in the UI.

`time` : | Time value to parse
Returns : | A string representing `time`. The returned string should be freed with g_free when no longer needed.

### SEAHORSE_ERROR

    #define SEAHORSE_ERROR  (seahorse_util_error_domain ())

### seahorse_util_error_domain ()

    GQuark              seahorse_util_error_domain          ();

Returns : | The GError domain for generic seahorse errors

### seahorse_util_show_error ()

    void                seahorse_util_show_error            (GtkWidget *parent,
                                                             const gchar *heading,
                                                             const gchar *message);

This displays an error dialog. The parent widget can be any widget. The dialog will be a child of the window the widget is in.

`parent` : | The parent widget. Can be NULL
`heading` : | The heading of the dialog
`message` : | The message to display

### seahorse_util_handle_error ()

    void                seahorse_util_handle_error          (GError *err,
                                                             const char *desc,
                                                             ...);

Displays an error box. The message is the error message.

`err` : | The GError to print.
`desc` : | The heading of the box
`...` : | Parameters to insert into the format string desc.

### seahorse_util_prompt_delete ()

    gboolean            seahorse_util_prompt_delete         (const gchar *text,
                                                             GtkWidget *parent);

Displays a modal dialog with "cancel" and "delete"

`text` : | The text to display in the delete-dialog
`parent` : | The widget to display the dialog for. Can be NULL
Returns : | TRUE if the user pressed "delete", FALSE else

### seahorse_util_read_to_memory ()

    guchar*             seahorse_util_read_to_memory        (GInputStream *input,
                                                             guint *len);

Reads data from the input stream and returns them as guchar

`input` : | Data to read. The GInputStream is read till the end.
`len` : | Length of the data read (out)
Returns : | The string read from data. The returned string should be freed with g_free when no longer needed.

### seahorse_util_read_data_block ()

    guint               seahorse_util_read_data_block       (GString *buf,
                                                             GInputStream *input,
                                                             const gchar *start,
                                                             const gchar *end);

Breaks out one block of data (usually a key)

`buf` : | A string buffer to write the data to.
`input` : | The input stream to read from.
`start` : | The start signature to look for.
`end` : | The end signature to look for.
Returns : | The number of bytes copied.

### seahorse_util_memory_input_string ()

    GMemoryInputStream * seahorse_util_memory_input_string  (const gchar *string,
                                                             gsize length);

`string` : | The string to create the stream from
`length` : | The length of this string
Returns : | The new input stream of type GMemoryInputStream

### seahorse_util_memory_output_length ()

    gsize               seahorse_util_memory_output_length  (GMemoryOutputStream *output);

A replacement for g_memory_output_stream_get_data_size (since 2.18)

`output` : | a stream
Returns : | The length of the stream

### seahorse_util_print_fd ()

    gboolean            seahorse_util_print_fd              (int fd,
                                                             const char *data);

`fd` : | The file descriptor to write to
`data` : |
Returns : | FALSE on error, TRUE on success

### seahorse_util_printf_fd ()

    gboolean            seahorse_util_printf_fd             (int fd,
                                                             const char *data,
                                                             ...);

`fd` : | The file descriptor to write to
`data` : |
`...` : | The parameters to insert
Returns : | TRUE on success, FALSE on error

### seahorse_util_filename_for_objects ()

    gchar*              seahorse_util_filename_for_objects  (GList *objects);

If the single object has a nickname, this will be returned (with .asc attached) If there are multiple objects, "Multiple Keys.asc" will be returned. Single objects default to "Key Data.asc". Results are internationalized

`objects` : | A list of objects
Returns : | NULL on error, the filename else. The returned string should be freed with g_free when no longer needed.

### seahorse_util_uri_exists ()

    gboolean            seahorse_util_uri_exists            (const gchar *uri);

Verify whether a given uri exists or not.

`uri` : | The uri to check
Returns : | FALSE if it does not exist, TRUE else

### seahorse_util_uri_unique ()

    gchar*              seahorse_util_uri_unique            (const gchar *uri);

Creates a URI based on `uri` that does not exist. A simple numbering scheme is used to create new URIs. Not meant for temp file creation.

`uri` : | The uri to guarantee is unique
Returns : | Newly allocated unique URI.

### seahorse_util_uri_replace_ext ()

    gchar*              seahorse_util_uri_replace_ext       (const gchar *uri,
                                                             const gchar *ext);

Replaces the extension on `uri`

`uri` : | The uri with old extension
`ext` : | The new extension
Returns : | Newly allocated URI string with new extension. The returned string should be freed with g_free when no longer needed.

### seahorse_util_uri_get_last ()

    const gchar*        seahorse_util_uri_get_last          (const gchar *uri);

Finds the last portion of `uri`. Note that this does not modify `uri`. If the uri is invalid or has no directories then the entire thing is returned.

`uri` : | The uri to parse
Returns : | Last portion of `uri`

### seahorse_util_uri_split_last ()

    const gchar*        seahorse_util_uri_split_last        (gchar *uri);

Splits the uri in two at it's last component. The result is still part of the same string, so don't free it. This modifies the `uri` argument.

`uri` : | The uri to split
Returns : | The last component

### seahorse_util_uris_package ()

    gboolean            seahorse_util_uris_package          (const gchar *package,
                                                             const gchar **uris);

Package uris into an archive. The uris must be local.

`package` : | Package uri
`uris` : | null-terminated array of uris to package
Returns : | TRUE on success or FALSE on failure

### seahorse_util_detect_mime_type ()

    GQuark              seahorse_util_detect_mime_type      (const gchar *mime);

Return the mime type depending on the mime string

`mime` : | The mime string
Returns : | SEAHORSE_PGP, SEAHORSE_SSH or 0

### seahorse_util_detect_data_type ()

    GQuark              seahorse_util_detect_data_type      (const gchar *data,
                                                             guint length);

`data` : | The buffer to test for content type
`length` : | The length of this buffer
Returns : | SEAHORSE_PGP, SEAHORSE_SSH or 0

### seahorse_util_detect_file_type ()

    GQuark              seahorse_util_detect_file_type      (const gchar *uri);

`uri` : | The file uri to test for content type
Returns : | SEAHORSE_PGP, SEAHORSE_SSH or 0

### seahorse_util_write_file_private ()

    gboolean            seahorse_util_write_file_private    (const gchar *filename,
                                                             const gchar *contents,
                                                             GError **err);

`filename` : | file to write to
`contents` : | nul-terminated string to write to the file
`err` : | error of the write operation
Returns : | TRUE on success, FALSE if an error occured

### seahorse_util_chooser_open_new ()

    GtkDialog*          seahorse_util_chooser_open_new      (const gchar *title,
                                                             GtkWindow *parent);

Creates a file chooser dialog to open files.

`title` : | The title of the dialog
`parent` : | The parent of the dialog
Returns : | The new open dialog

### seahorse_util_chooser_save_new ()

    GtkDialog*          seahorse_util_chooser_save_new      (const gchar *title,
                                                             GtkWindow *parent);

Creates a file chooser dialog to save files.

`title` : | The title of the dialog
`parent` : | The parent of the dialog
Returns : | The new save dialog

### seahorse_util_chooser_show_key_files ()

    void                seahorse_util_chooser_show_key_files
                                                            (GtkDialog *dialog);

Adds a key file filter and a "All files" filter. The key filter is used.

`dialog` : | the dialog to add the filter for

### seahorse_util_chooser_show_archive_files ()

    void                seahorse_util_chooser_show_archive_files
                                                            (GtkDialog *dialog);

Adds a archive file filter and a "All files" filter. The archive filter is used.

`dialog` : | the dialog to add the filter for

### seahorse_util_chooser_set_filename_full ()

    void                seahorse_util_chooser_set_filename_full
                                                            (GtkDialog *dialog,
                                                             GList *objects);

`dialog` : | The dialog to pre set the name
`objects` : | generate the file name from this object

### seahorse_util_chooser_set_filename ()

    void                seahorse_util_chooser_set_filename  (GtkDialog *dialog,
                                                             struct _SeahorseObject *object);

`dialog` : | set the dialog for this
`object` : | The object to use for the filename. SeahorseObject

### seahorse_util_chooser_open_prompt ()

    gchar*              seahorse_util_chooser_open_prompt   (GtkDialog *dialog);

Display an open dialog

`dialog` : | open dialog to display
Returns : | The uri of the file to open or NULL

### seahorse_util_chooser_save_prompt ()

    gchar*              seahorse_util_chooser_save_prompt   (GtkDialog *dialog);

If the selected file already exists, a confirmation dialog will be displayed

`dialog` : | save dialog to show
Returns : | the uri of the chosen file or NULL

### seahorse_util_check_suffix ()

    gboolean            seahorse_util_check_suffix          (const gchar *path,
                                                             SeahorseSuffix suffix);

Checks that `path` has a suffix specified by `suffix`.

`path` : | Path of file to check
`suffix` : | Suffix type to check for.
Returns : | TRUE if the file has a correct suffix, FALSE otherwise

### seahorse_util_add_suffix ()

    gchar*              seahorse_util_add_suffix            (const gchar *path,
                                                             SeahorseSuffix suffix,
                                                             const gchar *prompt);

Constructs a new path for a file based on `path` plus a suffix determined by `suffix`. If ASCII Armor is enabled, the suffix will be '.asc'. Otherwise the suffix will be '.pgp' if `suffix` is `SEAHORSE_CRYPT_SUFFIX` or '.sig' if `suffix` is `SEAHORSE_SIG_SUFFIX`.

`path` : | Path of an existing file
`suffix` : | Suffix type
`prompt` : | Overwrite prompt text
Returns : | A new path with the suffix appended to `path`. NULL if prompt cancelled

### seahorse_util_remove_suffix ()

    gchar*              seahorse_util_remove_suffix         (const gchar *path,
                                                             const gchar *prompt);

Removes a suffix from `path`. Does not check if `path` actually has a suffix.

`path` : | Path with a suffix
`prompt` : | Overwrite prompt text
Returns : | `path` without a suffix. NULL if prompt cancelled

### seahorse_util_strvec_dup ()

    gchar**             seahorse_util_strvec_dup            (const gchar **vec);

Copy a string table

`vec` : | the string table to copy
Returns : | the new char **

### seahorse_util_strvec_length ()

    guint               seahorse_util_strvec_length         (const gchar **vec);

Calculates the length of the string table

`vec` : | The string table
Returns : | The length of the string table

### seahorse_util_objects_sort ()

    GList*              seahorse_util_objects_sort          (GList *objects);

The objects are sorted by their source

`objects` : | SeahorseObject GList to sort
Returns : | The sorted list

### seahorse_util_objects_splice ()

    GList*              seahorse_util_objects_splice        (GList *objects);

Splices the list at the source disconuity

`objects` : | A GList of SeahorseObject. Must be sorted
Returns : | The second part of the list.

### seahorse_util_string_equals ()

    gboolean            seahorse_util_string_equals         (const gchar *s1,
                                                             const gchar *s2);

Compares two string. If they are equal, it returns TRUE

`s1` : | String, can be NULL
`s2` : | String, can be NULL
Returns : | TRUE if strings are equal, FALSE else

### seahorse_util_string_up_first ()

    gchar*              seahorse_util_string_up_first       (const gchar *orig);

Upper case the first char in the UTF8 string

`orig` : | The utf8 string to work with
Returns : | a new string, with the first char upper cased. The returned string should be freed with g_free when no longer needed.

### seahorse_util_string_lower ()

    void                seahorse_util_string_lower          (gchar *s);

The whole ASCII string will be lower cased.

`s` : | ASCII string to change

### seahorse_util_string_slist_free ()

    GSList*             seahorse_util_string_slist_free     (GSList *slist);

Free a GSList along with string values

`slist` : | the GSList to free
Returns : | NULL

### seahorse_util_string_slist_copy ()

    GSList*             seahorse_util_string_slist_copy     (GSList *slist);

Copy a GSList along with string values

`slist` : | The list to copy
Returns : | the new list

### seahorse_util_string_slist_equal ()

    gboolean            seahorse_util_string_slist_equal    (GSList *sl1,
                                                             GSList *sl2);

Compare two string GSLists.

`sl1` : | the first string list
`sl2` : | the second string list
Returns : | TRUE if all the string are equal

### seahorse_util_string_is_whitespace ()

    gboolean            seahorse_util_string_is_whitespace  (const gchar *text);

`text` : | The UTF8 string to test
Returns : | TRUE if `text` consists of whitespaces

### seahorse_util_string_trim_whitespace ()

    void                seahorse_util_string_trim_whitespace
                                                            (gchar *text);

Whitespaces will be removed from the start and the end of the text.

`text` : | The text to trim (UTF8)

### seahorse_util_hex_encode ()

    gchar*              seahorse_util_hex_encode            (gconstpointer value,
                                                             gsize length);

Creates a string contining the `value` in hex for printing.

`value` : | a buffer containing data
`length` : | The length of this buffer
Returns : | The hex encoded `value`. The returned string should be freed with g_free when no longer needed.

### seahorse_util_determine_popup_menu_position ()

    void                seahorse_util_determine_popup_menu_position
                                                            (GtkMenu *menu,
                                                             int *x,
                                                             int *y,
                                                             gboolean *push_in,
                                                             gpointer gdata);

Callback to determine where a popup menu should be placed

`menu` : | The menu to place
`x` : | (out) x pos of the menu
`y` : | (out) y pos of the menu
`push_in` : | (out) will be set to TRUE
`gdata` : | GTK_WIDGET for which the menu is

### seahorse_util_wait_until()

    #define             seahorse_util_wait_until(expr)

`expr` : |

### DBG_PRINT()

    #define             DBG_PRINT(x)

`x` : |