aRts audio server
Vous ne pouvez pas sélectionner plus de 25 sujets Les noms de sujets doivent commencer par une lettre ou un nombre, peuvent contenir des tirets ('-') et peuvent comporter jusqu'à 35 caractères.

716 lines
17KB

  1. /*
  2. Copyright (C) 1999-2000 Stefan Westerfeld
  3. stefan@space.twc.de
  4. This library is free software; you can redistribute it and/or
  5. modify it under the terms of the GNU Library General Public
  6. License as published by the Free Software Foundation; either
  7. version 2 of the License, or (at your option) any later version.
  8. This library is distributed in the hope that it will be useful,
  9. but WITHOUT ANY WARRANTY; without even the implied warranty of
  10. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  11. Library General Public License for more details.
  12. You should have received a copy of the GNU Library General Public License
  13. along with this library; see the file COPYING.LIB. If not, write to
  14. the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  15. Boston, MA 02110-1301, USA.
  16. */
  17. module Arts {
  18. // MCOP protocol
  19. enum HeaderMagic { MCOP_MAGIC = 0x4d434f50 }; /* gets marshalled as "MCOP" */
  20. /* decimal 1296256848 */
  21. enum MessageType {
  22. mcopMessageInvalid = 0, /* never send this */
  23. mcopServerHello = 1,
  24. mcopClientHello = 2,
  25. mcopAuthAccept = 3,
  26. mcopInvocation = 4,
  27. mcopReturn = 5,
  28. mcopOnewayInvocation = 6
  29. };
  30. /**
  31. * This type is sent as header of each MCOP message.
  32. */
  33. struct Header {
  34. /**
  35. * the value 0x504f434d, which is marshalled as MCOP
  36. */
  37. HeaderMagic magic;
  38. long messageLength;
  39. MessageType messageType;
  40. };
  41. /**
  42. * This is sent as start of each normal (twoway) invocation
  43. */
  44. struct Invocation {
  45. /**
  46. * The ID of the object receiving the request
  47. */
  48. long objectID;
  49. /**
  50. * The ID of the method that is to be invoked
  51. */
  52. long methodID;
  53. /**
  54. * A unique number of the request (needed to send the return code back)
  55. */
  56. long requestID;
  57. };
  58. /**
  59. * This is sent as start of each oneway invocation
  60. */
  61. struct OnewayInvocation {
  62. /**
  63. * The ID of the object receiving the request
  64. */
  65. long objectID;
  66. /**
  67. * The ID of the method that is to be invoked
  68. */
  69. long methodID;
  70. };
  71. /**
  72. * Body of the mcopServerHello MCOP message
  73. */
  74. struct ServerHello {
  75. string mcopVersion;
  76. string serverID;
  77. sequence<string> authProtocols;
  78. string authSeed;
  79. };
  80. /**
  81. * Body of the mcopClientHello MCOP message
  82. */
  83. struct ClientHello {
  84. string serverID;
  85. string authProtocol;
  86. string authData;
  87. };
  88. /**
  89. * The message you get when you connect a MCOP server. The MCOP server can
  90. * send you some useful information here. Usually, it will send you
  91. *
  92. * GlobalComm=<object reference of a global comm interface>
  93. * InterfaceRepo=<object reference of an interface repository>
  94. *
  95. * But as this is called "hints" it doesn't necessarily need to happen.
  96. */
  97. struct AuthAccept {
  98. sequence<string> hints;
  99. };
  100. /**
  101. * An object reference
  102. */
  103. struct ObjectReference {
  104. /**
  105. * A unique ID for the server the object is located on, (a server ID may
  106. * i.e. be composed of start time, hostname, and pid)
  107. */
  108. string serverID;
  109. /**
  110. * The number of the object under that server
  111. */
  112. long objectID;
  113. /**
  114. * where the server holding object can be reached
  115. */
  116. sequence<string> urls;
  117. };
  118. // Interface definitions
  119. /**
  120. * The definition of a parameter of a method
  121. *
  122. * hints is reserved for future extensions, such as default, min and maxvalues
  123. */
  124. struct ParamDef {
  125. string type;
  126. string name;
  127. sequence<string> hints;
  128. };
  129. /**
  130. * Twoway methods are such where the calling process does a call and is
  131. * suspended until some result (maybe even a void result) gets back.
  132. *
  133. * Oneway methods are one shot and forget methods: you send the invocation,
  134. * and continue. Maybe it will be received, maybe executed later. You will
  135. * never hear the result.
  136. */
  137. enum MethodType {
  138. methodOneway = 1,
  139. methodTwoway = 2
  140. };
  141. /**
  142. * The definition of a method.
  143. *
  144. * hints is reserved for future extensions, such as default, min and maxvalues
  145. */
  146. struct MethodDef {
  147. string name;
  148. string type;
  149. MethodType flags;
  150. sequence<ParamDef> signature;
  151. sequence<string> hints;
  152. };
  153. /**
  154. * an attribute
  155. *
  156. * flags should contain things like
  157. *
  158. * @li attribute is readonly/writeonly/readwrite
  159. * @li attribute is incoming/outgoing stream
  160. * @li if it's a stream, it also should contain the information whether it is
  161. * asynchronous or synchronous
  162. * @li NB20000320: see InterfaceDef for the meaning of streamDefault
  163. */
  164. enum AttributeType {
  165. streamIn = 1,
  166. streamOut = 2,
  167. streamMulti = 4,
  168. attributeStream = 8,
  169. attributeAttribute = 16,
  170. streamAsync = 32,
  171. streamDefault = 64
  172. };
  173. /**
  174. * The definition of an attribute and/or stream
  175. *
  176. * hints is reserved for future extensions, such as default, min and maxvalues
  177. */
  178. struct AttributeDef {
  179. string name;
  180. string type;
  181. AttributeType flags;
  182. sequence<string> hints;
  183. };
  184. /**
  185. * InterfaceDef - interface definition structure
  186. *
  187. * defines what methods/attributes a particular interface supports: these
  188. * do not contain the methods/attributes of inherited interfaces.
  189. *
  190. * inheritedInterfaces only contains the names of Interfaces that this one
  191. * inherits in exactly one step. So to see if interface XYZ is inherited
  192. * from ABC, you need to check the "inheritedInterfaces" of XYZ, and their
  193. * "inheritedInterfaces" and their "inheritedInterfaces" and so on.
  194. *
  195. * - NB20000320: defaultPorts allows to connect to those port by default if
  196. * connection is made in the corresponding direction.
  197. * It cannot be just an attribute flag because of the syntax
  198. * on a separate line.
  199. *
  200. * hints is reserved for future extensions, such as default, min and maxvalues
  201. */
  202. struct InterfaceDef {
  203. string name;
  204. sequence<string> inheritedInterfaces;
  205. sequence<MethodDef> methods;
  206. sequence<AttributeDef> attributes;
  207. sequence<string> defaultPorts;
  208. sequence<string> hints;
  209. };
  210. // Type definitions (struct's and such)
  211. /**
  212. * One component of a struct
  213. *
  214. * hints is reserved for future extensions, such as default, min and maxvalues
  215. */
  216. struct TypeComponent {
  217. string type;
  218. string name;
  219. sequence<string> hints;
  220. };
  221. /**
  222. * The definition of a struct
  223. *
  224. * hints is reserved for future extensions, such as default, min and maxvalues
  225. */
  226. struct TypeDef {
  227. string name;
  228. sequence<TypeComponent> contents;
  229. sequence<string> hints;
  230. };
  231. /**
  232. * One item of an enum value
  233. *
  234. * hints is reserved for future extensions, such as default, min and maxvalues
  235. */
  236. struct EnumComponent {
  237. string name;
  238. long value;
  239. sequence<string> hints;
  240. };
  241. /**
  242. * The definition of an enum
  243. *
  244. * hints is reserved for future extensions, such as default, min and maxvalues
  245. */
  246. struct EnumDef {
  247. /**
  248. * name if the enum, "_anonymous_" for anonymous enum - of course, when
  249. * using namespaces, this can also lead to things like "Arts::_anonymous_",
  250. * which would mean an anonymous enum in the Arts namespace
  251. */
  252. string name;
  253. sequence<EnumComponent> contents;
  254. sequence<string> hints;
  255. };
  256. /**
  257. * The contents of an idl file
  258. *
  259. * hints is reserved for future extensions, such as default, min and maxvalues
  260. */
  261. struct ModuleDef {
  262. string moduleName;
  263. sequence<EnumDef> enums;
  264. sequence<TypeDef> types;
  265. sequence<InterfaceDef> interfaces;
  266. sequence<string> hints;
  267. };
  268. /**
  269. * The interface repository
  270. */
  271. interface InterfaceRepo {
  272. /**
  273. * inserts the contents of a module into the interface repository
  274. *
  275. * @returns an ID which can be used to remove the entry again
  276. */
  277. long insertModule(ModuleDef newModule);
  278. /**
  279. * removes the contents of a module from the interface repository
  280. */
  281. void removeModule(long moduleID);
  282. /**
  283. * queries the definition of an interface
  284. */
  285. InterfaceDef queryInterface(string name);
  286. /**
  287. * queries the definition of a type
  288. */
  289. TypeDef queryType(string name);
  290. /**
  291. * queries the definition of an enum value
  292. */
  293. EnumDef queryEnum(string name);
  294. /**
  295. * queries all interfaces that inherit a given interface
  296. */
  297. sequence<string> queryChildren(string name);
  298. /**
  299. * queries all interfaces
  300. */
  301. sequence<string> queryInterfaces();
  302. /**
  303. * queries all types
  304. */
  305. sequence<string> queryTypes();
  306. /**
  307. * queries all enums
  308. */
  309. sequence<string> queryEnums();
  310. };
  311. enum TypeIdentification {
  312. tiUnknown = 0,
  313. tiVoid = 1,
  314. tiLong = 2,
  315. tiByte = 3,
  316. tiString = 4,
  317. tiBoolean = 5,
  318. tiFloat = 6,
  319. tiEnum = 128,
  320. tiType = 129,
  321. tiInterface = 130
  322. };
  323. interface InterfaceRepoV2 : InterfaceRepo {
  324. /**
  325. * identifies whether a type is a primitive, enum, type or interface,
  326. * or not known at all
  327. */
  328. TypeIdentification identifyType(string name);
  329. };
  330. /**
  331. * Flow System interface
  332. */
  333. /**
  334. * Internal use: implement distributed asynchronous streams.
  335. *
  336. * The FlowSystemSender object transmits the packets that should be sent
  337. * over the stream via _allocCustomMessage (Object_base).
  338. */
  339. interface FlowSystemSender {
  340. /**
  341. * This method is invoked whenever the receiver has finished processing
  342. * a packet of the stream
  343. */
  344. oneway void processed();
  345. /**
  346. * This method is for telling the local FlowSystemSender to break the
  347. * connection to the remote Receiver (it's not intended to be called
  348. * remotely)
  349. */
  350. void disconnect();
  351. };
  352. /**
  353. * Internal use: implement distributed asynchronous streams.
  354. *
  355. * The FlowSystemReceiver object receives and extracts the packets sent by
  356. * the sender object and injects them in the notification system again.
  357. */
  358. interface FlowSystemReceiver {
  359. /**
  360. * The custom message ID which should be used to send the stream packets
  361. */
  362. readonly attribute long receiveHandlerID;
  363. /**
  364. * This method is for telling the local FlowSystemReceiver to break the
  365. * connection to the remote Sender (it's not intended to be called
  366. * remotely)
  367. */
  368. void disconnect();
  369. };
  370. /**
  371. * A flow system.
  372. *
  373. * Flow systems handle the streaming between MCOP objects. As this streaming
  374. * is network transparent (at least for asynchronous streams) they have this
  375. * remote interface.
  376. */
  377. interface FlowSystem {
  378. /**
  379. * This starts a scheduling node
  380. *
  381. * Don't use this manually. Use object->_node()->connect(...) instead.
  382. */
  383. void startObject(object node);
  384. /**
  385. * This stops a scheduling node
  386. *
  387. * Don't use this manually. Use object->_node()->connect(...) instead.
  388. */
  389. void stopObject(object node);
  390. /**
  391. * This connects two objects, maybe even remote
  392. *
  393. * it is important that
  394. * - sourceObject/sourcePort points to the node the signal flow is
  395. * coming from
  396. * - destObject/destPort points to the node/port the signal flow is
  397. * going to
  398. *
  399. * Don't use this manually. Use object->_node()->connect(...) instead.
  400. */
  401. void connectObject(object sourceObject, string sourcePort,
  402. object destObject, string destPort);
  403. /**
  404. * This disconnects two objects, maybe even remote
  405. *
  406. * it is important that
  407. * @li sourceObject/sourcePort points to the node the signal flow is
  408. * coming from
  409. * @li destObject/destPort points to the node/port the signal flow is
  410. * going to
  411. *
  412. * Don't use this manually. Use object->_node()->connect(...) instead.
  413. */
  414. void disconnectObject(object sourceObject, string sourcePort,
  415. object destObject, string destPort);
  416. /**
  417. * queries the stream flags - returns 0 when such a stream isn't
  418. * present
  419. */
  420. AttributeType queryFlags(object node, string port);
  421. /**
  422. * directly sets an audio port to a fixed value
  423. */
  424. void setFloatValue(object node, string port, float value);
  425. /**
  426. * network transparent connections
  427. */
  428. FlowSystemReceiver createReceiver(object destObject, string destPort,
  429. FlowSystemSender sender);
  430. };
  431. /**
  432. * A global communication space used to obtain initial object references
  433. *
  434. * MCOP needs a way to connect to initial (global) object references. This
  435. * is done by these global communication spaces.
  436. */
  437. interface GlobalComm {
  438. /**
  439. * puts a variable/value pair into the global communication
  440. * space - it will not change the value of the variable if it is
  441. * already present. Returns true if success, false if the variable
  442. * was already there.
  443. */
  444. boolean put(string variable, string value);
  445. /**
  446. * gets the value of a variable out of the global communication
  447. * space - it returns an empty string when the variable isn't there
  448. */
  449. string get(string variable);
  450. /**
  451. * removes a variable from the global communication space
  452. */
  453. void erase(string variable);
  454. };
  455. /**
  456. * global communication based on the /tmp/mcop-<username> directory
  457. */
  458. interface TmpGlobalComm : GlobalComm {
  459. };
  460. /*
  461. * Trading interfaces follow - trading is used to locate objects with certain
  462. * properties. This is especially recommended, if you want to allow that after
  463. * your code has been released, people can extend it, without changing your
  464. * code, by adding new components.
  465. */
  466. /**
  467. * TraderOffer - this contains an offer of an object (which is usually returned
  468. * as result of a query.
  469. */
  470. interface TraderOffer {
  471. /**
  472. * You can use this interface name to create one of the objects that
  473. * fulfill your query
  474. */
  475. readonly attribute string interfaceName;
  476. /**
  477. * This allows you to query additional information about the offer,
  478. * such as the author of the plugin, the name of the library that
  479. * implements it (if it is a library) or similar.
  480. *
  481. * Since some properties support having multiple values, this always
  482. * returns a sequence<string>, which may be empty if the property isn't
  483. * present at all.
  484. */
  485. sequence<string> getProperty(string name);
  486. };
  487. /**
  488. * TraderQuery - this is a query against the trader. The idea is simple: you
  489. * say what you need, and the trader offers you components that do what you
  490. * want.
  491. */
  492. interface TraderQuery {
  493. /**
  494. * This restricts the query to only objects which support a "property"
  495. * with the value "value". For instance, you could say
  496. *
  497. * aquery.supports("Interface","Arts::PlayObject");
  498. *
  499. * to restrict the matching objects to only those that support the
  500. * interface Arts::PlayObject
  501. */
  502. void supports(string property, string value);
  503. /**
  504. * This performs the query, and returns a set of results
  505. */
  506. sequence<TraderOffer> query();
  507. };
  508. /**
  509. * Arts::Object is the base object that every interface implicitely inherits
  510. *
  511. * it is also the source for generation of the Object_stub stuff
  512. * (use mcopidl -e Arts::Object to avoid code generation for this interface)
  513. */
  514. interface Object {
  515. /**
  516. * access to the flow system this object is running in
  517. */
  518. readonly attribute FlowSystem _flowSystem;
  519. /** <interface description>
  520. * returns the ID for methodinvocations to this specific method
  521. * methodID = 0 => _lookupMethod (always)
  522. */
  523. long _lookupMethod(MethodDef methodDef);
  524. /** <interface description>
  525. * returns the name of the interface
  526. * methodID = 1 => _interfaceName (always)
  527. */
  528. string _interfaceName();
  529. /** <interface description>
  530. * returns the interface description to a given interface
  531. * methodID = 2 => _queryInterface (always)
  532. */
  533. InterfaceDef _queryInterface(string name);
  534. /** <interface description>
  535. * returns the type description to a given type
  536. * methodID = 3 => _queryType (always)
  537. */
  538. TypeDef _queryType(string name);
  539. /** <interface description>
  540. * returns the enum description to a given enum
  541. * methodID = 4 => _queryEnum (always)
  542. */
  543. EnumDef _queryEnum(string name);
  544. /**
  545. * stringifies the object to one string
  546. */
  547. string _toString();
  548. /** <interface description>
  549. * Run-time type compatibility check
  550. */
  551. boolean _isCompatibleWith(string interfacename);
  552. /** <reference counting>
  553. * prepares object for remote transmission (so that it will not be freed
  554. * soon, since the remote receiver expects it to be there after receiving
  555. * it)
  556. */
  557. void _copyRemote();
  558. /** <reference counting>
  559. * declares that the object is used remotely now (do that only after
  560. * _copyRemote)
  561. */
  562. void _useRemote();
  563. /** <reference counting>
  564. * declares that the object is no longer used remotely
  565. */
  566. void _releaseRemote();
  567. /** <aggregation>
  568. * add a child object - this makes this object hold a strong reference to
  569. * the child object (i.e. the child object will stay alive at least as
  570. * long as the object does)
  571. *
  572. * if there is already a child with the same name, a postfix will be added
  573. * automatically (i.e. if you add an object named "view" twice, the first
  574. * will be called view, the second view1).
  575. */
  576. string _addChild(object child, string name);
  577. /** <aggregation>
  578. * removes a child object
  579. */
  580. boolean _removeChild(string name);
  581. /** <aggregation>
  582. * gets a child object
  583. */
  584. object _getChild(string name);
  585. /** <aggregation>
  586. * lists all children
  587. */
  588. sequence<string> _queryChildren();
  589. };
  590. /**
  591. * a simple struct which can hold any other type
  592. */
  593. struct Any {
  594. string type;
  595. sequence<byte> value;
  596. };
  597. /**
  598. * TraderEntries as produced by the loader
  599. */
  600. struct TraderEntry {
  601. string interfaceName;
  602. sequence<string> lines;
  603. };
  604. /**
  605. * loader to load plugins (implemented in some language/binary format)
  606. */
  607. interface Loader {
  608. object loadObject(TraderOffer offer);
  609. /*
  610. * this is used for the type system to cache your trader data and
  611. * module data as long as it stays unchanged
  612. */
  613. readonly attribute string dataVersion;
  614. /*
  615. * the trader entries of the components that can be loaded
  616. */
  617. readonly attribute sequence<TraderEntry> traderEntries;
  618. /*
  619. * the interface information of the components that can be loaded
  620. */
  621. readonly attribute sequence<ModuleDef> modules;
  622. };
  623. };