summaryrefslogtreecommitdiffstats
path: root/mcop/core.idl
diff options
context:
space:
mode:
Diffstat (limited to 'mcop/core.idl')
-rw-r--r--mcop/core.idl715
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;
+};
+
+};
generated by cgit v1.2.3 (git 2.25.1) at 2024-05-01 01:43:01 +0000