/* -*- Mode: IDL; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */

/*
 *  Copyright (C) 2008 OMC Denmark ApS.
 *
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU Affero General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Affero General Public License for more details.
 *
 *  You should have received a copy of the GNU Affero General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef F2T_BRUTUS_LOGON_DEF
#define F2T_BRUTUS_LOGON_DEF

#pragma prefix "omc.brutus"

#include "IMAPISession.idl"
#include "BrutusCheck.idl"

module BRUTUS {

	/* 
	 * The GetVersion(), GetPublicKey() or Logon() methods are the
	 * first methods being called by any client. They must therefore 
	 * be able to potentially forward the request to another server. 
	 * This task is handled by a ServerRequestInterceptor.
	 */
        interface BrutusLogOn {

		// See:
		//
		//     http://iana.org/assignments/port-numbers
		//
		// for the IANA registered port.

		// The default port used by Brutus Server to listen for connections.
		const unsigned short BRUTUS_DEFAULT_PORT = 2003;

		// Registered name in the IOR table
		const string IOR_TABLE_KEY = "BRUTUS_LOGON";

		// Version of Brutus Server
		struct BrutusVersion {
			unsigned short major;
			unsigned short minor;
			unsigned short micro;
			unsigned short release_tag;
		};		
		void GetVersion(out BrutusVersion version);
		
                // Wrapping MAPILogonEx() and LogonUser()
		//
		// No exceptions are explicitly thrown but the following 
		// BRESULTs are indictive of significant client-side or server 
		// problems:
		//
		//    *) BRUTUS_LIFELINE_TIMEOUT.
		//          A CORBA::TIMEOUT exception was caught when trying to 
		//          issue BrutusCheck::ping() to validate the lifeline 
		//          object reference. This is indicative of network or DNS
		//          problems.
		//
		//    *) BRUTUS_EXCEPTION_FROM_CLIENT
		//          A CORBA::Exception exception was caught when trying to 
		//          issue BrutusCheck::ping() to validate the lifeline 
		//          object reference. This is indicative of a client-side
		//          bug in the BrutusCheck servant.
		//
		//    *) BRUTUS_INTERNAL_ERROR
		//          An unknown C++ exception was caught when trying to 
		//          issue BrutusCheck::ping() to validate the lifeline 
		//          object reference. This is indicative of a bug in the 
		//          Brutus server. 
		//          Please report this to <bugs@omesc.com>.
		//
		// Please refer to the comments regarding CreateProfile() for 
		// extended error code documentation.
		//
		// A client application should not retry the login attempt when 
		// any of the above return values are encountered unless steps has 
		// been taken to correct the error condition, whatever it may be.
		//
		// A MAPI profile will automatically be created if a profile 
		// named MAPIProfileName isn't found. You should use this profile
		// henceforth to conserve resources on the Brutus server. 
		//
                BRESULT Logon(in BrutusCheck Lifeline,       // To check for alive client
			      in string MAPIProfileName,     // MAPI Profile name
			      in string MAPIProfilePassword, // MAPI Profile password
			      in string WindowsUserName,     // NT Domain user name
			      in string WindowsDomainName,   // NT Domain name - This must be the empty string if WindowsUserName is in UPN format
			      in string WindowsUserPassword, // NT Domain user password
			      in string MailboxName,         // Name of mailbox on server
			      in string ServerName,          // Hostname of server
			      in BDEFINE LogonFlags,         // Flags given to MAPILogonEx()
			      in BDEFINE ProfileFlags,       // Flags given to IProfAdmin::CreateProfile()
			      in SERVER_TYPE ServerType,     // Exchange or Domino 
			      out unsigned long InstanceID,  // You must use this in IMAPISession::Destroy()
			      out IMAPISession Session);     // non-NIL if logon successfull
        };

}; // End of module BRUTUS


#endif
