Messenger Express 5.1 Authentication SDK
----------------------------------------


o The Basics

The Messenger Express Authentication SDK consists of 
a DLL/shared-object which exports six functions. These
functions allow you to integrate Messenger Express into
some other authentication system.


o Building

To integrate the authSDK into your existing code, simply
include the expapi.h header file in the calling code and
link with the DLL/shared object. On some platforms you
may also be required to link with other system libraries
which the SDK requires.

A sample makefile is also included with the package. 


o The API

int EXP_Init(
    char *pszLdapHost, 
    char *pszLdapMatchAttrib, 
    char *pszLdapDN, 
    unsigned int iLdapPort, 
    char *pszLdapBindUser, 
    char *pszLdapBindPass,
    char *pszAdminUser,
    char *pszAdminPassword);

   This function initializes the SDK
   configuration information needed when
   calling other functions. pszLdapHost is a null
   terminated string containing the hostname or
   ip-address of the ldap server to search for
   users in. pszLdapMatchAttrib is a null
   terminated string specifying which LDAP
   attribute the pszUser parameter should be
   matched against when searching LDAP. The
   default is uid. pszLdapDN is a null
   terminated string specifying the DN to use
   when searching for users. iLdapPort is an
   integer specifying the port number the LDAP
   server is listening on. The pazLdapBindUser
   and pszLdapBindPass are strings specifying
   the bind DN and password for the directory
   server. If NULL, the SDK will attempt to bind
   as an anonymous user. pszAdminUser and
   pszAdminPass are ptrs to strings containing
   the "proxy" user name and password to use
   when connection to the messaging server. These
   cannot be NULL.

   The function returns a 0 upon successful
   initialization or a non-zero number
   indicating failure. On failure, errno is set
   to the most appropriate value possible based
   on what failed (usually a system call). These
   codes map to standard errno values.

   This function should be called only once, prior to
   calling other functions.


int EXP_GenerateLoginURL(
    char *pszUser, 
    char *pszClientAddress, 
    char *pszMailHost, 
    char *pszURL)

   These functions are used to generate a
   session handle for a specific user and
   client-ip address. pszUser is a null
   terminated string containing the user name
   (uid). pszClientAddress is the a string
   representation of the client's ip-address.
   pszMailHost is a null terminated string
   containing the hostname or ip-address of the
   users mail server. If the third parameter is
   NULL, the LDAP server (from EXP_Init() ) will
   be searched to determine this host.
   Otherwise, the mail host specified will be
   used. The fourth parameter is a pointer to a
   buffer which must be allocated by the caller
   for the function to return the URL in. The
   URL will be at most 2048 characters long
   (including terminating NULL). The functions 0
   upon success or a non-zero number on failure.
   On failure, errno is set to the most
   appropriate value possible.

   The string returned by these functions is a
   login URL to be used when connecting to
   messenger express. Authentication
   applications (such as a login CGI) should
   call these functions after successfully
   authenticating the user based on whatever
   their local authentication criteria is. A
   typical CGI would use the resulting string to
   fire a URL or set a cookie on the client via
   HTTP headers or Javascript.


int EXP_Shutdown()

   This function is called to shutdown and
   cleanup any resources used by the SDK.
   Typically it's not necessary to call in a
   simple CGI, but plugins using the API may
   want to reclaim resources and continue
   running.

   The function returns a 0 upon successful
   initialization or a non-zero number
   indicating failure. On failure, errno is set
   to the most appropriate value possible based
   on what failed (usually a system call). These
   codes map to standard errno values.


const char* EXP_GetVersion()

   This function will return a const pointer to
   a null-terminated string identifying the
   version number of the SDK being used. The
   value itself should not be used in any
   dependant manner. In other words, don't code
   anything that expects this string to be in a
   certain format, containt a certain value,
   etc.  It is only available to provide
   information to support about which version
   you are using.

   If no version number information is
   available, the function will return NULL.


void EXP_SetHttpPort(
    int iHttpPort)

   This function can be used to tell the SDK to
   contact a non-standard port when connecting
   to the messaging server's webmail service to
   generate a session. By default the SDK will
   contact the standard HTTP port, 80. This
   function is not thread safe and sets a global
   value. If you want to use it in a thread
   environment, you'll need to lock around this
   call and the EXP_GenerateLoginURL call.



int EXP_EnableHostedDomains(
	const char *pszDefaultDomain,
	const char *pszDCRoot,
	const char *pszDomainSeparators)

   This function enables the iMS 5.x domain hosting extensions.
   When hosted domains are enabled and EXP_GenerateLoginURL needs
   to lookup a user's mailhost, it first looks up the domain in
   the DC tree to determine the base of that domain's user tree,
   then searches the user in this subtree

   Parameters: name of default domain
	root of the dc tree (usually o=internet)
	domain separator in login names (usually "@")
