SeahorseContext

## SeahorseContext SeahorseContext — This is where all the action in a Seahorse process comes together. |

## Synopsis

    #include <libseahorse/seahorse-context.h>

                        SeahorseContextPrivate;
                        SeahorseContext;
    void                (*SeahorseObjectFunc)               (struct _SeahorseObject *obj,
                                                             gpointer user_data);
    #define             SCTX_APP
    SeahorseContext*    seahorse_context_for_app            (void);
    SeahorseContext*    seahorse_context_new                (guint flags);
    void                seahorse_context_destroy            (SeahorseContext *sctx);
    #define             seahorse_context_is_daemon          (ctx)
    void                seahorse_context_add_source         (SeahorseContext *sctx,
                                                             SeahorseSource *sksrc);
    void                seahorse_context_take_source        (SeahorseContext *sctx,
                                                             SeahorseSource *sksrc);
    void                seahorse_context_remove_source      (SeahorseContext *sctx,
                                                             SeahorseSource *sksrc);
    SeahorseSource*     seahorse_context_find_source        (SeahorseContext *sctx,
                                                             GQuark ktype,
                                                             SeahorseLocation location);
    GSList*             seahorse_context_find_sources       (SeahorseContext *sctx,
                                                             GQuark ktype,
                                                             SeahorseLocation location);
    SeahorseSource*     seahorse_context_remote_source      (SeahorseContext *sctx,
                                                             const gchar *uri);
    void                seahorse_context_add_object         (SeahorseContext *sctx,
                                                             struct _SeahorseObject *sobj);
    void                seahorse_context_take_object        (SeahorseContext *sctx,
                                                             struct _SeahorseObject *sobj);
    guint               seahorse_context_get_count          (SeahorseContext *sctx);
    struct _SeahorseObject* seahorse_context_get_object     (SeahorseContext *sctx,
                                                             SeahorseSource *sksrc,
                                                             GQuark id);
    GList*              seahorse_context_get_objects        (SeahorseContext *sctx,
                                                             SeahorseSource *sksrc);
    struct _SeahorseObject* seahorse_context_find_object    (SeahorseContext *sctx,
                                                             GQuark id,
                                                             SeahorseLocation location);
    GList*              seahorse_context_find_objects       (SeahorseContext *sctx,
                                                             GQuark ktype,
                                                             SeahorseUsage usage,
                                                             SeahorseLocation location);
    GList*              seahorse_context_find_objects_full  (SeahorseContext *self,
                                                             struct _SeahorseObjectPredicate *skpred);
    void                seahorse_context_for_objects_full   (SeahorseContext *self,
                                                             struct _SeahorseObjectPredicate *skpred,
                                                             SeahorseObjectFunc func,
                                                             gpointer user_data);
    void                seahorse_context_verify_objects     (SeahorseContext *self);
    void                seahorse_context_remove_object      (SeahorseContext *sctx,
                                                             struct _SeahorseObject *sobj);
    SeahorseServiceDiscovery * seahorse_context_get_discovery
                                                            (SeahorseContext *sctx);
    struct _SeahorseObject * seahorse_context_get_default_key
                                                            (SeahorseContext *sctx);
    void                seahorse_context_refresh_auto       (SeahorseContext *sctx);
    SeahorseOperation*  seahorse_context_search_remote      (SeahorseContext *sctx,
                                                             const gchar *search);
    SeahorseOperation*  seahorse_context_transfer_objects   (SeahorseContext *sctx,
                                                             GList *objs,
                                                             SeahorseSource *to);
    SeahorseOperation*  seahorse_context_retrieve_objects   (SeahorseContext *sctx,
                                                             GQuark ktype,
                                                             GSList *ids,
                                                             SeahorseSource *to);
    GList*              seahorse_context_discover_objects   (SeahorseContext *sctx,
                                                             GQuark ktype,
                                                             GSList *ids);
    struct _SeahorseObject* seahorse_context_object_from_dbus
                                                            (SeahorseContext *sctx,
                                                             const gchar *dbusid);
    gchar*              seahorse_context_object_to_dbus     (SeahorseContext *sctx,
                                                             struct _SeahorseObject *sobj);
    gchar*              seahorse_context_id_to_dbus         (SeahorseContext *sctx,
                                                             GQuark id);
    GQuark              (*SeahorseCanonizeFunc)             (const gchar *id);
    GQuark              seahorse_context_canonize_id        (GQuark ktype,
                                                             const gchar *id);

