E2kAutoconfig

## E2kAutoconfig E2kAutoconfig — Account autoconfiguration |

## Synopsis

                E2kAutoconfig;
    enum        E2kExchangeVersion;
    enum        E2kAutoconfigAuthPref;
    enum        E2kAutoconfigResult;
    E2kAutoconfig* e2k_autoconfig_new           (const char *owa_uri,
                                                 const char *username,
                                                 const char *password,
                                                 E2kAutoconfigAuthPref auth_pref);
    void        e2k_autoconfig_free             (E2kAutoconfig *ac);
    void        e2k_autoconfig_set_owa_uri      (E2kAutoconfig *ac,
                                                 const char *owa_uri);
    void        e2k_autoconfig_set_gc_server    (E2kAutoconfig *ac,
                                                 const char *gc_server,
                                                 int gal_limit);
    void        e2k_autoconfig_set_username     (E2kAutoconfig *ac,
                                                 const char *username);
    void        e2k_autoconfig_set_password     (E2kAutoconfig *ac,
                                                 const char *password);
    E2kContext* e2k_autoconfig_get_context      (E2kAutoconfig *ac,
                                                 E2kOperation *op,
                                                 E2kAutoconfigResult *result);
    E2kAutoconfigResult e2k_autoconfig_check_exchange
                                                (E2kAutoconfig *ac,
                                                 E2kOperation *op);
    E2kGlobalCatalog* e2k_autoconfig_get_global_catalog
                                                (E2kAutoconfig *ac,
                                                 E2kOperation *op);
    E2kAutoconfigResult e2k_autoconfig_check_global_catalog
                                                (E2kAutoconfig *ac,
                                                 E2kOperation *op);
    const char* e2k_autoconfig_lookup_option    (const char *option);

## Description

The `E2kAutoconfig` object handles trying to automatically configure a user’s account without requiring the user to have to know arcane details about the organization of the company’s Exchange servers.

## Details

### E2kAutoconfig

    typedef struct {
    	/* Input data. (gc_server is optional) */
    	char *owa_uri, *gc_server;
    	char *username, *password;
    	int gal_limit;

    	/* Output data */
    	E2kExchangeVersion version;
    	char *display_name, *email;
    	char *account_uri, *exchange_server;
    	char *timezone;

    	/* Private-ish members */
    	char *nt_domain, *w2k_domain;
    	char *home_uri, *exchange_dn;
    	char *pf_server;
    	E2kAutoconfigAuthPref auth_pref;
    	gboolean require_ntlm, use_ntlm;
    	gboolean saw_basic, saw_ntlm;
    	gboolean nt_domain_defaulted, gc_server_autodetected;
    } E2kAutoconfig;

The `version`, `exchange_server`, and `timezone` fields are set by `e2k_autoconfig_check_exchange()`.

The `display_name`, `email`, and `account_uri` fields are set by `e2k_autoconfig_check_global_catalog()`. `account_uri` is an camel-style URI describing the account configuration.

### enum E2kExchangeVersion

    typedef enum {
    	E2K_EXCHANGE_UNKNOWN,
    	E2K_EXCHANGE_2000,
    	E2K_EXCHANGE_2003,

    	E2K_EXCHANGE_FUTURE
    } E2kExchangeVersion;

E2kExchangeVersion represents the version of Exchange detected on the server.

`E2K_EXCHANGE_UNKNOWN` | The server seems to be running Exchange 2000 or later, but we couldn’t figure out what version.
`E2K_EXCHANGE_2000` | The server is running Exchange 2000
`E2K_EXCHANGE_2003` | The server is running Exchange 2003
`E2K_EXCHANGE_FUTURE` | The server seems to be running some version of Exchange newer than Exchange 2003.

### enum E2kAutoconfigAuthPref

    typedef enum {
    	E2K_AUTOCONFIG_USE_BASIC,
    	E2K_AUTOCONFIG_USE_NTLM,
    	E2K_AUTOCONFIG_USE_EITHER,
    } E2kAutoconfigAuthPref;

E2kAutoconfigAuthPref indicates what sort of authentication the user wants to use.

`E2K_AUTOCONFIG_USE_BASIC` | Only try "Basic" authentication
`E2K_AUTOCONFIG_USE_NTLM` | Only try "NTLM" authentication
`E2K_AUTOCONFIG_USE_EITHER` | Try both kinds.

