EConfigLookup: Evolution Utilities Reference Manual

## EConfigLookup EConfigLookup — Configuration lookup |

## Functions

EConfigLookup * | e_config_lookup_new ()
ESourceRegistry * | e_config_lookup_get_registry ()
ESource * | e_config_lookup_get_source ()
gboolean | e_config_lookup_get_busy ()
void | e_config_lookup_cancel_all ()
void | e_config_lookup_register_worker ()
void | e_config_lookup_unregister_worker ()
GSList * | e_config_lookup_dup_registered_workers ()
void | e_config_lookup_run ()
void | e_config_lookup_run_finish ()
void | e_config_lookup_run_worker ()
void | e_config_lookup_add_result ()
gint | e_config_lookup_count_results ()
GSList * | e_config_lookup_dup_results ()
void | e_config_lookup_clear_results ()
const gchar * | e_config_lookup_encode_certificate_trust ()
ETrustPromptResponse | e_config_lookup_decode_certificate_trust ()

## Properties

gboolean | busy | Read
ESourceRegistry * | registry | Read / Write / Construct Only

## Signals

gpointer | get-source | Action
void | result-added | Run Last
void | worker-finished | Run Last
void | worker-started | Run Last

## Types and Values

#define | E_CONFIG_LOOKUP_PARAM_USER
#define | E_CONFIG_LOOKUP_PARAM_PASSWORD
#define | E_CONFIG_LOOKUP_PARAM_REMEMBER_PASSWORD
#define | E_CONFIG_LOOKUP_PARAM_EMAIL_ADDRESS
#define | E_CONFIG_LOOKUP_PARAM_SERVERS
#define | E_CONFIG_LOOKUP_PARAM_CERTIFICATE_PEM
#define | E_CONFIG_LOOKUP_PARAM_CERTIFICATE_HOST
#define | E_CONFIG_LOOKUP_PARAM_CERTIFICATE_TRUST
struct | EConfigLookup

## Object Hierarchy

        GObject
        ╰── EConfigLookup

## Implemented Interfaces

EConfigLookup implements EExtensible.

## Includes

    #include <e-util/e-util.h>

## Description

EConfigLookup is used to search for configuration of an account, which is identified by an e-mail address, server address or such. It is an EExtensible object, where the extensions connect to the “run” signal to run the configuration lookup.

## Functions

### e_config_lookup_new ()

    EConfigLookup *
    e_config_lookup_new (ESourceRegistry *registry);

Creates a new EConfigLookup instance.

#### Parameters

registry | an ESourceRegistry |

#### Returns

a new EConfigLookup.

[transfer full]

Since: 3.26

### e_config_lookup_get_registry ()

    ESourceRegistry *
    e_config_lookup_get_registry (EConfigLookup *config_lookup);

Returns the ESourceRegistry passed to `e_config_lookup_new()`.

#### Parameters

config_lookup | an EConfigLookup |

#### Returns

an ESourceRegistry.

[transfer none]

Since: 3.26

### e_config_lookup_get_source ()

    ESource *
    e_config_lookup_get_source (EConfigLookup *config_lookup,
                                EConfigLookupSourceKind kind);

Emits the “get-source” signal and any listener can provide the source. The function can return `NULL`, when there are no listeners or when such source is not available.

#### Parameters

config_lookup | an EConfigLookup |
kind | one of EConfigLookupSourceKind, except of the `E_CONFIG_LOOKUP_SOURCE_UNKNOWN` |

#### Returns

an ESource of the given `kind` , or `NULL`, if not found.

[transfer none][nullable]

Since: 3.26

### e_config_lookup_get_busy ()

    gboolean
    e_config_lookup_get_busy (EConfigLookup *config_lookup);

Returns whether there's any running worker. They can be cancelled with `e_config_lookup_cancel_all()`.

#### Parameters

config_lookup | an EConfigLookup |

#### Returns

whether there's any running worker

Since: 3.28

### e_config_lookup_cancel_all ()

    void
    e_config_lookup_cancel_all (EConfigLookup *config_lookup);

Cancels all pending workers.

#### Parameters

config_lookup | an EConfigLookup |

Since: 3.28

### e_config_lookup_register_worker ()

    void
    e_config_lookup_register_worker (EConfigLookup *config_lookup,
                                     EConfigLookupWorker *worker);

Registers a `worker` as a worker, which can be run as part of `e_config_lookup_run()`. The function adds its own reference to `worker` .

#### Parameters

config_lookup | an EConfigLookup |
worker | an EConfigLookupWorker |

Since: 3.28

### e_config_lookup_unregister_worker ()

    void
    e_config_lookup_unregister_worker (EConfigLookup *config_lookup,
                                       EConfigLookupWorker *worker);