## Description

## Details

### SeahorseContextPrivate

    typedef struct _SeahorseContextPrivate SeahorseContextPrivate;

### SeahorseContext

    typedef struct {
        GtkObject               parent;

        gboolean                is_daemon;
    } SeahorseContext;

This is where all the action in a Seahorse process comes together.

- Usually there's only one SeahorseContext per process created by passing `SEAHORSE_CONTEXT_APP` to `seahorse_context_new()`, and accessed via the `SCTX_APP` macro. - Retains the list of all valid struct _SeahorseObject objects. - Has a collection of SeahorseSource objects which add objects to the SeahorseContext.

Signals: added: A object was added to the context. removed: A object was removed from the context. changed: A object changed. destroy: The context was destroyed.

GtkObject `parent`; | The parent GtkObject
gboolean `is_daemon`; | a gboolean indicating whether the context is being used in a program that is daemonized

### SeahorseObjectFunc ()

    void                (*SeahorseObjectFunc)               (struct _SeahorseObject *obj,
                                                             gpointer user_data);

`obj` : |
`user_data` : |

### SCTX_APP

    #define             SCTX_APP()                          (seahorse_context_for_app ())

### seahorse_context_for_app ()

    SeahorseContext*    seahorse_context_for_app            (void);

Returns : | the application main context as SeahorseContext

### seahorse_context_new ()

    SeahorseContext*    seahorse_context_new                (guint flags);

Creates a new SeahorseContext. Flags: SEAHORSE_CONTEXT_DAEMON: internal daemon flag will be set SEAHORSE_CONTEXT_APP: will support DNS-SD discovery and remote key sources

`flags` : | Flags define the type of the context to create.
Returns : | The new context

### seahorse_context_destroy ()

    void                seahorse_context_destroy            (SeahorseContext *sctx);

Emits the destroy signal for `sctx`.

`sctx` : | SeahorseContext to destroy

### seahorse_context_is_daemon()

    #define             seahorse_context_is_daemon(ctx)     ((ctx)->is_daemon)

`ctx` : |

### seahorse_context_add_source ()

    void                seahorse_context_add_source         (SeahorseContext *sctx,
                                                             SeahorseSource *sksrc);

Adds `sksrc` to the `sctx`. If `sctx` is NULL it will use the application context. It also adds a reference to the new added source.

`sctx` : | A context to add a source to, can be NULL
`sksrc` : | The source to add

### seahorse_context_take_source ()

    void                seahorse_context_take_source        (SeahorseContext *sctx,
                                                             SeahorseSource *sksrc);

Adds `sksrc` to the `sctx`. If `sctx` is NULL it will use the application context.

`sctx` : | A context to add a source to, can be NULL
`sksrc` : | The source to add

### seahorse_context_remove_source ()

    void                seahorse_context_remove_source      (SeahorseContext *sctx,
                                                             SeahorseSource *sksrc);

Remove all objects from source `sksrc` from the SeahorseContext `sctx`

`sctx` : | Context to remove objects from
`sksrc` : | The source to remove

### seahorse_context_find_source ()

    SeahorseSource*     seahorse_context_find_source        (SeahorseContext *sctx,
                                                             GQuark ktype,
                                                             SeahorseLocation location);

Finds a context where `ktype` and `location` match

`sctx` : | A SeahorseContext
`ktype` : | A seahorse tag (SEAHORSE_TAG_INVALID is wildcard)
`location` : | A location (SEAHORSE_LOCATION_INVALID is wildcard)
Returns : | The context

### seahorse_context_find_sources ()

    GSList*             seahorse_context_find_sources       (SeahorseContext *sctx,
                                                             GQuark ktype,
                                                             SeahorseLocation location);