### enum E2kAutoconfigResult

    typedef enum {
    	E2K_AUTOCONFIG_OK,
    	E2K_AUTOCONFIG_REDIRECT,
    	E2K_AUTOCONFIG_TRY_SSL,
    	E2K_AUTOCONFIG_AUTH_ERROR,
    	E2K_AUTOCONFIG_AUTH_ERROR_TRY_DOMAIN,
    	E2K_AUTOCONFIG_AUTH_ERROR_TRY_BASIC,
    	E2K_AUTOCONFIG_AUTH_ERROR_TRY_NTLM,
    	E2K_AUTOCONFIG_EXCHANGE_5_5,
    	E2K_AUTOCONFIG_NOT_EXCHANGE,
    	E2K_AUTOCONFIG_NO_OWA,
    	E2K_AUTOCONFIG_NO_MAILBOX,
    	E2K_AUTOCONFIG_CANT_BPROPFIND,
    	E2K_AUTOCONFIG_CANT_RESOLVE,
    	E2K_AUTOCONFIG_CANT_CONNECT,
    	E2K_AUTOCONFIG_CANCELLED,
    	E2K_AUTOCONFIG_FAILED
    } E2kAutoconfigResult;

See `e2k_autoconfig_get_context()`, `e2k_autoconfig_check_exchange()`, and `e2k_autoconfig_check_global_catalog()` for details about what the specific error codes mean.

### e2k_autoconfig_new ()

    E2kAutoconfig* e2k_autoconfig_new           (const char *owa_uri,
                                                 const char *username,
                                                 const char *password,
                                                 E2kAutoconfigAuthPref auth_pref);

Creates an autoconfig context, based on information stored in the config file or provided as arguments.

`owa_uri` : | the OWA URI, or `NULL` to (try to) use a default
`username` : | the username (or DOMAIN\username), or `NULL` to use a default
`password` : | the password, or `NULL` if not yet known
`auth_pref` : | information about what auth type to use
Returns : | an autoconfig context

### e2k_autoconfig_free ()

    void        e2k_autoconfig_free             (E2kAutoconfig *ac);

Frees `ac`.

`ac` : | an autoconfig context

### e2k_autoconfig_set_owa_uri ()

    void        e2k_autoconfig_set_owa_uri      (E2kAutoconfig *ac,
                                                 const char *owa_uri);

Sets `ac`'s owa_uri field to `owa_uri` (or the default if `owa_uri` is `NULL`), and resets any fields whose values had been set based on the old value of owa_uri.

`ac` : | an autoconfig context
`owa_uri` : | the new OWA URI, or `NULL`

### e2k_autoconfig_set_gc_server ()

    void        e2k_autoconfig_set_gc_server    (E2kAutoconfig *ac,
                                                 const char *gc_server,
                                                 int gal_limit);

Sets `ac`'s gc_server field to `gc_server` (or the default if `gc_server` is `NULL`) and the gal_limit field to `gal_limit`, and resets any fields whose values had been set based on the old value of gc_server.

`ac` : | an autoconfig context
`gc_server` : | the new GC server, or `NULL`
`gal_limit` : | GAL search size limit, or -1 for no limit

### e2k_autoconfig_set_username ()

    void        e2k_autoconfig_set_username     (E2kAutoconfig *ac,
                                                 const char *username);

Sets `ac`'s username field to `username` (or the default if `username` is `NULL`), and resets any fields whose values had been set based on the old value of username.

`ac` : | an autoconfig context
`username` : | the new username (or DOMAIN\username), or `NULL`

### e2k_autoconfig_set_password ()

    void        e2k_autoconfig_set_password     (E2kAutoconfig *ac,
                                                 const char *password);

Sets or clears `ac`'s password field.

`ac` : | an autoconfig context
`password` : | the new password, or `NULL` to clear

### e2k_autoconfig_get_context ()

    E2kContext* e2k_autoconfig_get_context      (E2kAutoconfig *ac,
                                                 E2kOperation *op,
                                                 E2kAutoconfigResult *result);

Checks if `ac`'s URI and authentication parameters work, and if so returns an E2kContext using them. On return, *`result` (which may not be `NULL`) will contain a result code as follows:

