linking II

[lacage email enst fr (Mathieu Lacage)]

Thanks to Maceij Comments, here is a 2nd version.

LinkServer and LinkClient were created after understanding the true
use of QI and why unimplemented methods suck.
They add some functionality: the "Document Dialog Links" like in OLE
and OpenDoc.

Mathieu



module Bonobo {

	/**
	 * This interface is inherited by the MonikerFactory
	 * object and by the LinkServer Object.
	 */
	interface DisplayNameParser : Unknown {
		/**
		 * parse_display_name:
		 *
		 * Returns a moniker from the string representation
		 * This is probably one of the most important method 
		 * here...
		 */
		Moniker parse_display_name (in string display_name,
					    out short display_name_bytes_parsed);
	}

	/**
	 * This interface must implemented by the embeddables 
	 * which can be embedded as links and which want to 
	 * support the Complex Linking stuff.
	 */
	interface LinkServer : DisplayNameParser {
		
		/**
		 * get_object:
		 * @item_name: Item name to bind to
		 * @only_if_exists: if TRUE, only bind if this object currently exists
		 * otherwise, it will try to create the server for it.
		 */
		Unknown get_object (in string item_name, in boolean only_if_exists)
			raises (SyntaxError, NotFound);
	
	}


	/**
	 * This interface should be implemented by containers 
	 * which can embedd linked embeddables.
	 * It would allow us to create a "Document Links Dialog"
	 * like in OLE and OpenDoc.
	 * Parts of this interface were shamelessly stolen from
	 * the BindContext interface of bonobo-moniker.idl. 
	 */
	interface LinkClient : Unknown {
	
		/**
		 * register_moniker:
		 *
		 * Keeps track of the moniker.
		 * The Moniker is ref()ed 
		 */
		void register_moniker (in Moniker moniker);
		
		/**
		 * drop_one_moniker:
		 * @moniker: Forgets about the moniker
		 */
		void drop_one_moniker (in Moniker moniker);

		/**
		 * drop_moniker:
		 * Drops all the monikers
		 */
		void drop_objects ();


		typedef sequence<Moniker> MonikerList;
		/**
		 * returns the list of all the links which
		 * the container holds
		 */
		MonikerList get_links (void);
	}


	


	/**
	 * The base Factory for all monikers.
	 * There should be ONE instance of this
	 * object on the system.
	 */
	interface MonikerFactory : ParseDisplayName {
		/**
		 * will create an Item Moniker and initializes it with its left moniker
		 * and the part of the path it is supposed to represent.
		 * Typically, this method would be called with a path set to: "Sheet1" or
		 * "A2:A5".
		 * a NULL left parameter is valid provided ItemMoniker::set_left_moniker
		 * is called after.
		 */
		Moniker create_item_moniker (in Moniker left, in string path);

		/**
		 * will create a file moniker and initializes it with the path it 
		 * represents.
		 * Typically, it would be called with the path set to:
		 * "file:///home/mathieu/bidule.gnumeric.
		 */
		Moniker create_file_moniker (in string path);

	}

	/**
	 * This interface is created by calling 
	 * one of the MonikerFactory interface methods.
	 */
	interface Moniker : Object {
		exception InterfaceNotFound {
			string interface_name;
		};
	       
		exception MissingInterface {
			string interface_name;
			string object_name;
		};

		/**
		 * bind_to_object:
		 * @requested_interface: which interface we want in the end
		 *
		 * Binds a moniker. Once the service has been registered, it
		 * will attempt to get the @requester_interface
		 */
		Object bind_to_object (in string requested_interface)
			raises (InterfaceNotFound, TimeOut, MissingInterface);

		/**
		 * get_relative_moniker:
		 */
		Moniker get_relative_moniker (void);

		/**
		 * get_absolute_moniker:
		 */
		Moniker get_absolute_moniker (void);

		/**
		 * get_display_name:
		 * 
		 * Returns a representation of the Moniker
		 */
		string get_display_name (void);					    
	};

	interface FileMoniker : Moniker {
	}

	interface ItemMoniker : Moniker {
		boolean set_left_moniker (in Moniker left);
	}
};