`sctx` : | the context to work with
`ktype` : | the type of the key to match. Or SEAHORSE_TAG_INVALID
`location` : | the location to match. Or SEAHORSE_LOCATION_INVALID
Returns : | A list of seahorse sources matching `ktype` and `location` as GSList. Must be freed with g_slist_free

### seahorse_context_remote_source ()

    SeahorseSource*     seahorse_context_remote_source      (SeahorseContext *sctx,
                                                             const gchar *uri);

Add a remote source to the Context `sctx`. If it already exists, the source object will be returned.

`sctx` : | the context to add the source to (can be NULL)
`uri` : | An URI to add as remote source
Returns : | The SeahorseSource with this URI

### seahorse_context_add_object ()

    void                seahorse_context_add_object         (SeahorseContext *sctx,
                                                             struct _SeahorseObject *sobj);

Adds `sobj` to `sctx`. References `sobj`

`sctx` : | The context to add the object to
`sobj` : | The object to add

### seahorse_context_take_object ()

    void                seahorse_context_take_object        (SeahorseContext *sctx,
                                                             struct _SeahorseObject *sobj);

Adds `sobj` to `sctx`. If a similar object exists, it will be overwritten. Emits the "added" signal.

`sctx` : | The SeahorseContext context to add an object to
`sobj` : | The SeahorseObject object to add

### seahorse_context_get_count ()

    guint               seahorse_context_get_count          (SeahorseContext *sctx);

`sctx` : | The context. If NULL is passed it will take the application context
Returns : | The number of objects in this context

### seahorse_context_get_object ()

    struct _SeahorseObject* seahorse_context_get_object     (SeahorseContext *sctx,
                                                             SeahorseSource *sksrc,
                                                             GQuark id);

Finds the object with the source `sksrc` and `id` in the context and returns it

`sctx` : | The SeahorseContext to look in
`sksrc` : | The source to match
`id` : | the id to match
Returns : | The matching object

### seahorse_context_get_objects ()

    GList*              seahorse_context_get_objects        (SeahorseContext *sctx,
                                                             SeahorseSource *sksrc);

`sctx` : |
`sksrc` : |
Returns : | A GList of objects from `self` that match the source `source`

### seahorse_context_find_object ()

    struct _SeahorseObject* seahorse_context_find_object    (SeahorseContext *sctx,
                                                             GQuark id,
                                                             SeahorseLocation location);

Finds the object with the id `id` at location `location` or better. Local is better than remote...

`sctx` : | The SeahorseContext to work with (can be NULL)
`id` : | The id to look for
`location` : | The location to look for (at least)
Returns : | the matching SeahorseObject or NULL if none is found

### seahorse_context_find_objects ()

    GList*              seahorse_context_find_objects       (SeahorseContext *sctx,
                                                             GQuark ktype,
                                                             SeahorseUsage usage,
                                                             SeahorseLocation location);

`sctx` : | A SeahorseContext to look in (can be NULL)
`ktype` : | The tag to look for
`usage` : | the usage (SeahorseUsage)
`location` : | the location to look for
Returns : | A list of matching objects

### seahorse_context_find_objects_full ()

    GList*              seahorse_context_find_objects_full  (SeahorseContext *self,
                                                             struct _SeahorseObjectPredicate *skpred);

Finds matching objects and adds them to the list

`self` : | The SeahorseContext to match objects in
`skpred` : |
Returns : | a GList list containing the matching objects

### seahorse_context_for_objects_full ()

    void                seahorse_context_for_objects_full   (SeahorseContext *self,
                                                             struct _SeahorseObjectPredicate *skpred,
                                                             SeahorseObjectFunc func,
                                                             gpointer user_data);

Calls `func` for every object in `self` matching the criteria in `pred`. `user_data` is passed to this function

`self` : | SeahorseContext to work with
`skpred` : |
`func` : | Function to call for matching objects
`user_data` : | Data to pass to this function

### seahorse_context_verify_objects ()

    void                seahorse_context_verify_objects     (SeahorseContext *self);

Verifies each key in the given context. An assertion handles failure.

`self` : | A SeahorseContext to verify