`E2K_AUTOCONFIG_OK` | Success
`E2K_AUTOCONFIG_REDIRECT` | The server issued a valid-looking redirect. `ac->owa_uri` has been updated and the caller should try again.
`E2K_AUTOCONFIG_TRY_SSL` | The server requires SSL. `ac->owa_uri` has been updated and the caller should try again.
`E2K_AUTOCONFIG_AUTH_ERROR` | Generic authentication failure. Probably password incorrect
`E2K_AUTOCONFIG_AUTH_ERROR_TRY_DOMAIN` | Authentication failed. Including an NT domain with the username (or using NTLM) may fix the problem.
`E2K_AUTOCONFIG_AUTH_ERROR_TRY_BASIC` | Caller requested NTLM auth, but only Basic was available.
`E2K_AUTOCONFIG_AUTH_ERROR_TRY_NTLM` | Caller requested Basic auth, but only NTLM was available.
`E2K_AUTOCONFIG_EXCHANGE_5_5` | Server appears to be Exchange 5.5.
`E2K_AUTOCONFIG_NOT_EXCHANGE` | Server does not appear to be any version of Exchange
`E2K_AUTOCONFIG_NO_OWA` | Server may be Exchange 2000, but OWA is not present at the given URL.
`E2K_AUTOCONFIG_NO_MAILBOX` | OWA claims the user has no mailbox.
`E2K_AUTOCONFIG_CANT_RESOLVE` | Could not resolve hostname.
`E2K_AUTOCONFIG_CANT_CONNECT` | Could not connect to server.
`E2K_AUTOCONFIG_CANCELLED` | User cancelled.
`E2K_AUTOCONFIG_FAILED` | Other error.

`ac` : | an autoconfig context
`op` : |
`result` : | on output, a result code
Returns : | the new context, or `NULL`

### e2k_autoconfig_check_exchange ()

    E2kAutoconfigResult e2k_autoconfig_check_exchange
                                                (E2kAutoconfig *ac,
                                                 E2kOperation *op);

Tries to connect to the the Exchange server using the OWA URL, username, and password in `ac`. Attempts to determine the domain name and home_uri, and then given the home_uri, looks up the user's mailbox entryid (used to find his Exchange 5.5 DN) and default timezone.

The result codes are the same as for `e2k_autoconfig_get_context()` with the following changes:

`E2K_AUTOCONFIG_REDIRECT` | The URL returned in first redirect returned another redirect, which was not followed.
`E2K_AUTOCONFIG_CANT_BPROPFIND` | The server does not allow BPROPFIND due to IIS Lockdown configuration
`E2K_AUTOCONFIG_TRY_SSL` | Not used; always handled internally by `e2k_autoconfig_check_exchange()`

`ac` : | an autoconfiguration context
`op` : |
Returns : | an E2kAutoconfigResult

### e2k_autoconfig_get_global_catalog ()

    E2kGlobalCatalog* e2k_autoconfig_get_global_catalog
                                                (E2kAutoconfig *ac,
                                                 E2kOperation *op);

Tries to connect to the global catalog associated with `ac` (trying to figure it out from the domain name if the server name is not yet known).

`ac` : | an autoconfig context
`op` : | an E2kOperation, for cancellation
Returns : | the global catalog, or `NULL` if the GC server name wasn't provided and couldn't be autodetected.

### e2k_autoconfig_check_global_catalog ()

    E2kAutoconfigResult e2k_autoconfig_check_global_catalog
                                                (E2kAutoconfig *ac,
                                                 E2kOperation *op);

Tries to connect to the global catalog associated with `ac` (trying to figure it out from the domain name if the server name is not yet known). On success it will look up the user's full name and email address (based on his Exchange DN).

The possible values for `result` are:

`E2K_AUTOCONFIG_OK` | Success
`E2K_AUTOCONFIG_CANT_RESOLVE` | Could not determine GC server
`E2K_AUTOCONFIG_NO_MAILBOX` | Could not find information for the user
`E2K_AUTOCONFIG_AUTH_ERROR_TRY_DOMAIN` | Plaintext password authentication failed: need to specify NT domain
`E2K_AUTOCONFIG_CANCELLED` | Operation was cancelled
`E2K_AUTOCONFIG_FAILED` | Other error

`ac` : | an autoconfig context
`op` : |
Returns : | an E2kAutoconfigResult.

### e2k_autoconfig_lookup_option ()

    const char* e2k_autoconfig_lookup_option    (const char *option);

Looks up an autoconfiguration hint in the config file (if present)

`option` : | option name to look up
Returns : | the string value of the option, or `NULL` if it is unset.

## See Also

E2kContext, E2kGlobalCatalog