e2k-autoconfig

e2k-autoconfig — Account autoconfiguration

Synopsis




enum        E2kExchangeVersion;
struct      E2kAutoconfig;
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);
E2kAutoconfigResult e2k_autoconfig_check_global_catalog
                                            (E2kAutoconfig *ac,
                                             E2kOperation *op);

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

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_UNKNOWNThe server seems to be running Exchange 2000 or later, but we couldn’t figure out what version.
E2K_EXCHANGE_2000The server is running Exchange 2000
E2K_EXCHANGE_2003The server is running Exchange 2003
E2K_EXCHANGE_FUTUREThe server seems to be running some version of Exchange newer than Exchange 2003.

struct E2kAutoconfig

struct E2kAutoconfig {

	/* 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;
};

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 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_OKSuccess
E2K_AUTOCONFIG_REDIRECTThe server issued a valid-looking redirect. ac->owa_uri has been updated and the caller should try again.
E2K_AUTOCONFIG_TRY_SSLThe server requires SSL. ac->owa_uri has been updated and the caller should try again.
E2K_AUTOCONFIG_AUTH_ERRORGeneric authentication failure. Probably password incorrect
E2K_AUTOCONFIG_AUTH_ERROR_TRY_DOMAINAuthentication failed. Including an NT domain with the username (or using NTLM) may fix the problem.
E2K_AUTOCONFIG_AUTH_ERROR_TRY_BASICCaller requested NTLM auth, but only Basic was available.
E2K_AUTOCONFIG_AUTH_ERROR_TRY_NTLMCaller requested Basic auth, but only NTLM was available.
E2K_AUTOCONFIG_EXCHANGE_5_5Server appears to be Exchange 5.5.
E2K_AUTOCONFIG_NOT_EXCHANGEServer does not appear to be any version of Exchange
E2K_AUTOCONFIG_NO_OWAServer may be Exchange 2000, but OWA is not present at the given URL.
E2K_AUTOCONFIG_NO_MAILBOXOWA claims the user has no mailbox.
E2K_AUTOCONFIG_NETWORK_ERRORA network error occurred. (usually could not connect or could not resolve hostname).
E2K_AUTOCONFIG_FAILEDOther 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_REDIRECTThe URL returned in first redirect returned another redirect, which was not followed.
E2K_AUTOCONFIG_CANT_BPROPFINDThe server does not allow BPROPFIND due to IIS Lockdown configuration
E2K_AUTOCONFIG_TRY_SSLNot used; always handled internally by e2k_autoconfig_check_exchange()
ac :an autoconfiguration context
op :
Returns :an E2kAutoconfigResult

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_OKSuccess
E2K_AUTOCONFIG_NETWORK_ERRORCould not determine GC server
E2K_AUTOCONFIG_NO_MAILBOXCould not find information for the user
E2K_AUTOCONFIG_FAILEDOther error
ac :an autoconfig context
op :
Returns :an E2kAutoconfigResult.