Calendar Express 1.0 Authentication SDK
----------------------------------------


o The Basics

The Calendar Express Authentication SDK consists of 
a DLL/shared-object which exports six functions. These
functions allow you to integrate Calendar 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 CEXP_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 ohter 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 users. 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.

   The value of the pszAdminUser parameter should be a userid
   value that is defined in the "service.http.admins".

int CEXP_GenerateLoginURL(
    char *pszUser, 
    char *pszClientAddress, 
    char *pszCalendarHost, 
    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.
   pszCalendarHost is a null terminated string
   containing the hostname or ip-address of the
   users calendar server. If the third parameter is
   NULL, the LDAP server (from CEXP_Init() ) will
   be searched to determine this host.
   Otherwise, the calendar 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 CEXP_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* CEXP_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 CEXP_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 webcalendar 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 CEXP_GenerateLoginURL call.