Removes a `worker` previously registered with `e_config_lookup_register_worker()`.

#### Parameters

config_lookup | an EConfigLookup |
worker | an EConfigLookupWorker |

Since: 3.28

### e_config_lookup_dup_registered_workers ()

    GSList *
    e_config_lookup_dup_registered_workers
                                   (EConfigLookup *config_lookup);

Returns a list of all registered EConfigLookupWorker objects.

The returned GSList should be freed with g_slist_free_full (workers, g_object_unref); when no longer needed.

#### Parameters

config_lookup | an EConfigLookup |

#### Returns

a GSList with all workers registered with `e_config_lookup_register_worker()`.

[transfer full][element-type EConfigLookupWorker]

Since: 3.28

### e_config_lookup_run ()

    void
    e_config_lookup_run (EConfigLookup *config_lookup,
                         const ENamedParameters *params,
                         GCancellable *cancellable,
                         GAsyncReadyCallback callback,
                         gpointer user_data);

Runs configuration lookup asynchronously. Once the run is done, the `callback` is called, and the call can be finished with `e_config_lookup_run_finish()`. The `callback` is always called from the main thread.

Workers can be run individually using `e_config_lookup_run_worker()`.

Note that there cannot be run two lookups at the same time, thus if it happens, then the `callback` is called immediately with a `NULL` result.

#### Parameters

config_lookup | an EConfigLookup |
params | an ENamedParameters with lookup parameters |
cancellable | an optional GCancellable, or `NULL` |
callback | a callback to call, when the run is finished |
user_data | user data for the `callback` |

Since: 3.26

### e_config_lookup_run_finish ()

    void
    e_config_lookup_run_finish (EConfigLookup *config_lookup,
                                GAsyncResult *result);

Finishes the configuration lookup previously run by `e_config_lookup_run()`. It's expected that the extensions may fail, thus it doesn't return anything and is provided mainly for consistency with asynchronous API.

#### Parameters

config_lookup | an EConfigLookup |
result | result of the operation |

Since: 3.26

### e_config_lookup_run_worker ()

    void
    e_config_lookup_run_worker (EConfigLookup *config_lookup,
                                EConfigLookupWorker *worker,
                                const ENamedParameters *params,
                                GCancellable *cancellable);

Creates a new thread and runs `worker` in it. When the `cancellable` is `NULL`, then there's creates a new CamelOperation, which either proxies currently running lookup or the newly created cancellable is completely independent.

This function can be called while there's an ongoing configuration lookup, but also when the `worker` is restarted.

#### Parameters

config_lookup | an EConfigLookup |
worker | an EConfigLookupWorker to run in a dedicated thread |
params | an ENamedParameters with lookup parameters |
cancellable | an optional GCancellable, or `NULL` |

Since: 3.28

### e_config_lookup_add_result ()

    void
    e_config_lookup_add_result (EConfigLookup *config_lookup,
                                EConfigLookupResult *result);

Adds a new `result` in a list of known configuration lookup results. The `config_lookup` assumes ownership of the `result` and frees it when no longer needed.

The list of results can be obtained with `e_config_lookup_dup_results()`.

#### Parameters

config_lookup | an EConfigLookup |
result | an EConfigLookupResult. | [transfer full]

Since: 3.26

### e_config_lookup_count_results ()

    gint
    e_config_lookup_count_results (EConfigLookup *config_lookup);

#### Parameters

config_lookup | an EConfigLookup |

#### Returns

how many results had been added already.

Since: 3.28

### e_config_lookup_dup_results ()

    GSList *
    e_config_lookup_dup_results (EConfigLookup *config_lookup,
                                 EConfigLookupResultKind kind,
                                 const gchar *protocol);

Returns a GSList with EConfigLookupResult objects satisfying the `kind` and `protocol` filtering conditions. To receive all gathered results use `E_CONFIG_LOOKUP_RESULT_UNKNOWN` for `kind` and `NULL` for the `protocol` .

Free the returned GSList with g_slist_free_full (results, g_object_unref); when no longer needed.

#### Parameters

config_lookup | an EConfigLookup |
kind | an EConfigLookupResultKind to filter the results with |
protocol | optional protocol to filter the results with, or `NULL`. | [nullable]

#### Returns

a GSList with results satisfying the `kind` and `protocol` filtering conditions.

[transfer full][element-type EConfigLookupResult]

Since: 3.28

### e_config_lookup_clear_results ()

    void
    e_config_lookup_clear_results (EConfigLookup *config_lookup);

Frees all gathered results. This might be usually called before starting new custom lookup. The `e_config_lookup_run()` frees all results automatically.

