<!-- <?xml version="1.0" ?>
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd">
To validate or process this file as a standalone document, uncomment
this prolog. Be sure to comment it out again when you are done -->
<chapter id="mcop">
<title
>&MCOP; : modèle object et streaming</title>
<sect1 id="mcop-overview">
<title
>Aperçu</title>
<para
> &MCOP; est utilisé dans &arts; pour : </para>
<itemizedlist
> <listitem
> <para
> la communication entre objets </para
> </listitem
> <listitem
> <para
> la transparence réseau </para
> </listitem
> <listitem
> <para
> décrire les interfaces objet </para
> </listitem
> <listitem
> <para
> l'indépendance du langage </para
> </listitem
> </itemizedlist>
<para
> Un aspect majeur de &MCOP; est l'<emphasis
>interface description language</emphasis
>, &IDL;, dans laquelle les interfaces de &arts; et les <acronym
>API</acronym
> sont définies dans un langage indépendant. </para>
<para
> Pour utiliser les interfaces &IDL; avec C++, le code &IDL; est compilé par le compilateur &IDL; en code C++. Lorsque vous implantez une interface, vous dérivez à partir de la classe squelette que le compilateur &IDL; a généré. Lorsque vous utilisez une interface, vous utilisez ainsi un wrapper. De cette façon,&MCOP; peut utiliser un protocole si l'objet auquel vous vous adressez n'est pas local - vous bénéficiez de la transparence réseau. </para>
<para
> Ce chapitre est supposé décrire les caractéristiques de base du modèle objet qui résulte de l'utilisation de &MCOP;, le protocole, comment utiliser &MCOP; en C++ (language binding),etc. </para>
</sect1>
<sect1 id="interfaces">
<title
>Interfaces et &IDL;</title>
<para
> La plupart des services fournis par &arts;, comme les modules et le serveur sonore, sont définis en termes d'<acronym
>interfaces</acronym
>. Les interfaces sont spécifiées dans un format indépendant du langage de programmation :&IDL;. </para>
<para
> Ceci permet de dissimuler la plupart des détails d'implantation des spécifications de l'interface, comme par exemple le format des flux de données multimédia, la transparence réseau, et les choses dépendantes du langage de programmation. Un outil, &mcopidl;, traduit la définition de l'interface en un langage de programmation spécifique (actuellement, seul le C++ est géré). </para>
<para
> L'outil génère une classe squelette avec tout le code élémentaire
et les fonctionnalités de base. Vous dérivez cette classe pour implémenter les caractéristiques souhaitées. </para>
<para
> L'&IDL; utilisé par &arts; est similaire à celui utilisé par <acronym
>CORBA</acronym
> et <acronym
>DCOM</acronym
>. </para>
<para
> Lesfichiers &IDL; peuvent contenir : </para>
<itemizedlist
> <listitem
> <para
> Des directives #include dans le style C pour d'autres fichiers &IDL;. </para
> </listitem
> <listitem
> <para
> Des définitions d'énumérations et de types de structures, comme en C/C++ </para
> </listitem
> <listitem
> <para
> Des définitions d'interfaces </para
> </listitem
> </itemizedlist>
<para
> En &IDL;, les interfaces sont définies comme une classe C++ ou une structure C, bien qu'il y ait certaines restrictions. Comme en C++ des interfaces peuvent être définies par héritage d'autres interfaces. Les définitions d'interfaces peuvent inclure trois choses : des flux, des attributs et des méthodes. </para>
<sect2 id="streams">
<title
>Flux</title>
<para
> Les flux représentent les données multimédia, faisant partie des composants les plus importants d'un module. Les flux sont définis par le format suivant : </para>
<para
> [ async ] in|out [ multi ] <replaceable
>type</replaceable
> stream<replaceable
>name</replaceable
> [ , <replaceable
>name</replaceable
> ] ; </para>
<para
> La direction d'un flux est définie par rapport au module, comme le précisent les paramètre obligatoires "in" et "out". L'argument "type" définit le type de la donnée, qui peut être de n'importe quel type décrit plus tard pour les attributs (tous ne sont pas encore supportés). Beaucoup de modules utilisent le type "audio", qui est un synonyme pour le type float (réel) utilisé en interne pour les flux audio. Plusieurs flots du même type peuvent figurer dans la même définition sous la forme d'une liste de noms séparés par des virgules. </para>
<para
> Les flux sont par défaut synchrones, ce qui signifie qu'il constituent un flux continu de données à un taux constant, comme les données audio <acronym
>PCM.</acronym
> Le qualificateur async dénote un flux asynchrone, qui est utilisé pour les flux de données discontinus, comme par exemple les messages &MIDI;. </para>
<para
> Le mot clé multi, valide uniquement pour les flux entrants, indique que l'interface gère un nombre variable d'entrées. C'est utile pour implanter des périphériques comme des tables de mixage qui peuvent accepter un nombre indéterminé de flux entrants. </para>
</sect2>
<sect2 id="attributes">
<title
>Attributs</title>
<para
> Les attributs sont des données associées à une instance d'une interface. Ils sont déclarés comme variables membres en C++, et peuvent utiliser n'importe lequel des types suivants : boolean, byte, long, string, or float. Vous pouvez aussi utiliser des types de structure ou d'énumération définis par l'utilisateur aussi bien que des séquences de taille variable en utilisant la syntaxe sequence <type>. Les attributs peuvent en option être marqués en lecture seule. </para>
</sect2>
<sect2 id="methods">
<title
>Méthodes</title>
<para
> Comme en C++, des méthodes peuvent être définies dans les interfaces. Lesparamètres des méthodes sont restreintes au même type que celui des attributs.Le mot clé oneway indique une méthode qui renvoie une valeur immédiatement etest exécutée de manière asynchrone. </para>
</sect2>
<sect2 id="standardinterfaces">
<title
>Interfaces standards</title>
<para
> Plusieurs interfaces de modules standards sont déjà définies dans &arts;, comme par exemple <interfacename
>StereoEffect</interfacename
> et <interfacename
>SimpleSoundServer</interfacename
>. </para>
</sect2>
<sect2 id="example">
<title
>Exemples</title>
<para
> Un exemple simple de module tiré de &arts; est le module contenant un délai avec retard constant, qui se trouve dans le fichier <filename
>kdemultimedia/arts/modules/artsmodules.idl</filename
>. La définition de l'interface est donnée ci-dessous : </para>
<programlisting>
interface Synth_CDELAY : SynthModule {
attribute float time;
in audio stream invalue;
out audio stream outvalue;
};
</programlisting>
<para
> Ce module hérite de <interfacename
>SynthModule</interfacename
>. Cette interface, définie dans <filename
>artsflow.idl</filename
>, défini les méthodes standards implantées dans tous les modules de synthèse sonore. </para>
<para
> L'effet CDELAY retarde un flux audio stéréo d'une durée spécifiées comme paramètre à virgule flottante. La définition de l'interface comporte un attribut de type float pour mémoriser la valeur du retard. Deux flux audio en entrée et deux en sortie sont définis (caractéristique des signaux stéréo). Aucune méthode n'est requise autre que celles héritées. </para>
</sect2>
</sect1>
<sect1 id="more-about-streams">
<title
></title>
<para
> </para>
<sect2 id="stream-types">
<title
>Types de Flux</title>
<para
> </para>
<itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist>
<para
> </para>
<itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist>
<para
> </para>
<programlisting>
</programlisting>
</sect2>
<sect2 id="async-streams">
<title
></title>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<para
> </para>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
</sect2>
<sect2 id="default-streams">
<title
>Flux par défaut</title>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<programlisting>
interface TwoToOneMixer {
default in audio stream input1, input2;
out audio stream output;
};
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<para
> </para>
<itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist>
</sect2>
</sect1>
<sect1 id="attribute-change-notify">
<title
>notifications de changement d'attribut</title>
<!-- TODO: This should be embedded better into the context - I mean: the
context should be written ;-). -->
<para
> Les notifications de changement d'attribut sont un moyen de savoir lorsqu'un attribut a changé. C'est un peu semblable aux signaux et slots de &Qt;'s ou Gtk. Par exemple, si vous avez un élément d'interface graphique, une glissière, qui sélectionne un nombre entre 0 et 100, vous avez certainement un objet qui fait quelque chose avec ce nombre (par exemple, ce peut être contrôler le volume d'un signal audio). Donc vous voudrez que chaque fois que lag lissière change de position, l'objet qui gère le volume soit mis au courant. Une connexion entre un émetteur et un récepteur. </para>
<para
> &MCOP; gère cela en fournissant des notifications lorsque des attributs changent. Tout ce qui est déclaré comme <quote
>attribut</quote
>dans l'&IDL; peut émettre de telles notifications de changement, et devrait le faire chaque fois qu'il est modifié. Tout ce qui est déclaré comme <quote
>attribut</quote
> peut aussi reçevoir de telles notifications de changement. Donc par exemple si vous avez deux interfaces &IDL;, comme celles-ci : </para>
<programlisting>
interface Slider {
attribute long min,max;
attribute long position;
};
interface VolumeControl : Arts::StereoEffect {
attribute long volume; // 0..100
};
</programlisting>
<para
> Vous pouvez les connecter en utilisant les notifications de changement. Il utilise les opérations habituelles de connexion d'événements . Dans ce cas, le code C++ pour connecter deux objets ressemblerait à ceci : </para>
<programlisting>
#include <connect.h>
using namespace Arts;
[...]
connect(slider,"position_changed",volumeControl,"volume");
</programlisting>
<para
> Comme vous pouvez le voir, chaque attribut offre deux flux, un pour envoyer cette notification de changement, appelé <function
><replaceable
>attributename</replaceable
>_changed</function
>, et un pour reçevoir les notifications de changement, appelé <function
>attributename</function
>. </para>
<para
> Il est important de savoir que ces notifications de changement et flux asynchrones sont compatibles. Ils sont aussi transparents vis-à-vis du réseau. Vous pouvez donc connecter une notification de changement d'un attribut de type flottant d'un widget de l'interface à un flux asynchrone d'un module de synthèse exécuté sur un autre ordinateur. Ceci implique bien sûr que les notifications de changement ne soient pas <emphasis
>synchrones</emphasis
>, ceci signifie qu'après avoir envoyé une notification de changement, il faut un certain temps avant qu'elle soit réellement reçue. </para>
<sect2 id="sending-change-notifications">
<title
>Envoi de notifications de changement</title>
<para
> Lorsque vous implantez des objets qui ont des attributs, vous devez envoyer des notifications de changement chaque fois qu'un attribut est modifié. Le code correspondant ressemble à ceci : </para>
<programlisting>
void KPoti_impl::value(float newValue)
{
if(newValue != _value)
{
_value = newValue;
value_changed(newValue); // <- send change notification
}
}
</programlisting>
<para
> Il est fortement recommandé d'utiliser ce genre de code pour tous les objets que vous implantez, de façon à ce que les notifications de changement puissent être réutilisées par d'autres personnes. Il est préférable d'éviter d'envoyer des notifications trop fréquemment. Ainsi, si vous faites du traitement du signal, il est surement mieux de mémoriser les dernières notifications envoyées, afin de ne pas en envoyer une avec chaque échantillon traité. </para>
</sect2>
<sect2 id="change-notifications-apps">
<title
>Applications pour les notifications de changement</title>
<para
> Il est tout particulièrement intéressant d'utiliser les notifications de changement en conjonction avec des oscilloscopes (pour visualiser les données audio par exemple), éléments de l'interface, widgets de contrôle, et monitoring. Le code pour utiliser ceci se trouve dans <filename class="directory"
>kdelibs/arts/tests</filename
>, et dans l'implantation expérimentale de artsgui, que vous pouvez trouver dans <filename class="directory"
>kdemultimedia/arts/gui</filename
>. </para>
<!-- TODO: can I markup links into the source code - if yes, how? -->
<!-- LW: Linking into the source is problematic - we can't assume people are
reading this on a machine with the sources available, or that they aren't
reading it from a website. We're working on it! -->
</sect2>
<sect2 id="the-mcoprc-file">
<title
></title>
<para
> Le fichier <literal role="extension"
>.mcoprc</literal
> (présent dans le dossier personnel de chaque utilisateur) peut être utilisé pour configurer &MCOP;. Actuellement, les réglages suivants sont disponibles : </para>
<variablelist
> <varlistentry
> <term
>GlobalComm</term
> <listitem
> <para
> Nom de l'interface à utiliser pour la communication globale. Celle-ci est utilisée pour trouver des objets et obtenir le cookie secret. Les clients/serveurs &MCOP; multiples qui devraient pouvoir communiquer entre eux nécessitent un objet GlobalComm capable de partager l'information. Actuellement, les valeurs possibles sont <quote
>Arts::TmpGlobalComm</quote
> pour communiquer via le dossier <filename class="directory"
>/tmp/mcop-<replaceable
>username</replaceable
></filename
> (qui ne fonctionnera que sur l'ordinateur local) et <quote
>Arts::X11GlobalComm</quote
> pour communiquer via les propriétés de la fenêtre principale sur le serveur X11. Par exemple : </para
> </listitem
> </varlistentry
> <varlistentry
> <term
>TraderPath</term
> <listitem
> <para
> Spécifie où chercher les informations du sélecteur dynamique d'application (trader). Vous pouvez lister plus d'un dossier ici, et les séparer par des virgules, comme </para
> </listitem
> </varlistentry
> <varlistentry
> <term
>ExtensionPath</term
> <listitem
> <para
> Spécifie dans quels dossiers se situent les extensions (sous la forme de librairies partagées). Plusieurs valeurs peuvent être saisies, séparées par des virgules. </para
> </listitem
> </varlistentry
> </variablelist>
<para
> Voici un exemple qui utilise toutes les possibilités ci-dessus </para>
<programlisting>
# $HOME/.mcoprc file
GlobalComm=Arts::X11GlobalComm
# if you are a developer, it might be handy to add a directory in your home
# to the trader/extension path to be able to add components without
# installing them
TraderPath="/opt/kde2/lib/mcop","/home/joe/mcopdevel/mcop"
ExtensionPath="/opt/kde2/lib","/home/joe/mcopdevel/lib"
</programlisting>
</sect2>
<sect2 id="mcop-for-corba-users">
<title
>&MCOP; pour les utilisateurs de <acronym
>CORBA</acronym
></title>
<para
> </para>
<para
> </para>
<sect3 id="corba-missing">
<title
></title>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> dans &MCOP; </para>
<para
> </para>
<para
> </para>
<para
> </para>
</sect3>
<sect3 id="corba-different">
<title
></title>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
</sect3>
<sect3 id="no-in-corba">
<title
></title>
<para
> </para>
<programlisting>
// MCOP idl
interface Synth_ADD : SynthModule {
in audio stream signal1,signal2;
out audio stream outvalue;
};
</programlisting>
<para
> </para>
</sect3>
<sect3 id="mcop-binding">
<title
></title>
<para
> </para>
<itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist>
</sect3>
<sect3 id="implementing-objects">
<title
></title>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
</sect3>
</sect2>
<sect2 id="mcop-security">
<title
>Aspect sécurité de &MCOP;</title>
<para
> </para>
<para
> </para>
<itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist>
<para
> </para>
<para
> </para>
<procedure
> <step
> <para
> </para
> </step
> <step
> <para
> </para
> </step
> <step
> <para
> </para
> </step
> <step
> <para
> </para
> </step
> <step
> <para
> </para
> </step
> <step
> <para
> </para
> </step
> </procedure>
<para
> </para>
<orderedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </orderedlist>
<para
> </para>
<procedure
> <step
> <para
> </para
> </step
> <step
> <para
> </para
> </step
> <step
> <para
> </para
> </step
> </procedure>
<para
> </para>
<itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist>
</sect2>
<sect2 id="mcop-protocol">
<title
></title>
<sect3 id="mcop-protocol-intro">
<title
>Introduction</title>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist>
<para
> </para>
<itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist>
</sect3>
<sect3 id="mcop-protocol-marshalling">
<title
></title>
<para
> </para>
<itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> <itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist>
<!-- TODO: Make this a table -->
<para
> </para>
<informaltable>
<tgroup cols="3">
<thead
> <row
> <entry
></entry
> <entry
></entry
> <entry
></entry
> </row
> </thead>
<tbody
> <row
> <entry
><type
></type
></entry
> <entry
></entry
> <entry
></entry
> </row
> <row
> <entry
><type
></type
></entry
> <entry
></entry
> <entry
><literal
></literal
></entry
> </row
> <row
> <entry
><type
></type
></entry
> <entry
><para
></para
></entry
> <entry
></entry
> </row
> <row
> <entry
><type
></type
></entry
> <entry
><para
></para
></entry
> <entry
><literal
></literal
></entry
> </row
> <row
> <entry
><type
></type
></entry
> <entry
><para
></para
> <important
> <para
></para
> </important
> <para
></para
></entry
> <entry
><literal
></literal
></entry
> </row
> <row
> <entry
><type
></type
></entry
> <entry
><para
></para
></entry
> <entry
><literal
></literal
></entry
> </row
> <row
> <entry
><type
></type
></entry
> <entry
><para
></para
></entry
> <entry
><literal
></literal
></entry
> </row
> <row
> <entry
><type
>struct</type
></entry
> <entry
><para
> </para
> <programlisting>
</programlisting
> <para
></para
></entry
> <entry
> <literallayout>
</literallayout
></entry
> </row
> <row
> <entry
><type
></type
></entry
> <entry
><para
></para
> <para
></para
></entry
> <entry
> <literallayout>
</literallayout
> </entry
> </row
> </tbody>
</tgroup>
</informaltable>
<para
> </para>
</sect3>
<sect3 id="mcop-protocol-messages">
<title
></title>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist>
<para
> </para>
<para
> </para>
<para
> </para>
</sect3>
<sect3 id="mcop-protocol-invocations">
<title
></title>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<para
> </para>
<programlisting>
</programlisting>
</sect3>
<sect3 id="mcop-protocol-inspecting">
<title
></title>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<programlisting>
</programlisting>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
</sect3>
<sect3 id="mcop-protocol-typedefs">
<title
></title>
<para
> </para>
<programlisting>
</programlisting>
</sect3>
</sect2>
<sect2 id="why-not-dcop">
<title
></title>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<itemizedlist
> <listitem
><para
></para
></listitem
> <listitem
><para
></para
></listitem
> <listitem
><para
></para
></listitem
> <listitem
><para
></para
></listitem
> <listitem
><para
></para
></listitem
> <listitem
><para
></para
></listitem
> </itemizedlist>
<para
> </para>
<para
> </para>
<itemizedlist
> <listitem
><para
></para
></listitem
> <listitem
><para
></para
></listitem
> <listitem
><para
></para
></listitem
> </itemizedlist>
<para
> </para>
<para
> </para>
<itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist>
<para
> </para>
<itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<para
> </para>
<itemizedlist
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> <listitem
> <para
> </para
> </listitem
> </itemizedlist>
<para
> </para>
</sect2>
</sect1>
</chapter>
