## camel-provider

camel-provider

## Functions

#define | CAMEL_PROVIDER_ALLOWS()
#define | CAMEL_PROVIDER_NEEDS()
#define | CAMEL_PROVIDER_HIDDEN()
gint | (*CamelProviderAutoDetectFunc) ()
void | camel_provider_init ()
gboolean | camel_provider_load ()
void | camel_provider_register ()
GList * | camel_provider_list ()
CamelProvider * | camel_provider_get ()
void | camel_provider_module_init ()
gint | camel_provider_auto_detect ()

## Types and Values

#define | EDS_CAMEL_PROVIDER_DIR
#define | CAMEL_URL_PART_USER
#define | CAMEL_URL_PART_AUTH
#define | CAMEL_URL_PART_PASSWORD
#define | CAMEL_URL_PART_HOST
#define | CAMEL_URL_PART_PORT
#define | CAMEL_URL_PART_PATH
#define | CAMEL_URL_PART_PATH_DIR
#define | CAMEL_URL_PART_NEED
#define | CAMEL_URL_PART_HIDDEN
enum | CamelProviderURLFlags
| CamelProviderConfEntry
| CamelProviderPortEntry
struct | CamelProviderModule

## Object Hierarchy

        GBoxed
        ╰── CamelProvider

## Description

## Functions

### CAMEL_PROVIDER_ALLOWS()

    #define             CAMEL_PROVIDER_ALLOWS(prov, flags)

### CAMEL_PROVIDER_NEEDS()

    #define             CAMEL_PROVIDER_NEEDS(prov, flags)

### CAMEL_PROVIDER_HIDDEN()

    #define             CAMEL_PROVIDER_HIDDEN(prov, flags)

### CamelProviderAutoDetectFunc ()

    gint
    (*CamelProviderAutoDetectFunc) (CamelURL *url,
                                    GHashTable **auto_detected,
                                    GError **error);

Function used in `camel_provider_auto_detect()`.

#### Parameters

url | a CamelURL |
auto_detected | output GHashTable of auto-detected values. | [out][element-type utf8 utf8][nullable]
error | return location for a GError, or `NULL` |

#### Returns

0 on success or -1 on fail.

### camel_provider_init ()

    void
    camel_provider_init (void);

Initialize the Camel provider system by reading in the .urls files in the provider directory and creating a hash table mapping URLs to module names.

A .urls file has the same initial prefix as the shared library it correspond to, and consists of a series of lines containing the URL protocols that that library handles.

TODO: This should be pathed? TODO: This should be plugin-d?

### camel_provider_load ()

    gboolean
    camel_provider_load (const gchar *path,
                         GError **error);

Loads the provider at `path` , and calls its initialization function, passing `session` as an argument. The provider should then register itself with `session` .

#### Parameters

path | the path to a shared library |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on failure

### camel_provider_register ()

    void
    camel_provider_register (CamelProvider *provider);

Registers a provider.

#### Parameters

provider | provider object |

### camel_provider_list ()

    GList *
    camel_provider_list (gboolean load);

This returns a list of available providers. If `load` is `TRUE`, it will first load in all available providers that haven't yet been loaded.

Free the returned list with `g_list_free()`. The CamelProvider structs in the list are owned by Camel and should not be modified or freed.

#### Parameters

load | whether or not to load in providers that are not already loaded |

#### Returns

a GList of CamelProvider structs.

[element-type CamelProvider][transfer container]

### camel_provider_get ()

    CamelProvider *
    camel_provider_get (const gchar *protocol,
                        GError **error);

Returns the registered CamelProvider for `protocol` , loading it from disk if necessary. If no CamelProvider can be found for `protocol` , or the provider module fails to load, the function sets `error` and returns `NULL`.

The returned CamelProvider is owned by Camel and should not be modified or freed.

#### Parameters

protocol | a CamelProvider protocol name |
error | return location for a GError, or `NULL` |

#### Returns

a CamelProvider for `protocol` , or `NULL` on error

### camel_provider_module_init ()

    void
    camel_provider_module_init (void);

