Copy of aRts for Trinity modifications

git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/dependencies/arts@1070145 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 715 insertions, 0 deletions

diff --git a/mcop/core.idl b/mcop/core.idl
new file mode 100644
index 0000000..33081e7
--- /dev/null
+++ b/mcop/core.idl
@@ -0,0 +1,715 @@
+/*
+
+    Copyright (C) 1999-2000 Stefan Westerfeld
+                       stefan@space.twc.de
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Library General Public
+    License as published by the Free Software Foundation; either
+    version 2 of the License, or (at your option) any later version.
+  
+    This library 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
+    Library General Public License for more details.
+   
+    You should have received a copy of the GNU Library General Public License
+    along with this library; see the file COPYING.LIB.  If not, write to
+    the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+    Boston, MA 02111-1307, USA.
+
+*/
+
+module Arts {
+// MCOP protocol
+
+enum HeaderMagic { MCOP_MAGIC = 0x4d434f50 }; /* gets marshalled as "MCOP" */
+											  /* decimal 1296256848 */                                                                                    
+enum MessageType {
+ mcopMessageInvalid		= 0,				  /* never send this */
+ mcopServerHello		= 1,
+ mcopClientHello		= 2,
+ mcopAuthAccept			= 3,
+ mcopInvocation			= 4,
+ mcopReturn				= 5,
+ mcopOnewayInvocation   = 6
+};
+
+/**
+ * This type is sent as header of each MCOP message.
+ */
+struct Header {
+	/**
+	 * the value 0x504f434d, which is marshalled as MCOP
+	 */
+    HeaderMagic magic;
+    long messageLength;
+    MessageType messageType;
+};
+
+/**
+ * This is sent as start of each normal (twoway) invocation
+ */
+struct Invocation {
+	/**
+	 * The ID of the object receiving the request
+	 */
+    long objectID;
+	/**
+	 * The ID of the method that is to be invoked
+	 */
+    long methodID;
+	/**
+	 * A unique number of the request (needed to send the return code back)
+	 */
+    long requestID;
+};
+
+/**
+ * This is sent as start of each oneway invocation
+ */
+struct OnewayInvocation {
+	/**
+	 * The ID of the object receiving the request
+	 */
+    long objectID;
+	/**
+	 * The ID of the method that is to be invoked
+	 */
+    long methodID;
+};
+
+/**
+ * Body of the mcopServerHello MCOP message
+ */
+struct ServerHello {
+	string mcopVersion;
+	string serverID;
+	sequence<string> authProtocols;
+	string authSeed;
+};
+
+/**
+ * Body of the mcopClientHello MCOP message
+ */
+struct ClientHello {
+	string serverID;
+	string authProtocol;
+	string authData;
+};
+
+/**
+ * The message you get when you connect a MCOP server. The MCOP server can
+ * send you some useful information here. Usually, it will send you
+ *
+ *   GlobalComm=<object reference of a global comm interface>
+ *   InterfaceRepo=<object reference of an interface repository>
+ *
+ * But as this is called "hints" it doesn't necessarily need to happen.
+ */
+struct AuthAccept {
+	sequence<string> hints;
+};
+
+/**
+ * An object reference
+ */
+struct ObjectReference {
+	/**
+	 * A unique ID for the server the object is located on, (a server ID may
+	 * i.e. be composed of start time, hostname, and pid)
+	 */
+	string serverID;
+
+	/**
+	 * The number of the object under that server
+	 */
+	long objectID;
+
+	/**
+	 * where the server holding object can be reached
+	 */
+	sequence<string> urls;
+};
+
+// Interface definitions
+
+/**
+ * The definition of a parameter of a method
+ *
+ * hints is reserved for future extensions, such as default, min and maxvalues
+ */
+struct ParamDef {
+	string type;
+	string name;
+	sequence<string> hints;
+};
+
+/**
+ * Twoway methods are such where the calling process does a call and is
+ * suspended until some result (maybe even a void result) gets back.
+ *
+ * Oneway methods are one shot and forget methods: you send the invocation,
+ * and continue. Maybe it will be received, maybe executed later. You will
+ * never hear the result.
+ */
+enum MethodType {
+	methodOneway = 1,
+	methodTwoway = 2
+};
+
+/**
+ * The definition of a method.
+ *
+ * hints is reserved for future extensions, such as default, min and maxvalues
+ */
+struct MethodDef {
+	string     name;
+	string     type;
+	MethodType flags;
+
+	sequence<ParamDef> signature;
+	sequence<string>   hints;
+};
+
+/**
+ * an attribute
+ *
+ * flags should contain things like
+ *
+ * @li attribute is readonly/writeonly/readwrite
+ * @li attribute is incoming/outgoing stream
+ * @li if it's a stream, it also should contain the information whether it is
+ *     asynchronous or synchronous
+ * @li NB20000320: see InterfaceDef for the meaning of streamDefault
+ */
+enum AttributeType {
+  streamIn    = 1,
+  streamOut   = 2,
+  streamMulti = 4,
+  attributeStream    = 8,
+  attributeAttribute = 16,
+  streamAsync = 32,
+  streamDefault = 64
+};
+
+/**
+ * The definition of an attribute and/or stream
+ *
+ * hints is reserved for future extensions, such as default, min and maxvalues
+ */
+struct AttributeDef {
+	string  name;
+	string  type;
+	AttributeType flags;
+	sequence<string>   hints;
+};
+
+/**
+ * InterfaceDef - interface definition structure
+ *
+ * defines what methods/attributes a particular interface supports: these
+ * do not contain the methods/attributes of inherited interfaces.
+ *
+ * inheritedInterfaces only contains the names of Interfaces that this one
+ * inherits in exactly one step. So to see if interface XYZ is inherited
+ * from ABC, you need to check the "inheritedInterfaces" of XYZ, and their
+ * "inheritedInterfaces" and their "inheritedInterfaces" and so on.
+ *
+ * - NB20000320: defaultPorts allows to connect to those port by default if
+ *               connection is made in the corresponding direction.
+ *               It cannot be just an attribute flag because of the syntax
+ *               on a separate line.
+ *
+ * hints is reserved for future extensions, such as default, min and maxvalues
+ */
+
+struct InterfaceDef {
+	string name;
+
+	sequence<string> inheritedInterfaces;
+	sequence<MethodDef> methods;
+	sequence<AttributeDef> attributes;
+	
+	sequence<string> defaultPorts;
+	sequence<string> hints;
+};
+
+// Type definitions (struct's and such)
+
+/**
+ * One component of a struct
+ *
+ * hints is reserved for future extensions, such as default, min and maxvalues
+ */
+struct TypeComponent {
+	string type;
+	string name;
+	sequence<string> hints;
+};
+
+/**
+ * The definition of a struct
+ *
+ * hints is reserved for future extensions, such as default, min and maxvalues
+ */
+struct TypeDef {
+	string name;
+
+	sequence<TypeComponent> contents;
+	sequence<string> hints;
+};
+
+/**
+ * One item of an enum value
+ *
+ * hints is reserved for future extensions, such as default, min and maxvalues
+ */
+struct EnumComponent {
+	string name;
+
+	long value;
+	sequence<string> hints;
+};
+
+/**
+ * The definition of an enum
+ *
+ * hints is reserved for future extensions, such as default, min and maxvalues
+ */
+struct EnumDef {
+	/**
+	 * name if the enum, "_anonymous_" for anonymous enum - of course, when
+	 * using namespaces, this can also lead to things like "Arts::_anonymous_",
+	 * which would mean an anonymous enum in the Arts namespace
+	 */
+	string name;	
+
+	sequence<EnumComponent> contents;
+	sequence<string> hints;
+};
+
+/**
+ * The contents of an idl file
+ *
+ * hints is reserved for future extensions, such as default, min and maxvalues
+ */
+struct ModuleDef {
+	string moduleName;
+
+	sequence<EnumDef> enums;
+	sequence<TypeDef> types;
+	sequence<InterfaceDef> interfaces;
+	sequence<string> hints;
+};
+
+/**
+ * The interface repository
+ */
+interface InterfaceRepo {
+	/**
+	 * inserts the contents of a module into the interface repository
+	 *
+	 * @returns an ID which can be used to remove the entry again
+	 */
+	long insertModule(ModuleDef newModule);
+
+	/**
+	 * removes the contents of a module from the interface repository
+	 */
+	void removeModule(long moduleID);
+
+	/**
+	 * queries the definition of an interface
+	 */
+	InterfaceDef queryInterface(string name);
+
+	/**
+	 * queries the definition of a type
+	 */
+	TypeDef queryType(string name);
+
+	/**
+	 * queries the definition of an enum value
+	 */
+	EnumDef queryEnum(string name);
+
+	/**
+	 * queries all interfaces that inherit a given interface
+	 */
+	sequence<string> queryChildren(string name);
+
+	/**
+	 * queries all interfaces
+	 */
+	sequence<string> queryInterfaces();
+
+	/**
+	 * queries all types
+	 */
+	sequence<string> queryTypes();
+
+	/**
+	 * queries all enums
+	 */
+	sequence<string> queryEnums();
+};
+
+enum TypeIdentification {
+	tiUnknown = 0,
+	tiVoid = 1,
+	tiLong = 2,
+	tiByte = 3,
+	tiString = 4,
+	tiBoolean = 5,
+	tiFloat = 6,
+	tiEnum = 128,
+	tiType = 129,
+	tiInterface = 130
+};
+
+interface InterfaceRepoV2 : InterfaceRepo {
+	/**
+	 * identifies whether a type is a primitive, enum, type or interface,
+	 * or not known at all
+	 */
+	TypeIdentification identifyType(string name);
+};
+
+/**
+ * Flow System interface
+ */
+
+/**
+ * Internal use: implement distributed asynchronous streams.
+ *
+ * The FlowSystemSender object transmits the packets that should be sent
+ * over the stream via _allocCustomMessage (Object_base).
+ */
+interface FlowSystemSender {
+	/**
+	 * This method is invoked whenever the receiver has finished processing
+	 * a packet of the stream
+	 */
+	oneway void processed();
+
+	/**
+	 * This method is for telling the local FlowSystemSender to break the
+	 * connection to the remote Receiver (it's not intended to be called
+	 * remotely)
+	 */
+	void disconnect();
+};
+
+/**
+ * Internal use: implement distributed asynchronous streams.
+ *
+ * The FlowSystemReceiver object receives and extracts the packets sent by
+ * the sender object and injects them in the notification system again.
+ */
+interface FlowSystemReceiver {
+	/**
+	 * The custom message ID which should be used to send the stream packets
+	 */
+	readonly attribute long receiveHandlerID;
+
+	/**
+	 * This method is for telling the local FlowSystemReceiver to break the
+	 * connection to the remote Sender (it's not intended to be called
+	 * remotely)
+	 */
+	void disconnect();
+};
+
+/**
+ * A flow system.
+ *
+ * Flow systems handle the streaming between MCOP objects. As this streaming
+ * is network transparent (at least for asynchronous streams) they have this
+ * remote interface.
+ */
+interface FlowSystem {
+	/**
+	 * This starts a scheduling node
+	 *
+	 * Don't use this manually. Use object->_node()->connect(...) instead.
+	 */
+	void startObject(object node);
+
+	/**
+	 * This stops a scheduling node
+	 *
+	 * Don't use this manually. Use object->_node()->connect(...) instead.
+	 */
+	void stopObject(object node);
+
+	/**
+	 * This connects two objects, maybe even remote
+	 *
+	 * it is important that
+	 *  - sourceObject/sourcePort points to the node the signal flow is
+	 *    coming from
+	 *  - destObject/destPort points to the node/port the signal flow is
+	 *    going to
+	 *
+	 * Don't use this manually. Use object->_node()->connect(...) instead.
+	 */
+	void connectObject(object sourceObject, string sourcePort,
+						object destObject, string destPort);
+
+	/**
+	 * This disconnects two objects, maybe even remote
+	 *
+	 * it is important that
+	 * @li sourceObject/sourcePort points to the node the signal flow is
+	 *     coming from
+	 * @li destObject/destPort points to the node/port the signal flow is
+	 *     going to
+	 *
+	 * Don't use this manually. Use object->_node()->connect(...) instead.
+	 */
+	void disconnectObject(object sourceObject, string sourcePort,
+		 					object destObject, string destPort);
+
+	/**
+	 * queries the stream flags - returns 0 when such a stream isn't
+	 * present
+	 */
+	AttributeType queryFlags(object node, string port);
+
+	/**
+	 * directly sets an audio port to a fixed value
+	 */
+	void setFloatValue(object node, string port, float value);
+
+	/**
+	 * network transparent connections
+	 */
+	FlowSystemReceiver createReceiver(object destObject, string destPort,
+												FlowSystemSender sender);
+};
+
+/**
+ * A global communication space used to obtain initial object references
+ *
+ * MCOP needs a way to connect to initial (global) object references. This
+ * is done by these global communication spaces.
+ */
+interface GlobalComm {
+	/**
+	 * puts a variable/value pair into the global communication
+	 * space - it will not change the value of the variable if it is
+	 * already present. Returns true if success, false if the variable
+	 * was already there.
+	 */
+	boolean put(string variable, string value);
+
+	/**
+	 * gets the value of a variable out of the global communication
+	 * space - it returns an empty string when the variable isn't there
+	 */
+	string get(string variable);
+
+	/**
+	 * removes a variable from the global communication space
+	 */
+	void erase(string variable);
+};
+
+/**
+ * global communication based on the /tmp/mcop-<username> directory
+ */
+interface TmpGlobalComm : GlobalComm {
+};
+
+/*
+ * Trading interfaces follow - trading is used to locate objects with certain
+ * properties. This is especially recommended, if you want to allow that after
+ * your code has been released, people can extend it, without changing your
+ * code, by adding new components.
+ */
+
+/**
+ * TraderOffer - this contains an offer of an object (which is usually returned
+ * as result of a query.
+ */
+interface TraderOffer {
+	/**
+	 * You can use this interface name to create one of the objects that
+	 * fulfill your query
+	 */
+	readonly attribute string interfaceName;
+
+	/**
+	 * This allows you to query additional information about the offer,
+	 * such as the author of the plugin, the name of the library that
+	 * implements it (if it is a library) or similar.
+	 *
+	 * Since some properties support having multiple values, this always
+	 * returns a sequence<string>, which may be empty if the property isn't
+	 * present at all.
+	 */
+	sequence<string> getProperty(string name);
+};
+
+/**
+ * TraderQuery - this is a query against the trader. The idea is simple: you
+ * say what you need, and the trader offers you components that do what you
+ * want.
+ */
+interface TraderQuery {
+	/**
+	 * This restricts the query to only objects which support a "property"
+	 * with the value "value". For instance, you could say
+	 *
+	 *   aquery.supports("Interface","Arts::PlayObject");
+     *
+	 * to restrict the matching objects to only those that support the
+	 * interface Arts::PlayObject
+	 */
+	void supports(string property, string value);
+
+	/**
+	 * This performs the query, and returns a set of results
+	 */
+	sequence<TraderOffer> query();
+};
+
+/**
+ * Arts::Object is the base object that every interface implicitely inherits
+ *
+ * it is also the source for generation of the Object_stub stuff
+ * (use mcopidl -e Arts::Object to avoid code generation for this interface)
+ */
+interface Object {
+	/**
+	 * access to the flow system this object is running in
+	 */
+	readonly attribute FlowSystem _flowSystem;
+
+	/**  <interface description>
+	 * returns the ID for methodinvocations to this specific method
+	 * methodID = 0  =>  _lookupMethod (always)
+	 */
+	long _lookupMethod(MethodDef methodDef);
+
+	/**  <interface description>
+	 * returns the name of the interface
+	 * methodID = 1  =>  _interfaceName (always)
+	 */
+	string _interfaceName();
+
+	/**  <interface description>
+	 * returns the interface description to a given interface
+	 * methodID = 2  =>  _queryInterface (always)
+	 */
+	InterfaceDef _queryInterface(string name);
+
+	/**  <interface description>
+	 * returns the type description to a given type
+	 * methodID = 3  =>  _queryType (always)
+	 */
+	TypeDef _queryType(string name);
+
+	/**  <interface description>
+	 * returns the enum description to a given enum
+	 * methodID = 4  =>  _queryEnum (always)
+	 */
+	EnumDef _queryEnum(string name);
+
+	/**
+	 * stringifies the object to one string
+	 */
+	string _toString();
+	
+	/**  <interface description>
+	 * Run-time type compatibility check
+	 */
+	boolean _isCompatibleWith(string interfacename);
+
+	/**  <reference counting>
+	 * prepares object for remote transmission (so that it will not be freed
+	 * soon, since the remote receiver expects it to be there after receiving
+	 * it)
+	 */
+	void _copyRemote();
+
+	/**  <reference counting>
+	 * declares that the object is used remotely now (do that only after
+	 * _copyRemote)
+	 */
+	void _useRemote();
+
+	/**  <reference counting>
+	 * declares that the object is no longer used remotely
+	 */
+	void _releaseRemote();
+
+	/**  <aggregation>
+	 * add a child object - this makes this object hold a strong reference to
+	 * the child object (i.e. the child object will stay alive at least as
+	 * long as the object does)
+	 *
+	 * if there is already a child with the same name, a postfix will be added
+	 * automatically (i.e. if you add an object named "view" twice, the first
+	 * will be called view, the second view1).
+	 */
+	string _addChild(object child, string name);
+
+	/**  <aggregation>
+	 * removes a child object 
+	 */
+	boolean _removeChild(string name);
+
+	/**  <aggregation>
+	 * gets a child object
+	 */
+	object _getChild(string name);
+
+	/**  <aggregation>
+	 * lists all children
+	 */
+	sequence<string> _queryChildren();
+};
+
+/**
+ * a simple struct which can hold any other type
+ */
+struct Any {
+	string type;
+	sequence<byte> value;
+};
+
+/**
+ * TraderEntries as produced by the loader
+ */
+
+struct TraderEntry {
+	string interfaceName;
+	sequence<string> lines;
+};
+
+/**
+ * loader to load plugins (implemented in some language/binary format)
+ */
+interface Loader {
+	object loadObject(TraderOffer offer);
+
+	/*
+	 * this is used for the type system to cache your trader data and
+	 * module data as long as it stays unchanged
+	 */
+	readonly attribute string dataVersion;
+
+	/*
+	 * the trader entries of the components that can be loaded
+	 */
+	readonly attribute sequence<TraderEntry> traderEntries;
+
+	/*
+	 * the interface information of the components that can be loaded
+	 */
+	readonly attribute sequence<ModuleDef> modules;
+};
+ 
+};