### seahorse_context_remove_object ()

    void                seahorse_context_remove_object      (SeahorseContext *sctx,
                                                             struct _SeahorseObject *sobj);

Removes the object from the context

`sctx` : | The SeahorseContext (can be NULL)
`sobj` : | The SeahorseObject to remove

### seahorse_context_get_discovery ()

    SeahorseServiceDiscovery * seahorse_context_get_discovery
                                                            (SeahorseContext *sctx);

### Warning

`seahorse_context_get_discovery` is deprecated and should not be used in newly-written code. No replacement

Gets the Service Discovery object for this context.

`sctx` : | SeahorseContext object
Returns : | The Service Discovery object.

### seahorse_context_get_default_key ()

    struct _SeahorseObject * seahorse_context_get_default_key
                                                            (SeahorseContext *sctx);

### Warning

`seahorse_context_get_default_key` is deprecated and should not be used in newly-written code. No replacement

`sctx` : | Current SeahorseContext
Returns : | the secret key that's the default key

### seahorse_context_refresh_auto ()

    void                seahorse_context_refresh_auto       (SeahorseContext *sctx);

Starts a new refresh operation and emits the "refreshing" signal

`sctx` : | A SeahorseContext (can be NULL)

### seahorse_context_search_remote ()

    SeahorseOperation*  seahorse_context_search_remote      (SeahorseContext *sctx,
                                                             const gchar *search);

Searches for the key matching `search` o the remote servers

`sctx` : | A SeahorseContext (can be NULL)
`search` : | a keyword (name, email address...) to search for
Returns : | The created search operation

### seahorse_context_transfer_objects ()

    SeahorseOperation*  seahorse_context_transfer_objects   (SeahorseContext *sctx,
                                                             GList *objs,
                                                             SeahorseSource *to);

`sctx` : | The SeahorseContext (can be NULL)
`objs` : |
`to` : | a source to import to (can be NULL)
Returns : | A transfer operation

### seahorse_context_retrieve_objects ()

    SeahorseOperation*  seahorse_context_retrieve_objects   (SeahorseContext *sctx,
                                                             GQuark ktype,
                                                             GSList *ids,
                                                             SeahorseSource *to);

Copies remote objects to a local source

`sctx` : | A SeahorsecContext
`ktype` : | The type of the keys to transfer
`ids` : | The key ids to transfer
`to` : | A SeahorseSource. If NULL, it will use `ktype` to find a source
Returns : | A SeahorseOperation

### seahorse_context_discover_objects ()

    GList*              seahorse_context_discover_objects   (SeahorseContext *sctx,
                                                             GQuark ktype,
                                                             GSList *ids);

Downloads a list of keys from the keyserver

`sctx` : | the context to work with (can be NULL)
`ktype` : | the type of key to discover
`ids` : |
Returns : | The imported keys

### seahorse_context_object_from_dbus ()

    struct _SeahorseObject* seahorse_context_object_from_dbus
                                                            (SeahorseContext *sctx,
                                                             const gchar *dbusid);

Finds an object basing on the `key`

`sctx` : | A SeahorseContext
`dbusid` : |
Returns : | The SeahorseObject found. NULL on not found.

### seahorse_context_object_to_dbus ()

    gchar*              seahorse_context_object_to_dbus     (SeahorseContext *sctx,
                                                             struct _SeahorseObject *sobj);

Translates an object to a string id

`sctx` : | A seahorse context
`sobj` : | the object
Returns : | The string id of the object. Free with g_free

### seahorse_context_id_to_dbus ()

    gchar*              seahorse_context_id_to_dbus         (SeahorseContext *sctx,
                                                             GQuark id);

Translates an id to a dbus compatible string

`sctx` : | ignored
`id` : | the id to translate
Returns : | A string, free with g_free

### SeahorseCanonizeFunc ()

    GQuark              (*SeahorseCanonizeFunc)             (const gchar *id);

`id` : |
Returns : |

### seahorse_context_canonize_id ()

    GQuark              seahorse_context_canonize_id        (GQuark ktype,
                                                             const gchar *id);

`ktype` : | a keytype defining the canonization function
`id` : | The id to canonize
Returns : | A canonized GQuark