/*
 * bonobo-moniker.idl: Implements an object naming and resolution interface
 *
 * Copyright (C) 2000  Helix Code, Inc.
 *
 * Authors:
 *	Michael Meeks (michael@helixcode.com)
 *	Ettore Perazzoli (ettore@helixcode.com)
 */

#ifndef BONOBO_MONIKER_IDL
#define BONOBO_MONIKER_IDL

#include "Bonobo_Unknown.idl"

module Bonobo {

	typedef long ResolveFlag;
	const ResolveFlag MONIKER_ALLOW_USER_INTERACTION = 1;

	struct ResolveOptions {
		ResolveFlag  flags;
		long         timeout; /* in ms */
	};

	interface Moniker : Bonobo::Unknown {
		exception InterfaceNotFound {};
		exception TimeOut           {};
		exception InvalidSyntax     {};
		exception UnknownPrefix     {};

		/**
		 * parent:
		 *
		 * A moniker can be composed of a chain of monikers
		 * which can be collectively resolved, displayed etc.
		 */
		attribute Moniker parent;

		/**
		 * getDisplayName:
		 * 
		 * Returns a human readable representation of the Moniker
		 */
		string  getDisplayName ()
			raises (InvalidSyntax);

		/**
		 * parseDisplayName:
		 * @parent: the parent of this moniker
		 * @name: the display name fragment to parse
		 *
		 * Generates a moniker from the string representation,
		 * it builds a list returning the root node in a
		 * similar way to g_list_append ();
		 */
		Moniker parseDisplayName (in Moniker parent, in string name)
			raises (InvalidSyntax, UnknownPrefix);
		
		/**
		 * resolve:
		 * @options: resolution options
		 * @inferface: what interface we want from the result
		 *
		 * Resolves a moniker; this returns a reference to the
		 * activated object described by the moniker
		 */
		Unknown resolve            (in ResolveOptions options,
					    in string         requestedInterface)
			raises (InterfaceNotFound, TimeOut);

		/**
		 * equal:
		 * @displayName: the display name of another moniker
		 *
		 *  Compares the full moniker with this @displayName,
		 * returns 0 if not equal, else the number of chars swallowed
		 * by the compare.
		 */
		long    equal              (in string         displayName);
	};

        interface MonikerExtender : Bonobo::Unknown {
		/**
		 * resolve:
		 * @m: the moniker we are about to extend
		 * @options: resolve options
		 * @display_name: the display name of 'm' by itself eg. 'file:/tmp/a'
		 * @requested_interface: the interface we want to get back
		 *
		 *  The interface for a later extension to a moniker that allows it
		 * to be resolved against new and exotic interfaces.
		 *
		 * Returns: The interface requested, or CORBA_OBJECT_NIL.
		 */
                Unknown resolve (in Moniker        m,
				 in ResolveOptions options,
                                 in string         displayName,
                                 in string         requestedInterface)
			raises (Moniker::InterfaceNotFound, Moniker::TimeOut);
        };
};

#endif /* BONOBO_MONIKER_IDL */