#### Parameters

config_lookup | an EConfigLookup |

Since: 3.28

### e_config_lookup_encode_certificate_trust ()

    const gchar *
    e_config_lookup_encode_certificate_trust
                                   (ETrustPromptResponse response);

Encodes `response` to a string. This can be decoded back to enum with `e_config_lookup_decode_certificate_trust()`.

#### Parameters

response | an ETrustPromptResponse to encode |

#### Returns

string representation of `response` .

Since: 3.28

### e_config_lookup_decode_certificate_trust ()

    ETrustPromptResponse
    e_config_lookup_decode_certificate_trust
                                   (const gchar *value);

Decodes text `value` to ETrustPromptResponse, previously encoded with `e_config_lookup_encode_certificate_trust()`.

#### Parameters

value | a text value to decode |

#### Returns

an ETrustPromptResponse corresponding to `value` .

Since: 3.28

## Types and Values

### E_CONFIG_LOOKUP_PARAM_USER

    #define E_CONFIG_LOOKUP_PARAM_USER		"user"

### E_CONFIG_LOOKUP_PARAM_PASSWORD

    #define E_CONFIG_LOOKUP_PARAM_PASSWORD		"password"

### E_CONFIG_LOOKUP_PARAM_REMEMBER_PASSWORD

    #define E_CONFIG_LOOKUP_PARAM_REMEMBER_PASSWORD "remember-password" /* Is part of params, if can remember, otherwise not in params */

### E_CONFIG_LOOKUP_PARAM_EMAIL_ADDRESS

    #define E_CONFIG_LOOKUP_PARAM_EMAIL_ADDRESS "email-address"

### E_CONFIG_LOOKUP_PARAM_SERVERS

    #define E_CONFIG_LOOKUP_PARAM_SERVERS		"servers"

### E_CONFIG_LOOKUP_PARAM_CERTIFICATE_PEM

    #define E_CONFIG_LOOKUP_PARAM_CERTIFICATE_PEM "certificate-pem"

### E_CONFIG_LOOKUP_PARAM_CERTIFICATE_HOST

    #define E_CONFIG_LOOKUP_PARAM_CERTIFICATE_HOST "certificate-host"

### E_CONFIG_LOOKUP_PARAM_CERTIFICATE_TRUST

    #define E_CONFIG_LOOKUP_PARAM_CERTIFICATE_TRUST "certificate-trust"

### struct EConfigLookup

    struct EConfigLookup;

Contains only private data that should be read and manipulated using the functions below.

Since: 3.26

## Property Details

### The `“busy”` property

      “busy”                     gboolean

Whether the EConfigLookup has any running workers.

Owner: EConfigLookup

Flags: Read

Default value: FALSE

Since: 3.28

### The `“registry”` property

      “registry”                 ESourceRegistry *

The ESourceRegistry manages ESource instances.

Owner: EConfigLookup

Flags: Read / Write / Construct Only

Since: 3.26

## Signal Details

### The `“get-source”` signal

    gpointer
    user_function (EConfigLookup          *kind,
                   EConfigLookupSourceKind arg1,
                   gpointer                user_data)

Emitted to get an ESource of the given `kind` . Return `NULL`, when not available.

#### Parameters

kind | an EConfigLookupSourceKind |
user_data | user data set when the signal handler was connected. |

Flags: Action

Since: 3.26

### The `“result-added”` signal

    void
    user_function (EConfigLookup       *result,
                   EConfigLookupResult *arg1,
                   gpointer             user_data)

Emitted when a new `result` is added to the config lookup.

Note that this signal can be emitted in a worker's dedicated thread.

#### Parameters

result | an EConfigLookupResult |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.28

### The `“worker-finished”` signal

    void
    user_function (EConfigLookup       *worker,
                   EConfigLookupWorker *restart_params,
                   ENamedParameters    *error,
                   GError              *arg3,
                   gpointer             user_data)

Emitted when the `worker` finished its running.

Note that this signal is always emitted in the main thread.

#### Parameters

worker | an EConfigLookupWorker |
restart_params | an optional ENamedParameters to use when the `worker` might be restarted |
error | an optional GError with an overall result of the run |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.28

### The `“worker-started”` signal

    void
    user_function (EConfigLookup       *worker,
                   EConfigLookupWorker *cancellable,
                   GCancellable        *arg2,
                   gpointer             user_data)

Emitted when the `worker` is about to start running. Corresponding `EConfigLookup` ::worker-finished is emitted when the run is finished.

Note that this signal is always emitted in the main thread.

#### Parameters

worker | an EConfigLookupWorker |
cancellable | associated GCancellable for this worker run |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.28