## GcrImporter

GcrImporter — Import certificates and keys

## Synopsis

                        GcrImporter;
    struct              GcrImporterIface;
    GTlsInteraction *   gcr_importer_get_interaction        (GcrImporter *importer);
    void                gcr_importer_set_interaction        (GcrImporter *importer,
                                                             GTlsInteraction *interaction);
    gboolean            gcr_importer_import                 (GcrImporter *importer,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gcr_importer_import_async           (GcrImporter *importer,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gcr_importer_import_finish          (GcrImporter *importer,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                gcr_importer_register               (GType importer_type,
                                                             GckAttributes *attrs);
    void                gcr_importer_register_well_known    (void);
    GList *             gcr_importer_create_for_parsed      (GcrParsed *parsed);
    gboolean            gcr_importer_queue_for_parsed       (GcrImporter *importer,
                                                             GcrParsed *parsed);
    GList *             gcr_importer_queue_and_filter_for_parsed
                                                            (GList *importers,
                                                             GcrParsed *parsed);
    void                gcr_import_interaction_supplement_prep
                                                            (GcrImportInteraction *interaction,
                                                             GckBuilder *builder);
    GTlsInteractionResult gcr_import_interaction_supplement (GcrImportInteraction *interaction,
                                                             GckBuilder *builder,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gcr_import_interaction_supplement_async
                                                            (GcrImportInteraction *interaction,
                                                             GckBuilder *builder,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GTlsInteractionResult gcr_import_interaction_supplement_finish
                                                            (GcrImportInteraction *interaction,
                                                             GAsyncResult *result,
                                                             GError **error);

## Object Hierarchy

      GInterface
       +----GcrImporter

## Prerequisites

GcrImporter requires GObject.

## Properties

      "icon"                     GIcon*                : Read
      "interaction"              GTlsInteraction*      : Read / Write
      "label"                    gchar*                : Read
      "uri"                      gchar*                : Read

## Description

An interface which allows importing of certificates and keys. Each GcrImporter is registered with a set of PKCS#11 attributes to match stuff that it can import.

An importer gets passed a GcrParser and accesses the currently parsed item. To create a set of importers that can import the currently parsed item in a GcrParser, use `gcr_importer_create_for_parsed()`. The list of importers returned has the parsed item queued for import.

To queue additional items with a importer use `gcr_importer_queue_for_parsed()`. In addition you can try and queue an additional item with a set of importers using the `gcr_importer_queue_and_filter_for_parsed()`.

To start the import use `gcr_importer_import()` or the async variants.

## Details

### GcrImporter

    typedef struct _GcrImporter GcrImporter;

Imports certificates and keys

### struct GcrImporterIface

    struct GcrImporterIface {
    	GTypeInterface parent;

    	GList *     (*create_for_parsed)      (GcrParsed *parsed);

    	gboolean    (*queue_for_parsed)       (GcrImporter *importer,
    	                                       GcrParsed *parsed);

    	gboolean    (*import_sync)            (GcrImporter *importer,
    	                                       GCancellable *cancellable,
    	                                       GError **error);

    	void        (*import_async)           (GcrImporter *importer,
    	                                       GCancellable *cancellable,
    	                                       GAsyncReadyCallback callback,
    	                                       gpointer user_data);

    	gboolean    (*import_finish)          (GcrImporter *importer,
    	                                       GAsyncResult *result,
    	                                       GError **error);
    };

Interface implemented for a GcrImporter.

GTypeInterface `parent`; | parent interface
`create_for_parsed` () | implementation of `gcr_importer_create_for_parsed()`, required
`queue_for_parsed` () | implementation of `gcr_importer_queue_for_parsed()`, required
`import_sync` () | optional implemantionon of `gcr_importer_import()`
`import_async` () | implementation of `gcr_importer_import_async()`, required
`import_finish` () | implementation of `gcr_importer_import_finish()`

### gcr_importer_get_interaction ()

    GTlsInteraction *   gcr_importer_get_interaction        (GcrImporter *importer);

Get the interaction used to prompt the user when needed by this importer.

`importer` : | the importer
Returns : | the interaction or `NULL`. [transfer none][allow-none]

### gcr_importer_set_interaction ()

    void                gcr_importer_set_interaction        (GcrImporter *importer,
                                                             GTlsInteraction *interaction);

Set the interaction used to prompt the user when needed by this importer.

`importer` : | the importer
`interaction` : | the interaction used by the importer

### gcr_importer_import ()

    gboolean            gcr_importer_import                 (GcrImporter *importer,
                                                             GCancellable *cancellable,
                                                             GError **error);

Import the queued items in the importer. This call will block until the operation completes.

`importer` : | the importer
`cancellable` : | a GCancellable, or `NULL`
`error` : | the location to place an error on failure, or `NULL`
Returns : | whether the items were imported successfully or not

### gcr_importer_import_async ()

    void                gcr_importer_import_async           (GcrImporter *importer,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Import the queued items in the importer. This function returns immediately and completes asynchronously.

`importer` : | the importer
`cancellable` : | a GCancellable, or `NULL`
`callback` : | called when the operation completes
`user_data` : | data to be passed to the callback

### gcr_importer_import_finish ()

    gboolean            gcr_importer_import_finish          (GcrImporter *importer,
                                                             GAsyncResult *result,
                                                             GError **error);

Complete an asynchronous operation to import queued items.

`importer` : | the importer
`result` : | an asynchronous result
`error` : | the location to place an error on failure, or `NULL`
Returns : | whether the import succeeded or failed

### gcr_importer_register ()

    void                gcr_importer_register               (GType importer_type,
                                                             GckAttributes *attrs);

Register an importer to handle parsed items that match the given attributes.

`importer_type` : | the GType of the importer being registered
`attrs` : | the attributes that this importer is compatible with

### gcr_importer_register_well_known ()

    void                gcr_importer_register_well_known    (void);

Register built-in PKCS#11 and GnuPG importers.

### gcr_importer_create_for_parsed ()

    GList *             gcr_importer_create_for_parsed      (GcrParsed *parsed);

Create a set of importers which can import this parsed item. The parsed item is represented by the state of the GcrParser at the time of calling this method.

`parsed` : | a parser with a parsed item to import
Returns : | a list of importers which can import the parsed item, which should be freed with `g_object_unref()`, or `NULL` if no types of importers can be created. [element-type Gcr.Importer][transfer full]

### gcr_importer_queue_for_parsed ()

    gboolean            gcr_importer_queue_for_parsed       (GcrImporter *importer,
                                                             GcrParsed *parsed);

Queues an additional item to be imported. The parsed item is represented by the state of the GcrParser at the time of calling this method.

If the parsed item is incompatible with the importer, then this will fail and the item will not be queued.

`importer` : | an importer to add additional items to
`parsed` : | a parsed item to import
Returns : | whether the item was queued or not

### gcr_importer_queue_and_filter_for_parsed ()

    GList *             gcr_importer_queue_and_filter_for_parsed
                                                            (GList *importers,
                                                             GcrParsed *parsed);

Queues an additional item to be imported in all compattible importers in the set. The parsed item is represented by the state of the GcrParser at the time of calling this method.

If the parsed item is incompatible with an importer, then that the item will not be queued on that importer.

`importers` : | a set of importers. [element-type Gcr.Importer]
`parsed` : | a parsed item
Returns : | a new set of importers that queued the item, which should be freed with `gck_list_unref_free()`. [transfer full][element-type Gcr.Importer]

### gcr_import_interaction_supplement_prep ()

    void                gcr_import_interaction_supplement_prep
                                                            (GcrImportInteraction *interaction,
                                                             GckBuilder *builder);

Prepare for supplementing the given attributes before import. This means prompting the user for things like labels and the like. The attributes will contain attributes for values that the importer needs, either empty or prefilled with suggested values.

This method does not prompt the user, but rather just prepares the interaction that these are the attributes that are needed.

`interaction` : | the interaction
`builder` : | attributes to supplement

### gcr_import_interaction_supplement ()

    GTlsInteractionResult gcr_import_interaction_supplement (GcrImportInteraction *interaction,
                                                             GckBuilder *builder,
                                                             GCancellable *cancellable,
                                                             GError **error);

Supplement attributes before import. This means prompting the user for things like labels and the like. The needed attributes will have been passed to `gcr_import_interaction_supplement_prep()`.

This method prompts the user and fills in the attributes. If the user or cancellable cancels the operation the error should be set with `G_IO_ERROR_CANCELLED`.

`interaction` : | the interaction
`builder` : | supplemented attributes
`cancellable` : | optional cancellable object
`error` : | location to store error on failure
Returns : | `G_TLS_INTERACTION_HANDLED` if successful or `G_TLS_INTERACTION_FAILED`

### gcr_import_interaction_supplement_async ()

    void                gcr_import_interaction_supplement_async
                                                            (GcrImportInteraction *interaction,
                                                             GckBuilder *builder,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously supplement attributes before import. This means prompting the user for things like labels and the like. The needed attributes will have been passed to `gcr_import_interaction_supplement_prep()`.

This method prompts the user and fills in the attributes.

`interaction` : | the interaction
`builder` : | supplemented attributes
`cancellable` : | optional cancellable object
`callback` : | called when the operation completes
`user_data` : | data to be passed to the callback

### gcr_import_interaction_supplement_finish ()

    GTlsInteractionResult gcr_import_interaction_supplement_finish
                                                            (GcrImportInteraction *interaction,
                                                             GAsyncResult *result,
                                                             GError **error);

Complete operation to asynchronously supplement attributes before import.

If the user or cancellable cancels the operation the error should be set with `G_IO_ERROR_CANCELLED`.

`interaction` : | the interaction
`result` : | the asynchronous result
`error` : | location to place an error on failure
Returns : | `G_TLS_INTERACTION_HANDLED` if successful or `G_TLS_INTERACTION_FAILED`

## Property Details

### The `"icon"` property

      "icon"                     GIcon*                : Read

The icon for the importer.

### The `"interaction"` property

      "interaction"              GTlsInteraction*      : Read / Write

The interaction for the importer.

### The `"label"` property

      "label"                    gchar*                : Read

The label for the importer.

Default value: ""

### The `"uri"` property

      "uri"                      gchar*                : Read

The URI of the location imported to.

Default value: NULL