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

/*
 *    Lorica IDL file. 
 *    Copyright (C) 2007-2008 OMC Denmark ApS.
 *
 *    This program is free software; you can redistribute it and/or modify
 *    it under the terms of the GNU General Public License as published by
 *    the Free Software Foundation; either version 2 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 General Public License for more details.
 *
 *    You should have received a copy of the GNU General Public License
 *    along with this program; if not, write to the Free Software
 *    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
 */

#include "ServerAgent.idl"

module Lorica
{

	// Interface used by applications within a firewalled enclave. The
	// ReferenceMapper converts supplied object references into proxy managed
	// references that may be exported by servers or used by internal clients.

	interface ReferenceMapper
	{
		exception SecurityNotAvailable { };

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

		// The default ports used by the Lorica process to listen for 
		// connections coming from inside the firewall enclave. This 
		// includes connections used to register new object references 
		// for mapping, or for clients tunneling new connections 
		// through the proxy. 
		const unsigned short lorica_in_port = 4080;
		const unsigned short lorica_in_port_sec = 4081;

		// The default ports used by the Lorica process to listen for 
		// connections coming from outside the protected firewall enclave.
		const unsigned short lorica_out_port = 4082;
		const unsigned short lorica_out_port_sec = 4083;

		// Used for corbaloc bootstrapping of the ReferenceMapper
		const string IOR_TABLE_KEY = "LORICA_REFERENCE_MAPPER";


		// Map a reference that a server would publish to clients outside the
		// enclave. The arguments are:
		//
		//   orig:          The original object reference
		//
		//   corbaloc_name: If not "", use this name to create a binding in
		//                  the proxy's IOR table.
		//
		//   agent:         The server agent used to receive messages related
		//                  to the reference being mapped.
		//
		Object as_server(in Object orig,
				 in string corbaloc_name,
				 in Lorica::ServerAgent agent);

		// The same as "as_server" however in this form, the mapped reference
		// will require secure access. If security is not available an execption
		// is raised.
		Object as_secure_server(in Object orig,
					in string corbaloc_name,
					in Lorica::ServerAgent agent)
			raises (SecurityNotAvailable);

		// Map a reference that a client inside an enclave would use to reach
		// servers on the outside. This is necessary only when the interface
		// associated with the supplied reference may be used to pass object
		// references.
		Object as_client(in Object orig);

		// As as_client() but a valid CORBALOC string and the the IFR ID 
		// is explicitly given. This is useful as an object created from 
		// a corbaloc string using string_to_object() wouldn't carry any 
		// IFR ID and would therefore not be mappable by Lorica.
		//
		// An example of a valid IFR ID is:
		//
		//         IDL:test.lorica/Test/Hello:1.0
		//
		Object as_client_with_corbaloc(in string corbaloc,
					       in string interface_repository_id);

		// Remove a previously mapped server reference. This will unbind the
		// reference from the IOR table, if previously bound. This should
		// probably generate an error if the mapped reference is not known.
		void remove_server(in Object mapped);

		// Remove a previously mapped client reference. Client references are
		// counted, as many clients may wish to communicate with the same server.
		// This should probably return an error if the mapped reference is not
		// known.
		void remove_client(in Object mapped);

		// Returns true if the proxy is capable of supporting secure invocations.
		// This status depends on the configuration of the proxy. If SSLIOP is
		// not installed, then a current won't be available and thus no security
		// support is available.
		boolean supports_security();
	};
};