### camel_provider_auto_detect ()

    gint
    camel_provider_auto_detect (CamelProvider *provider,
                                CamelURL *url,
                                GHashTable **auto_detected,
                                GError **error);

After filling in the standard Username/Hostname/Port/Path settings (which must be set in `url` ), if the provider supports it, you may wish to have the provider auto-detect further settings based on the aformentioned settings.

If the provider does not support auto-detection, `auto_detected` will be set to `NULL`. Otherwise the provider will attempt to auto-detect whatever it can and file them into `auto_detected` . If for some reason it cannot auto-detect anything (not enough information provided in `url` ?) then `auto_detected` will be set to `NULL` and an exception may be set to explain why it failed.

#### Parameters

provider | camel provider |
url | a CamelURL |
auto_detected | output GHashTable of auto-detected values. | [out][element-type utf8 utf8][nullable]
error | return location for a GError, or `NULL` |

#### Returns

0 on success or -1 on fail.

## Types and Values

### EDS_CAMEL_PROVIDER_DIR

    #define EDS_CAMEL_PROVIDER_DIR    "EDS_CAMEL_PROVIDER_DIR"

This environment variable configures where the camel provider modules are loaded from.

### CAMEL_URL_PART_USER

    #define CAMEL_URL_PART_USER	 (1 << 0)

### CAMEL_URL_PART_AUTH

    #define CAMEL_URL_PART_AUTH	 (1 << 1)

### CAMEL_URL_PART_PASSWORD

    #define CAMEL_URL_PART_PASSWORD	 (1 << 2)

### CAMEL_URL_PART_HOST

    #define CAMEL_URL_PART_HOST	 (1 << 3)

### CAMEL_URL_PART_PORT

    #define CAMEL_URL_PART_PORT	 (1 << 4)

### CAMEL_URL_PART_PATH

    #define CAMEL_URL_PART_PATH	 (1 << 5)

### CAMEL_URL_PART_PATH_DIR

    #define CAMEL_URL_PART_PATH_DIR  (1 << 6)

### CAMEL_URL_PART_NEED

    #define CAMEL_URL_PART_NEED	       8

### CAMEL_URL_PART_HIDDEN

    #define CAMEL_URL_PART_HIDDEN (CAMEL_URL_PART_NEED + 8)

### enum CamelProviderURLFlags

#### Members

CAMEL_URL_ALLOW_USER |  |
CAMEL_URL_ALLOW_AUTH |  |
CAMEL_URL_ALLOW_PASSWORD |  |
CAMEL_URL_ALLOW_HOST |  |
CAMEL_URL_ALLOW_PORT |  |
CAMEL_URL_ALLOW_PATH |  |
CAMEL_URL_NEED_USER |  |
CAMEL_URL_NEED_AUTH |  |
CAMEL_URL_NEED_PASSWORD |  |
CAMEL_URL_NEED_HOST |  |
CAMEL_URL_NEED_PORT |  |
CAMEL_URL_NEED_PATH |  |
CAMEL_URL_NEED_PATH_DIR |  |
CAMEL_URL_HIDDEN_USER |  |
CAMEL_URL_HIDDEN_AUTH |  |
CAMEL_URL_HIDDEN_PASSWORD |  |
CAMEL_URL_HIDDEN_HOST |  |
CAMEL_URL_HIDDEN_PORT |  |
CAMEL_URL_HIDDEN_PATH |  |
CAMEL_URL_FRAGMENT_IS_PATH |  |
CAMEL_URL_PATH_IS_ABSOLUTE |  |

### CamelProviderConfEntry

    typedef struct {
    	CamelProviderConfType type;
    	const gchar *name, *depname;
    	const gchar *text, *value;
    } CamelProviderConfEntry;

### CamelProviderPortEntry

    typedef struct {
    	gint port;
    	const gchar *desc;
    	gboolean is_ssl;
    } CamelProviderPortEntry;

#### Members

gint `port`; | port number |
const gchar *`desc`; | human description of the port |
gboolean `is_ssl`; | a boolean whether the port is used together with TLS/SSL |

Since: 3.2

### struct CamelProviderModule

    struct CamelProviderModule {
    	gchar *path;
    	GSList *types;
    	guint loaded : 1;
    };