# translation of artsbuilder_mcop.po to 
# translation of artsbuilder_mcop.po to
# translation of artsbuilder_mcop.po to
# Copyright (C) 2002 Free Software Foundation, Inc.
# Lwandle Mgidlana <lwandle@translate.org.za>, 2002
#
msgid ""
msgstr ""
"Project-Id-Version: artsbuilder_mcop\n"
"POT-Creation-Date: 2001-02-09 01:25+0100\n"
"PO-Revision-Date: 2002-09-26 12:34+0200\n"
"Last-Translator: Lwandle Mgidlana <lwandle@translate.org.za>\n"
"Language-Team:  <xh@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: application/x-xml2pot; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"X-Generator: KBabel 1.0beta2\n"

#: index.docbook:7
#, no-c-format
msgid "&MCOP;: Object Model and Streaming"
msgstr ""

#: index.docbook:11
#, no-c-format
msgid "Overview"
msgstr "Imboniselo engaphaya"

#: index.docbook:13
#, no-c-format
msgid "&MCOP; is the standard &arts; uses for:"
msgstr ""

#: index.docbook:17
#, no-c-format
msgid "Communication between objects."
msgstr ""

#: index.docbook:17
#, no-c-format
msgid "Network transparency."
msgstr ""

#: index.docbook:17
#, no-c-format
msgid "Describing object interfaces."
msgstr ""

#: index.docbook:17
#, no-c-format
msgid "Language independancy."
msgstr ""

#: index.docbook:43
#, no-c-format
msgid ""
"One major aspect of &MCOP; is the <emphasis>interface description "
"language</emphasis>, &IDL;, in which many of the &arts; interfaces and "
"<acronym>API</acronym>s are defined in a language independent way."
msgstr ""

#: index.docbook:49
#, no-c-format
msgid ""
"To use &IDL; interfaces from C++, is compiled by the &IDL; compiler into C++ "
"code. When you implement an interface, you derive from the skeleton class "
"the &IDL; compiler has generated. When you use an interface, you do so using "
"a wrapper. This way, &MCOP; can use a protocol if the object you are talking "
"to is not local - you get network transparency."
msgstr ""

#: index.docbook:58
#, no-c-format
msgid ""
"This chapter is supposed to describe the basic features of the object model "
"that results from the use of &MCOP;, the protocol, how do use &MCOP; in C++ "
"(language binding), and so on."
msgstr ""

#: index.docbook:68
#, no-c-format
msgid "Interfaces and &IDL;"
msgstr ""

#: index.docbook:70
#, no-c-format
msgid ""
"Many of the services provided by &arts;, such as modules and the sound "
"server, are defined in terms of <acronym>interfaces</acronym>. Interfaces "
"are specified in a programming language independent format: &IDL;."
msgstr ""

#: index.docbook:77
#, no-c-format
msgid ""
"This allows many of the implementation details such as the format of "
"multimedia data streams, network transparency, and programming language "
"dependencies, to be hidden from the specification for the interface. A tool, "
"&mcopidl;, translates the interface definition into a specific programming "
"language (currently only C++ is supported)."
msgstr ""

#: index.docbook:86
#, no-c-format
msgid ""
"The tool generates a skeleton class with all of the boilerplate code and "
"base functionality. You derive from that class to implement the features you "
"want."
msgstr ""

#: index.docbook:92
#, no-c-format
msgid ""
"The &IDL; used by &arts; is similar to that used by <acronym>CORBA</acronym>"
" and <acronym>DCOM</acronym>."
msgstr ""

#: index.docbook:97
#, no-c-format
msgid "&IDL; files can contain:"
msgstr ""

#: index.docbook:101
#, no-c-format
msgid "C-style #include directives for other &IDL; files."
msgstr ""

#: index.docbook:101
#, no-c-format
msgid "Definitions of enumerated and struct types, as in C/C++."
msgstr ""

#: index.docbook:101
#, no-c-format
msgid "Definitions of interfaces."
msgstr ""

#: index.docbook:121
#, no-c-format
msgid ""
"In &IDL;, interfaces are defined much like a C++ class or C struct, albeit "
"with some restrictions. Like C++, interfaces can subclass other interfaces "
"using inheritance. Interface definitions can include three things: streams, "
"attributes, and methods."
msgstr ""

#: index.docbook:130
#, no-c-format
msgid "Streams"
msgstr ""

#: index.docbook:132
#, no-c-format
msgid ""
"Streams define multimedia data, one of the most important components of a "
"module. Streams are defined in the following format:"
msgstr ""

#: index.docbook:137
#, no-c-format
msgid ""
"[ async ] in|out [ multi ] <replaceable>type</replaceable> stream "
"<replaceable>name</replaceable> [ , <replaceable>name</replaceable> ] ;"
msgstr ""

#: index.docbook:141
#, no-c-format
msgid ""
"Streams have a defined direction in reference to the module, as indicated by "
"the required qualifiers in or out. The type argument defines the type of "
"data, which can be any of the types described later for attributes (not all "
"are currently supported). Many modules use the stream type audio, which is "
"an alias for float since that is the internal data format used for audio "
"stream. Multiple streams of the same type can defined in the same definition "
"uisng comma separated names."
msgstr ""

#: index.docbook:151
#, no-c-format
msgid ""
"Streams are by default synchronous, which means they are continuous flows of "
"data at a constant rate, such as <acronym>PCM</acronym> audio. The async "
"qualifier specifies an asynchronous stream, which is used for non-continuous "
"data flows. The most common example of an async stream is &MIDI; messages."
msgstr ""

#: index.docbook:159
#, no-c-format
msgid ""
"The multi keyword, only valid for input streams, indicates that the "
"interface supports a variable number of inputs. This is useful for "
"implementing devices such as mixers that can accept any number of input "
"streams."
msgstr ""

#: index.docbook:169
#, no-c-format
msgid "Attributes"
msgstr "Iziphumo"

#: index.docbook:171
#, no-c-format
msgid ""
"Attributes are data associated with an instance of an interface. They are "
"declared like member variables in C++, and can can use any of the primitive "
"types boolean, byte, long, string, or float. You can also use user-defined "
"struct or enum types as well as variable sized sequences using the syntax "
"sequence&lt;type&gt;. Attributes can optionally be marked readonly."
msgstr ""

#: index.docbook:183
#, no-c-format
msgid "Methods"
msgstr "Iindlela zokwenza"

#: index.docbook:185
#, no-c-format
msgid ""
"As in C++, methods can be defined in interfaces. The method parameters are "
"restricted to the same types as attributes. The keyword oneway indicates a "
"method which returns immediately and is executed asynchronously."
msgstr ""

#: index.docbook:196
#, no-c-format
msgid "Standard Interfaces"
msgstr ""

#: index.docbook:198
#, no-c-format
msgid ""
"Several standard module interfaces are already defined for you in &arts;, "
"such as <interfacename>StereoEffect</interfacename>, and "
"<interfacename>SimpleSoundServer</interfacename>."
msgstr ""

#: index.docbook:207
#, no-c-format
msgid "Example"
msgstr "Umzekelo"

#: index.docbook:209
#, no-c-format
msgid ""
"A simple example of a module taken from &arts; is the constant delay module, "
"found in the file "
"<filename>kdemultimedia/arts/modules/artsmodules.idl</filename>. The "
"interface definition is listed below."
msgstr ""

#: index.docbook:216
#, no-c-format
msgid ""
"interface Synth_CDELAY : SynthModule {\n"
"        attribute float time;\n"
"        in audio stream invalue;\n"
"        out audio stream outvalue;\n"
"};"
msgstr ""

#: index.docbook:224
#, no-c-format
msgid ""
"This modules inherits from <interfacename>SynthModule</interfacename>. That "
"interface, defined in <filename>artsflow.idl</filename>, defines the "
"standard methods implemented in all music synthesizer modules."
msgstr ""

#: index.docbook:231
#, no-c-format
msgid ""
"The CDELAY effect delays a stereo audio stream by the time value specified "
"as a floating point parameter. The interface definition has an attribute of "
"type float to store the delay value. It defines two input audio streams and "
"two output audio streams (typical of stereo effects). No methods are "
"required other than those it inherits."
msgstr ""

#: index.docbook:244
#, no-c-format
msgid "More About Streams"
msgstr ""

#: index.docbook:246
#, no-c-format
msgid "This section covers some additional topics related to streams."
msgstr ""

#: index.docbook:251
#, no-c-format
msgid "Stream Types"
msgstr ""

#: index.docbook:253
#, no-c-format
msgid ""
"There are various requirements for how a module can do streaming. To "
"illustrate this, consider these examples:"
msgstr ""

#: index.docbook:258
#, no-c-format
msgid "Scaling a signal by a factor of two."
msgstr ""

#: index.docbook:258
#, no-c-format
msgid "Performing sample frequency conversion."
msgstr ""

#: index.docbook:258
#, no-c-format
msgid "Decompressing a run-length encoded signal."
msgstr ""

#: index.docbook:258
#, no-c-format
msgid ""
"Reading &MIDI; events from <filename "
"class=\"devicefile\">/dev/midi00</filename> and inserting them into a stream."
msgstr ""

#: index.docbook:286
#, no-c-format
msgid ""
"The first case is the simplest: upon receiving 200 samples of input the "
"module produces 200 samples of output. It only produces output when it gets "
"input."
msgstr ""

#: index.docbook:292
#, no-c-format
msgid ""
"The second case produces different numbers of output samples when given 200 "
"input samples. It depends what conversion is performed, but the number is "
"known in advance."
msgstr ""

#: index.docbook:298
#, no-c-format
msgid ""
"The third case is even worse. From the outset you cannot even guess how much "
"data 200 input bytes will generate (probably a lot more than 200 bytes, "
"but...)."
msgstr ""

#: index.docbook:304
#, no-c-format
msgid ""
"The last case is a module which becomes active by itself, and sometimes "
"produces data."
msgstr ""

#: index.docbook:309
#, no-c-format
msgid ""
"In &arts;s-0.3.4, only streams of the first type were handled, and most "
"things worked nicely. This is probably what you need most when writing "
"modules that process audio. The problem with the other, more complex types "
"of streaming, is that they are hard to program, and that you don't need the "
"features most of the time. That is why we do this with two different stream "
"types: synchronous and asynchronous."
msgstr ""

#: index.docbook:318
#, no-c-format
msgid "Synchronous streams have these characteristics:"
msgstr ""

#: index.docbook:322
#, no-c-format
msgid "Modules must be able to calculate data of any length, given enough input."
msgstr ""

#: index.docbook:322
#, no-c-format
msgid "All streams have the same sampling rate."
msgstr ""

#: index.docbook:322
#, no-c-format
msgid ""
"The <function>calculateBlock()</function> function will be called when "
"enough data is available, and the module can rely on the pointers pointing "
"to data."
msgstr ""

#: index.docbook:322
#, no-c-format
msgid "There is no allocation and deallocation to be done."
msgstr ""

#: index.docbook:351
#, no-c-format
msgid "Asynchronous streams, on the other hand, have this behaviour:"
msgstr ""

#: index.docbook:355
#, no-c-format
msgid ""
"Modules may produce data sometimes, or with varying sampling rate, or only "
"if they have input from some filed escriptor. They are not bound by the rule "
"<quote>must be able to satisfy requests of any size</quote>."
msgstr ""

#: index.docbook:355
#, no-c-format
msgid "Asynchronous streams of a module may have entirely different sampling rates."
msgstr ""

#: index.docbook:355
#, no-c-format
msgid ""
"Outgoing streams: there are explicit functions to allocate packets, to send "
"packets - and an optional polling mechanism that will tell you when you "
"should create some more data."
msgstr ""

#: index.docbook:355
#, no-c-format
msgid ""
"Incoming streams: you get a call when you receive a new packet - you have to "
"say when you are through with processing all data of that packet, which must "
"not happen at once (you can say that anytime later, and if everybody has "
"processed a packet, it will be freed/reused)"
msgstr ""

#: index.docbook:389
#, no-c-format
msgid ""
"When you declare streams, you use the keyword <quote>async</quote> to "
"indicate you want to make an asynchronous stream. So, for instance, assume "
"you want to convert an asynchronous stream of bytes into a synchronous "
"stream of samples. Your interface could look like this:"
msgstr ""

#: index.docbook:396
#, no-c-format
msgid ""
"interface ByteStreamToAudio : SynthModule {\n"
"    async in byte stream indata;   // the asynchonous input sample stream\n"
"\n"
"    out audio stream left,right;   // the synchronous output sample streams\n"
"};"
msgstr ""

#: index.docbook:407
#, no-c-format
msgid "Using Asynchronous Streams"
msgstr ""

#: index.docbook:409
#, no-c-format
msgid ""
"Suppose you decided to write a module to produce sound asynchronously. Its "
"interface could look like this:"
msgstr ""

#: index.docbook:414
#, no-c-format
msgid ""
"interface SomeModule : SynthModule\n"
"{\n"
"    async out byte stream outdata;\n"
"};"
msgstr ""

#: index.docbook:421
#, no-c-format
msgid ""
"How do you send the data? The first method is called <quote>push "
"delivery</quote>. With asynchronous streams you send the data as packets. "
"That means you send individual packets with bytes as in the above example. "
"The actual process is: allocate a packet, fill it, send it."
msgstr ""

#: index.docbook:429
#, no-c-format
msgid "Here it is in terms of code. First we allocate a packet:"
msgstr ""

#: index.docbook:433
#, no-c-format
msgid "DataPacket&lt;mcopbyte&gt; *packet = outdata.allocPacket(100);"
msgstr ""

#: index.docbook:437
#, no-c-format
msgid "The we fill it:"
msgstr ""

#: index.docbook:441
#, no-c-format
msgid ""
"// cast so that fgets is happy that it has a (char *) pointer\n"
"char *data = (char *)packet-&gt;contents;\n"
"\n"
"// as you can see, you can shrink the packet size after allocation\n"
"// if you like\n"
"if(fgets(data,100,stdin))\n"
"    packet-&gt;size = strlen(data);\n"
"else\n"
"    packet-&gt;size = 0;"
msgstr ""

#: index.docbook:453
#, no-c-format
msgid "Now we send it:"
msgstr ""

#: index.docbook:457
#, no-c-format
msgid "packet-&gt;send();"
msgstr ""

#: index.docbook:461
#, no-c-format
msgid ""
"This is quite simple, but if we want to send packets exactly as fast as the "
"receiver can process them, we need another approach, the <quote>pull "
"delivery</quote> method. You ask to send packets as fast as the receiver is "
"ready to process them. You start with a certain amount of packets you send. "
"As the receiver processes one packet after another, you start refilling them "
"with fresh data, and send them again."
msgstr ""

#: index.docbook:470
#, no-c-format
msgid "You start that by calling setPull. For example:"
msgstr ""

#: index.docbook:474
#, no-c-format
msgid "outdata.setPull(8, 1024);"
msgstr ""

#: index.docbook:478
#, no-c-format
msgid ""
"This means that you want to send packets over outdata. You want to start "
"sending 8 packets at once, and as the receiver processes some of them, you "
"want to refill them."
msgstr ""

#: index.docbook:484
#, no-c-format
msgid ""
"Then, you need to implement a method which fills the packets, which could "
"look like this:"
msgstr ""

#: index.docbook:489
#, no-c-format
msgid ""
"void request_outdata(DataPacket&lt;mcopbyte&gt; *packet)\n"
"{\n"
"    packet-&gt;size = 1024;  // shouldn't be more than 1024\n"
"    for(int i = 0;i &lt; 1024; i++)\n"
"        packet-&gt;contents[i] = (mcopbyte)'A';\n"
"    packet-&gt;send();\n"
"}"
msgstr ""

#: index.docbook:499
#, no-c-format
msgid ""
"Thats it. When you don't have any data any more, you can start sending "
"packets with zero size, which will stop the pulling."
msgstr ""

#: index.docbook:504
#, no-c-format
msgid ""
"Note that it is essential to give the method the exact name "
"<methodname>request_<replaceable>streamname</replaceable></methodname>."
msgstr ""

#: index.docbook:509
#, no-c-format
msgid ""
"We just discussed sending data. Receiving data is much much simpler. Suppose "
"you have a simple ToLower filter, which simply converts all letters in "
"lowercase:"
msgstr ""

#: index.docbook:515
#, no-c-format
msgid ""
"interface ToLower {\n"
"    async in byte stream indata;\n"
"    async out byte stream outdata;\n"
"};"
msgstr ""

#: index.docbook:522
#, no-c-format
msgid "This is really simple to implement; here is the whole implementation:"
msgstr ""

#: index.docbook:526
#, no-c-format
msgid ""
"class ToLower_impl : public ToLower_skel {\n"
"public:\n"
"    void process_indata(DataPacket&lt;mcopbyte&gt; *inpacket)\n"
"    {\n"
"        DataPacket&lt;mcopbyte&gt; *outpacket = "
"outdata.allocPacket(inpacket-&gt;size);\n"
"\n"
"        // convert to lowercase letters\n"
"        char *instring = (char *)inpacket-&gt;contents;\n"
"        char *outstring = (char *)outpacket-&gt;contents;\n"
"\n"
"        for(int i=0;i&lt;inpacket-&gt;size;i++)\n"
"            outstring[i] = tolower(instring[i]);\n"
"\n"
"        inpacket-&gt;processed();\n"
"        outpacket-&gt;send();\n"
"    }\n"
"};\n"
"\n"
"REGISTER_IMPLEMENTATION(ToLower_impl);"
msgstr ""

#: index.docbook:548
#, no-c-format
msgid ""
"Again, it is essential to name the method "
"<methodname>process_<replaceable>streamname</replaceable></methodname>."
msgstr ""

#: index.docbook:553
#, no-c-format
msgid ""
"As you see, for each arriving packet you get a call for a function (the "
"<function>process_indata</function> call in our case). You need to call the "
"<methodname>processed()</methodname>"
" method of a packet to indicate you have processed it."
msgstr ""

#: index.docbook:560
#, no-c-format
msgid ""
"Here is an implenetation tip: if processing takes longer (&ie; if you need "
"to wait for soundcard output or something like that), don't call processed "
"immediately, but store the whole data packet and call processed only as soon "
"as you really processed that packet. That way, senders have a chance to know "
"how long it really takes to do your work."
msgstr ""

#: index.docbook:568
#, no-c-format
msgid ""
"As synchronization isn't so nice with asynchronous streams, you should use "
"synchronous streams wherever possible, and asynchronous streams only when "
"necessary."
msgstr ""

#: index.docbook:577
#, no-c-format
msgid "Default Streams"
msgstr ""

#: index.docbook:579
#, no-c-format
msgid ""
"Suppose you have 2 objects, for example an AudioProducer and an "
"AudioConsumer. The AudioProducer has an output stream and AudioConsumer has "
"an input one. Each time you want to connect them, you will use those 2 "
"streams. The first use of defaulting is to enable you to make the connection "
"without specifying the ports in that case."
msgstr ""

#: index.docbook:587
#, no-c-format
msgid ""
"Now suppose the teo objects above can handle stereo, and each have a "
"<quote>left</quote> and <quote>right</quote> port. You'd still like to "
"connect them as easily as before. But how can the connecting system know "
"which output port to connect to which input port? It has no way to correctly "
"map the streams. Defaulting is then used to specify several streams, with an "
"order. Thus, when you connect an object with 2 default output streams to "
"another one with 2 default input streams, you don't have to specify the "
"ports, and the mapping will be done correctly."
msgstr ""

#: index.docbook:598
#, no-c-format
msgid ""
"Of course, this is not limited to stereo. Any number of streams can be made "
"default if needed, and the connect function will check that the number of "
"defaults for 2 object match (in the required direction) if you don't specify "
"the ports to use."
msgstr ""

#: index.docbook:605
#, no-c-format
msgid ""
"The syntax is as follows: in the &IDL;, you can use the default keyword in "
"the stream declaration, or on a single line. For example:"
msgstr ""

#: index.docbook:610
#, no-c-format
msgid ""
"interface TwoToOneMixer {\n"
"    default in audio stream input1, input2;\n"
"    out audio stream output;\n"
"};"
msgstr ""

#: index.docbook:617
#, no-c-format
msgid ""
"In this example, the object will expect its two input ports to be connected "
"by default. The order is the one specified on the default line, so an object "
"like this one:"
msgstr ""

#: index.docbook:623
#, no-c-format
msgid ""
"interface DualNoiseGenerator {\n"
"    out audio stream bzzt, couic;\n"
"    default couic, bzzt;\n"
"};"
msgstr ""

#: index.docbook:630
#, no-c-format
msgid ""
"Will make connections from <quote>couic</quote> to <quote>input1</quote>, "
"and <quote>bzzt</quote> to <quote>input2</quote> automatically. Note that "
"since there is only one output for the mixer, it will be made default in "
"this case (see below). The syntax used in the noise generator is useful to "
"declare a different order than the declaration, or selecting only a few "
"ports as default. The directions of the ports on this line will be looked up "
"by &mcopidl;, so don't specify them. You can even mix input and output ports "
"in such a line, only the order is important."
msgstr ""

#: index.docbook:642
#, no-c-format
msgid "There are some rules that are followed when using inheritance:"
msgstr ""

#: index.docbook:646
#, no-c-format
msgid ""
"If a default list is specified in the &IDL;, then use it. Parent ports can "
"be put in this list as well, whether they were default in the parent or not."
msgstr ""

#: index.docbook:646
#, no-c-format
msgid ""
"Otherwise, inherit parent's defaults. Ordering is parent1 default1, parent1 "
"default2..., parent2 default1... If there is a common ancestor using 2 "
"parent branches, a <quote>virtual public</quote>-like merging is done at "
"that default's first occurrence in the list."
msgstr ""

#: index.docbook:646
#, no-c-format
msgid ""
"If there is still no default and a single stream in a direction, use it as "
"default for that direction."
msgstr ""

#: index.docbook:676
#, no-c-format
msgid "Attribute change notifications"
msgstr ""

#: index.docbook:681
#, no-c-format
msgid ""
"Attribute change notifications are a way to know when an attribute changed. "
"They are a bit comparable with &Qt;'s or Gtk's signals and slots. For "
"instance, if you have a &GUI; element, a slider, which configures a number "
"between 0 and 100, you will usually have an object that does something with "
"that number (for instance, it might be controlling the volume of some audio "
"signal). So you would like that whenever the slider is moved, the object "
"which scales the volume gets notified. A connection between a sender and a "
"receiver."
msgstr ""

#: index.docbook:692
#, no-c-format
msgid ""
"&MCOP; deals with that by being able to providing notifications when "
"attributes change. Whatever is declared as <quote>attribute</quote> in the "
"&IDL;, can emit such change notifications, and should do so, whenever it is "
"modified. Whatever is declared as <quote>attribute</quote> can also receive "
"such change notifications. So for instance if you had two &IDL; interfaces, "
"like these:"
msgstr ""

#: index.docbook:701
#, no-c-format
msgid ""
"interface Slider {\n"
"         attribute long min,max;\n"
"         attribute long position;\n"
" };\n"
" interface VolumeControl : Arts::StereoEffect {\n"
"     attribute long volume; // 0..100\n"
" };"
msgstr ""

#: index.docbook:711
#, no-c-format
msgid ""
"You can connect them using change notifications. It works using the normal "
"flowsystem connect operation. In this case, the C++ code to connect two "
"objects would look like this:"
msgstr ""

#: index.docbook:717
#, no-c-format
msgid ""
"#include &lt;connect.h&gt;\n"
"using namespace Arts;\n"
"[...]\n"
"connect(slider,\"position_changed\",volumeControl,\"volume\");"
msgstr ""

#: index.docbook:724
#, no-c-format
msgid ""
"As you see, each attribute offers two different streams, one for sending the "
"change notifications, called "
"<function><replaceable>attributename</replaceable>_changed</function>, and "
"one for receiving change notifications, called "
"<function>attributename</function>."
msgstr ""

#: index.docbook:758
#, no-c-format
msgid ""
"It is important to know that change notifications and asynchronous streams "
"are compatible. They are also network transparent. So you can connect a "
"change notification of a float attribute of a &GUI; widget has to an "
"asynchronous stream of a synthesis module running on another computer. This "
"of course also implies that change notifications are <emphasis>not "
"synchronous</emphasis>, this means, that after you have sent the change "
"notification, it may take some time until it really gets received."
msgstr ""

#: index.docbook:771
#, no-c-format
msgid "Sending change notifications"
msgstr ""

#: index.docbook:773
#, no-c-format
msgid ""
"When implementing objects that have attributes, you need to send change "
"notifications whereever an attribute changes. The code for doing this looks "
"like this:"
msgstr ""

#: index.docbook:779
#, no-c-format
msgid ""
"void KPoti_impl::value(float newValue)\n"
" {\n"
"     if(newValue != _value)\n"
"     {\n"
"         _value = newValue;\n"
"         value_changed(newValue); // &lt;- send change notification\n"
"     }\n"
" }"
msgstr ""

#: index.docbook:790
#, no-c-format
msgid ""
"It is strongly recommended to use code like this for all objects you "
"implement, so that change notifications can be used by other people. You "
"should however void sending notifications too often, so if you are doing "
"signal processing, it is probably the best if you keep track when you sent "
"your last notification, so that you don't send one with every sample you "
"process."
msgstr ""

#: index.docbook:802
#, no-c-format
msgid "Applications for change notifications"
msgstr ""

#: index.docbook:804
#, no-c-format
msgid ""
"It will be especially useful to use change notifications in conjunction with "
"scopes (things that visualize audio data for instance), gui elements, "
"control widgets, and monitoring. Code using this is in <filename "
"class=\"directory\">kdelibs/arts/tests</filename>, and in the experimental "
"artsgui implementation, which you can find under <filename "
"class=\"directory\">kdemultimedia/arts/gui</filename>."
msgstr ""

#: index.docbook:824
#, no-c-format
msgid "The <literal role=\"extension\">.mcoprc</literal> file"
msgstr ""

#: index.docbook:826
#, no-c-format
msgid ""
"The <literal role=\"extension\">.mcoprc</literal> file (in each user's home "
"directory) can be used to configure &MCOP; in some ways. Currently, the "
"following is possible:"
msgstr ""

#: index.docbook:832
#, no-c-format
msgid "GlobalComm"
msgstr ""

#: index.docbook:832
#, no-c-format
msgid ""
"The name of an interface to be used for global communication. Global "
"communication is used to find other objects and obtain the secret cookie. "
"Multiple &MCOP; clients/servers that should be able to talk to each other "
"need to have a GlobalComm object which is able to share information between "
"them. Currently, the possible values are <quote>Arts::TmpGlobalComm</quote> "
"to communicate via <filename "
"class=\"directory\">/tmp/mcop-<replaceable>username</replaceable></filename>"
" directory (which will only work on the local computer) and "
"<quote>Arts::X11GlobalComm</quote> to communicate via the root window "
"properties on the X11 server."
msgstr ""

#: index.docbook:832
#, no-c-format
msgid "TraderPath"
msgstr ""

#: index.docbook:832
#, no-c-format
msgid ""
"Specifies where to look for trader information. You can list more than one "
"directory here, and separate them with commas, like"
msgstr ""

#: index.docbook:832
#, no-c-format
msgid "ExtensionPath"
msgstr ""

#: index.docbook:832
#, no-c-format
msgid ""
"Specifies from which directories extensions (in the form of shared "
"libraries) are loaded. Multiple values can be specified comma seperated."
msgstr ""

#: index.docbook:877
#, no-c-format
msgid "An example which uses all of the above is:"
msgstr ""

#: index.docbook:881
#, no-c-format
msgid ""
"# $HOME/.mcoprc file\n"
"GlobalComm=Arts::X11GlobalComm\n"
"\n"
"# if you are a developer, it might be handy to add a directory in your home\n"
"# to the trader/extension path to be able to add components without\n"
"# installing them\n"
"TraderPath=\"/opt/kde2/lib/mcop\",\"/home/joe/mcopdevel/mcop\"\n"
"ExtensionPath=\"/opt/kde2/lib\",\"/home/joe/mcopdevel/lib\""
msgstr ""

#: index.docbook:895
#, no-c-format
msgid "&MCOP; for <acronym>CORBA</acronym> Users"
msgstr ""

#: index.docbook:897
#, no-c-format
msgid ""
"If you have used <acronym>CORBA</acronym> before, you will see that &MCOP; "
"is much the same thing. In fact, &arts; prior to version 0.4 used "
"<acronym>CORBA</acronym>."
msgstr ""

#: index.docbook:903
#, no-c-format
msgid ""
"The basic idea of <acronym>CORBA</acronym> is the same: you implement "
"objects (components). By using the &MCOP; features, your objects are not "
"only available as normal classes from the same process (via standard C++ "
"techniques) - they also are available to remote servers transparently. For "
"this to work, the first thing you need to do is to specify the interface of "
"your objects in an &IDL; file - just like <acronym>CORBA</acronym> &IDL;. "
"There are only a few differences."
msgstr ""

#: index.docbook:914
#, no-c-format
msgid "<acronym>CORBA</acronym> Features That Are Missing In &MCOP;"
msgstr ""

#: index.docbook:917
#, no-c-format
msgid ""
"In &MCOP; there are no <quote>in</quote> and <quote>out</quote> parameters "
"on method invocations. Parameters are always incoming, the return code is "
"always outgoing, which means that the interface:"
msgstr ""

#: index.docbook:923
#, no-c-format
msgid ""
"// CORBA idl\n"
"interface Account {\n"
"  void deposit( in long amount );\n"
"  void withdraw( in long amount );\n"
"  long balance();\n"
"};"
msgstr ""

#: index.docbook:932
#, no-c-format
msgid "is written as"
msgstr ""

#: index.docbook:936
#, no-c-format
msgid ""
"// MCOP idl\n"
"interface Account {\n"
"  void deposit( long amount );\n"
"  void withdraw( long amount );\n"
"  long balance();\n"
"};"
msgstr ""

#: index.docbook:945
#, no-c-format
msgid "in &MCOP;."
msgstr ""

#: index.docbook:949
#, no-c-format
msgid ""
"There is no exception support. &MCOP; doesn't have exceptions - it uses "
"something else for error handling."
msgstr ""

#: index.docbook:954
#, no-c-format
msgid ""
"There are no union types and no typedefs. I don't know if that is a real "
"weakness, something one would desperately need to survive."
msgstr ""

#: index.docbook:959
#, no-c-format
msgid "There is no support for passing interfaces or object references"
msgstr ""

#: index.docbook:966
#, no-c-format
msgid "<acronym>CORBA</acronym> Features That Are Different In &MCOP;"
msgstr ""

#: index.docbook:969
#, no-c-format
msgid ""
"You declare sequences as "
"<quote>sequence<replaceable>type</replaceable></quote> in &MCOP;. There is "
"no need for a typedef. For example, instead of:"
msgstr ""

#: index.docbook:975
#, no-c-format
msgid ""
"// CORBA idl\n"
"struct Line {\n"
"    long x1,y1,x2,y2;\n"
"};\n"
"typedef sequence&lt;Line&gt; LineSeq;\n"
"interface Plotter {\n"
"    void draw(in LineSeq lines);\n"
"};"
msgstr ""

#: index.docbook:986
#, no-c-format
msgid "you would write"
msgstr ""

#: index.docbook:990
#, no-c-format
msgid ""
"// MCOP idl\n"
"struct Line {\n"
"    long x1,y1,x2,y2;\n"
"};\n"
"interface Plotter {\n"
"    void draw(sequence&lt;Line&gt; lines);\n"
"};"
msgstr ""

#: index.docbook:1003
#, no-c-format
msgid "&MCOP; Features That Are Not In <acronym>CORBA</acronym>"
msgstr ""

#: index.docbook:1005
#, no-c-format
msgid ""
"You can declare streams, which will then be evaluated by the &arts; "
"framework. Streams are declared in a similar manner to attributes. For "
"example:"
msgstr ""

#: index.docbook:1011
#, no-c-format
msgid ""
"// MCOP idl\n"
"interface Synth_ADD : SynthModule {\n"
"    in audio stream signal1,signal2;\n"
"    out audio stream outvalue;\n"
"};"
msgstr ""

#: index.docbook:1019
#, no-c-format
msgid ""
"This says that your object will accept two incoming synchronous audio "
"streams called signal1 and signal2. Synchronous means that these are streams "
"that deliver x samples per second (or other time), so that the scheduler "
"will guarantee to always provide you a balanced amount of input data (&eg; "
"200 samples of signal1 are there and 200 samples signal2 are there). You "
"guarantee that if your object is called with those 200 samples signal1 + "
"signal2, it is able to produce exactly 200 samples to outvalue."
msgstr ""

#: index.docbook:1033
#, no-c-format
msgid "The &MCOP; C++ Language Binding"
msgstr ""

#: index.docbook:1035
#, no-c-format
msgid "This differs from <acronym>CORBA</acronym> mostly:"
msgstr ""

#: index.docbook:1039
#, no-c-format
msgid ""
"Strings use the C++ <acronym>STL</acronym> <classname>string</classname> "
"class. When stored in sequences, they are stored <quote>plain</quote>, that "
"means they are considered to be a primitive type. Thus, they need copying."
msgstr ""

#: index.docbook:1039
#, no-c-format
msgid "longs are plain long's (expected to be 32 bit)."
msgstr ""

#: index.docbook:1039
#, no-c-format
msgid ""
"Sequences use the C++ <acronym>STL</acronym> <classname>vector</classname> "
"class."
msgstr ""

#: index.docbook:1039
#, no-c-format
msgid ""
"Structures are all derived from the &MCOP; class "
"<classname>Type</classname>, and generated by the &MCOP; &IDL; compiler. "
"When stored in sequences, they are not stored <quote>plain</quote> , but as "
"pointers, as otherwise, too much copying would occur."
msgstr ""

#: index.docbook:1075
#, no-c-format
msgid "Implementing &MCOP; Objects"
msgstr ""

#: index.docbook:1077
#, no-c-format
msgid ""
"After having them passed through the &IDL; compiler, you need to derive from "
"the <classname>_skel</classname> class. For instance, consider you have "
"defined your interface like this:"
msgstr ""

#: index.docbook:1083
#, no-c-format
msgid ""
"// MCOP idl: hello.idl\n"
"interface Hello {\n"
"    void hello(string s);\n"
"    string concat(string s1, string s2);\n"
"    long sum2(long a, long b);\n"
"};"
msgstr ""

#: index.docbook:1092
#, no-c-format
msgid ""
"You pass that through the &IDL; compiler by calling "
"<userinput><command>mcopidl</command> "
"<parameter>hello.idl</parameter></userinput>, which will in turn generate "
"<filename>hello.cc</filename> and <filename>hello.h</filename>"
". To implement it, you need to define a C++-class that inherits the skeleton:"
msgstr ""

#: index.docbook:1100
#, no-c-format
msgid ""
"// C++ header file - include hello.h somewhere\n"
"class Hello_impl : virtual public Hello_skel {\n"
"public:\n"
"    void hello(const string&amp; s);\n"
"    string concat(const string&amp; s1, const string&amp; s2);\n"
"    long sum2(long a, long b);\n"
"};"
msgstr ""

#: index.docbook:1110
#, no-c-format
msgid "Finally, you need to implement the methods as normal C++"
msgstr ""

#: index.docbook:1114
#, no-c-format
msgid ""
"// C++ implementation file\n"
"\n"
"// as you see string's are passed as const string references\n"
"void Hello_impl::hello(const string&amp; s)\n"
"{\n"
"    printf(\"Hello '%s'!\\n\",s.c_str());\n"
"}\n"
"\n"
"// when they are a returncode they are passed as \"normal\" strings\n"
"string Hello_impl::concat(const string&amp; s1, const string&amp; s2)\n"
"{\n"
"    return s1+s2;\n"
"}\n"
"\n"
"long Hello_impl::sum2(long a, long b)\n"
"{\n"
"    return a+b;\n"
"}"
msgstr ""

#: index.docbook:1135
#, no-c-format
msgid ""
"Once you do that, you have an object which can communicate using &MCOP;. "
"Just create one (using the normal C++ facilities to create an object):"
msgstr ""

#: index.docbook:1140
#, no-c-format
msgid "Hello_impl server;"
msgstr ""

#: index.docbook:1144
#, no-c-format
msgid "And as soon as you give somebody the reference"
msgstr ""

#: index.docbook:1148
#, no-c-format
msgid ""
"string reference = server._toString();\n"
"    printf(\"%s\\n\",reference.c_str());"
msgstr ""

#: index.docbook:1153
#, no-c-format
msgid "and go to the &MCOP; idle loop"
msgstr ""

#: index.docbook:1157
#, no-c-format
msgid "Dispatcher::the()-&gt;run();"
msgstr ""

#: index.docbook:1161
#, no-c-format
msgid "People can access the thing using"
msgstr ""

#: index.docbook:1165
#, no-c-format
msgid ""
"// this code can run anywhere - not necessarily in the same process\n"
"// (it may also run on a different computer/architecture)\n"
"\n"
"    Hello *h = Hello::_fromString([the object reference printed above]);"
msgstr ""

#: index.docbook:1172
#, no-c-format
msgid "and invoke methods:"
msgstr ""

#: index.docbook:1176
#, no-c-format
msgid ""
"if(h)\n"
"        h-&gt;hello(\"test\");\n"
"    else\n"
"        printf(\"Access failed?\\n\");"
msgstr ""

#: index.docbook:1187
#, no-c-format
msgid "&MCOP; Security Considerations"
msgstr ""

#: index.docbook:1189
#, no-c-format
msgid ""
"Since &MCOP; servers will listen on a <acronym>TCP</acronym> port, "
"potentially everybody (if you are on the Internet) may try to connect &MCOP; "
"services. Thus, it is important to authenticate clients. &MCOP; uses the "
"md5-auth protocol."
msgstr ""

#: index.docbook:1196
#, no-c-format
msgid ""
"The md5-auth protocol does the following to ensure that only selected "
"(trusted) clients may connect to a server:"
msgstr ""

#: index.docbook:1201
#, no-c-format
msgid "It assumes you can give every client a secret cookie."
msgstr ""

#: index.docbook:1201
#, no-c-format
msgid ""
"Every time a client connects, it verifies that this client knows that secret "
"cookie, without actually transferring it (not even in a form that somebody "
"listening to the network traffic could find it out)."
msgstr ""

#: index.docbook:1218
#, no-c-format
msgid ""
"To give each client the secret cookie, &MCOP; will (normally) put it in the "
"<filename class=\"directory\">mcop</filename> directory (under <filename "
"class=\"directory\">/tmp/mcop-<envar>USER</envar>/secret-cookie</filename>"
"). Of course, you can copy it to other computers. However, if you do so, use "
"a secure transfer mechanism, such as <command>scp</command> (from "
"<application>ssh</application>)."
msgstr ""

#: index.docbook:1228
#, no-c-format
msgid "The authentication of clients uses the following steps:"
msgstr ""

#: index.docbook:1232
#, no-c-format
msgid "[SERVER] generate a new (random) cookie R"
msgstr ""

#: index.docbook:1232
#, no-c-format
msgid "[SERVER] send it to the client"
msgstr ""

#: index.docbook:1232
#, no-c-format
msgid "[CLIENT] read the \"secret cookie\" S from a file"
msgstr ""

#: index.docbook:1232
#, no-c-format
msgid ""
"[CLIENT] mangle the cookies R and S to a mangled cookie M using the MD5 "
"algorithm"
msgstr ""

#: index.docbook:1232
#, no-c-format
msgid "[CLIENT] send M to the server"
msgstr ""

#: index.docbook:1232
#, no-c-format
msgid ""
"[SERVER] verify that mangling R and S gives just the same thing as the "
"cookie M received from the client. If yes, authentication is successful."
msgstr ""

#: index.docbook:1274
#, no-c-format
msgid "This algorithm should be secure, given that"
msgstr ""

#: index.docbook:1278
#, no-c-format
msgid "The secret cookies and random cookies are <quote>random enough</quote> and"
msgstr ""

#: index.docbook:1278
#, no-c-format
msgid ""
"The MD5 hashing algorithm doesn't allow to find out the <quote>original "
"text</quote>, that is the secret cookie S and the random cookie R (which is "
"known, anyway), from the mangled cookie M."
msgstr ""

#: index.docbook:1295
#, no-c-format
msgid ""
"The &MCOP; protocol will start every new connection with an authentication "
"process. Basically, it looks like this:"
msgstr ""

#: index.docbook:1300
#, no-c-format
msgid ""
"Server sends a ServerHello message, which describes the known authentication "
"protocols."
msgstr ""

#: index.docbook:1300
#, no-c-format
msgid "Client sends a ClientHello message, which includes authentication info."
msgstr ""

#: index.docbook:1300
#, no-c-format
msgid "Server sends an AuthAccept message."
msgstr ""

#: index.docbook:1322
#, no-c-format
msgid ""
"To see that the security actually works, we should look at how messages are "
"processed on unauthenticated connections:"
msgstr ""

#: index.docbook:1327
#, no-c-format
msgid ""
"Before the authentication succeeds, the server will not receive other "
"messages from the connection. Instead, if the server for instance expects a "
"<quote>ClientHello</quote> message, and gets an mcopInvocation message, it "
"will drop the connection."
msgstr ""

#: index.docbook:1327
#, no-c-format
msgid ""
"If the client doesn't send a valid &MCOP; message at all (no &MCOP; magic in "
"the message header) in the authentication phase, but something else, the "
"connection is dropped."
msgstr ""

#: index.docbook:1327
#, no-c-format
msgid ""
"If the client tries to send a very very large message (&gt; 4096 bytes in "
"the authentication phase, the message size is truncated to 0 bytes, which "
"will cause that it isn't accepted for authentication) This is to prevent "
"unauthenticated clients from sending &eg; 100 megabytes of message, which "
"would be received and could cause the server to run out of memory."
msgstr ""

#: index.docbook:1327
#, no-c-format
msgid ""
"If the client sends a corrupt ClientHello message (one, for which "
"demarshalling fails), the connection is dropped."
msgstr ""

#: index.docbook:1327
#, no-c-format
msgid ""
"If the client send nothing at all, then a timeout should occur (to be "
"implemented)."
msgstr ""

#: index.docbook:1374
#, no-c-format
msgid "&MCOP; Protocol Specification"
msgstr ""

#: index.docbook:1377
#, no-c-format
msgid "Introduction"
msgstr "Ukwazisa"

#: index.docbook:1379
#, no-c-format
msgid ""
"It has conceptual similarities to <acronym>CORBA</acronym>, but it is "
"intended to extend it in all ways that are required for real time multimedia "
"operations."
msgstr ""

#: index.docbook:1385
#, no-c-format
msgid ""
"It provides a multimedia object model, which can be used for both: "
"communication between components in one adress space (one process), and "
"between components that are in different threads, processes or on different "
"hosts."
msgstr ""

#: index.docbook:1392
#, no-c-format
msgid ""
"All in all, it will be designed for extremely high performance (so "
"everything shall be optimized to be blazingly fast), suitable for very "
"communicative multimedia applications. For instance streaming videos around "
"is one of the applications of &MCOP;, where most <acronym>CORBA</acronym> "
"implementations would go down to their knees."
msgstr ""

#: index.docbook:1400
#, no-c-format
msgid "The interface definitions can handle the following natively:"
msgstr ""

#: index.docbook:1404
#, no-c-format
msgid "Continous streams of data (such as audio data)."
msgstr ""

#: index.docbook:1404
#, no-c-format
msgid "Event streams of data (such as &MIDI; events)."
msgstr ""

#: index.docbook:1404
#, no-c-format
msgid "Real reference counting."
msgstr ""

#: index.docbook:1424
#, no-c-format
msgid "and the most important <acronym>CORBA</acronym> gimmicks, like"
msgstr ""

#: index.docbook:1428
#, no-c-format
msgid "Synchronous method invocations."
msgstr ""

#: index.docbook:1428
#, no-c-format
msgid "Asynchronous method invocations."
msgstr ""

#: index.docbook:1428
#, no-c-format
msgid "Constructing user defined data types."
msgstr ""

#: index.docbook:1428
#, no-c-format
msgid "Multiple inheritance."
msgstr ""

#: index.docbook:1428
#, no-c-format
msgid "Passing object references."
msgstr ""

#: index.docbook:1463
#, no-c-format
msgid "The &MCOP; Message Marshalling"
msgstr ""

#: index.docbook:1465
#, no-c-format
msgid "Design goals/ideas:"
msgstr ""

#: index.docbook:1469
#, no-c-format
msgid "Marshalling should be easy to implement."
msgstr ""

#: index.docbook:1469
#, no-c-format
msgid "Demarshalling requires the receiver to know what type he wants to demarshall."
msgstr ""

#: index.docbook:1469
#, no-c-format
msgid ""
"The receiver is expected to use every information - so skipping is only in "
"the protocol to a degree that:"
msgstr ""

#: index.docbook:1469
#, no-c-format
msgid ""
"If you know you are going to receive a block of bytes, you don't need to "
"look at each byte for an end marker."
msgstr ""

#: index.docbook:1469
#, no-c-format
msgid ""
"If you know you are going to receive a string, you don't need to read it "
"until the zero byte to find out it's length while demarshalling, however,"
msgstr ""

#: index.docbook:1469
#, no-c-format
msgid ""
"If you know you are going to receive a sequence of strings, you need to look "
"at the length of each of them to find the end of the sequence, as strings "
"have variable length. But if you use the strings for something useful, "
"you'll need to do that anyway, so this is no loss."
msgstr ""

#: index.docbook:1469
#, no-c-format
msgid "As little overhead as possible."
msgstr ""

#: index.docbook:1526
#, no-c-format
msgid "Marshalling of the different types is show in the table below:"
msgstr ""

#: index.docbook:1532
#, no-c-format
msgid "Type"
msgstr "Udidi"

#: index.docbook:1532
#, no-c-format
msgid "Marshalling Process"
msgstr ""

#: index.docbook:1532
#, no-c-format
msgid "Result"
msgstr "Isiphumo"

#: index.docbook:1540
#, no-c-format
msgid "void"
msgstr "engenanto"

#: index.docbook:1540
#, no-c-format
msgid ""
"<type>void</type> types are marshalled by omitting them, so nothing is "
"written to the stream for them."
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "<entry></entry>"
msgstr "<entry></entry>"

#: index.docbook:1540
#, no-c-format
msgid "long"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid ""
"is marshalled as four bytes, the most significant byte first, so the number "
"10001025 (which is 0x989a81) would be marshalled as:"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "0x00 0x98 0x9a 0x81"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "enums"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "are marshalled like <type>long</type>s"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "byte"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "is marshalled as a single byte, so the byte 0x42 would be marshalled as:"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "0x42"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "string"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid ""
"is marshalled as a <type>long</type>"
", containing the length of the following string, and then the sequence of "
"characters strings must end with one zero byte (which is included in the "
"length counting)."
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "include the trailing 0 byte in length counting!"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "<quote>hello</quote> would be marshalled as:"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "0x00 0x00 0x00 0x06 0x68 0x65 0x6c 0x6c 0x6f 0x00"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "boolean"
msgstr "Ingxolo yento yokuxhaswa"

#: index.docbook:1540
#, no-c-format
msgid ""
"is marshalled as a byte, containing 0 if <returnvalue>false</returnvalue>"
" or 1 if <returnvalue>true</returnvalue>, so the boolean value "
"<returnvalue>true</returnvalue> is marshalled as:"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "0x01"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "float"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid ""
"is marshalled after the four byte IEEE754 representation - detailed docs how "
"IEEE works are here: <ulink "
"url=\"http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/n"
"cg_math.doc.html\">"
"http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_mat"
"h.doc.html</ulink> and here: <ulink "
"url=\"http://java.sun.com/docs/books/vmspec/2nd-edition/html/Overview.doc.htm"
"l\">"
"http://java.sun.com/docs/books/vmspec/2nd-edition/html/Overview.doc.html</uli"
"nk>. So, the value 2.15 would be marshalled as:"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "0x9a 0x99 0x09 0x40"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "struct"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid ""
"A structure is marshalled by marshalling it's contents. There are no "
"additional prefixes or suffixes required, so the structure"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid ""
"struct test {\n"
"    string name;        // which is \"hello\"\n"
"    long value;         // which is 10001025  (0x989a81)\n"
"};"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "would be marshalled as"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid ""
"0x00 0x00 0x00 0x06   0x68 0x65 0x6c 0x6c\n"
"0x6f 0x00 0x00 0x98   0x9a 0x81"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid "sequence"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid ""
"a sequence is marshalled by listing the number of elements that follow, and "
"then marshalling the elements one by one."
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid ""
"So a sequence of 3 longs a, with a[0] = 0x12345678, a[1] = 0x01 and a[2] = "
"0x42 would be marshalled as:"
msgstr ""

#: index.docbook:1540
#, no-c-format
msgid ""
"0x00 0x00 0x00 0x03   0x12 0x34 0x56 0x78\n"
"0x00 0x00 0x00 0x01   0x00 0x00 0x00 0x42"
msgstr ""

#: index.docbook:1639
#, no-c-format
msgid ""
"If you need to refer to a type, all primitive types are referred by the "
"names given above. Structures and enums get own names (like Header). "
"Sequences are referred as *<replaceable>normal type</replaceable>"
", so that a sequence of longs is <quote>*long</quote> and a sequence of "
"Header struct's is <quote>*Header</quote>."
msgstr ""

#: index.docbook:1650
#, no-c-format
msgid "Messages"
msgstr "Imiyalezo"

#: index.docbook:1652
#, no-c-format
msgid "The &MCOP; message header format is defined as defined by this structure:"
msgstr ""

#: index.docbook:1657
#, no-c-format
msgid ""
"struct Header {\n"
"    long magic;          // the value 0x4d434f50, which is marshalled as "
"MCOP\n"
"    long messageLength;\n"
"    long messageType;\n"
"};"
msgstr ""

#: index.docbook:1665
#, no-c-format
msgid "The possible messageTypes are currently"
msgstr ""

#: index.docbook:1669
#, no-c-format
msgid ""
"mcopServerHello\t\t= 1\n"
" mcopClientHello\t\t= 2\n"
" mcopAuthAccept\t\t\t= 3\n"
" mcopInvocation\t\t\t= 4\n"
" mcopReturn\t\t\t\t= 5\n"
" mcopOnewayInvocation   = 6"
msgstr ""

#: index.docbook:1678
#, no-c-format
msgid "A few notes about the &MCOP; messaging:"
msgstr ""

#: index.docbook:1683
#, no-c-format
msgid "Every message starts with a Header."
msgstr ""

#: index.docbook:1683
#, no-c-format
msgid ""
"Some messages types should be dropped by the server, as long as the "
"authentication is not complete."
msgstr ""

#: index.docbook:1683
#, no-c-format
msgid ""
"After receiving the header, the protocol (connection) handling can receive "
"the message completely, without looking at the contents."
msgstr ""

#: index.docbook:1705
#, no-c-format
msgid ""
"The messageLength in the header is of course in some cases redundant, which "
"means that this approach is not minimal regarding the number of bytes."
msgstr ""

#: index.docbook:1711
#, no-c-format
msgid ""
"However, it leads to an easy (and fast) implementation of non-blocking "
"messaging processing. With the help of the header, the messages can be "
"received by protocol handling classes in the background (non-blocking), if "
"there are many connections to the server, all of them can be served "
"parallel. You don't need to look at the message content, to receive the "
"message (and to determine when you are done), just at the header, so the "
"code for that is pretty easy."
msgstr ""

#: index.docbook:1721
#, no-c-format
msgid ""
"Once a message is there, it can be demarshalled and processed in one single "
"pass, without caring about cases where not all data may have been received "
"(because the messageLength guarantees that everything is there)."
msgstr ""

#: index.docbook:1731
#, no-c-format
msgid "Invocations"
msgstr ""

#: index.docbook:1733
#, no-c-format
msgid ""
"To call a remote method, you need to send the following structure in the "
"body of an &MCOP; message with the messageType = 1 (mcopInvocation):"
msgstr ""

#: index.docbook:1738
#, no-c-format
msgid ""
"struct Invocation {\n"
"    long objectID;\n"
"    long methodID;\n"
"    long requestID;\n"
"};"
msgstr ""

#: index.docbook:1746
#, no-c-format
msgid ""
"after that, you send the parameters as structure, &eg; if you invoke the "
"method string concat(string s1, string s2), you send a structure like"
msgstr ""

#: index.docbook:1751
#, no-c-format
msgid ""
"struct InvocationBody {\n"
"    string s1;\n"
"    string s2;\n"
"};"
msgstr ""

#: index.docbook:1759
#, no-c-format
msgid ""
"if the method was declared to be oneway - that means asynchronous without "
"return code - then that was it. Otherwise, you'll receive as answer the "
"message with messageType = 2 (mcopReturn)"
msgstr ""

#: index.docbook:1765
#, no-c-format
msgid ""
"struct ReturnCode {\n"
"    long requestID;\n"
"    &lt;resulttype&gt; result;\n"
"};"
msgstr ""

#: index.docbook:1773
#, no-c-format
msgid ""
"where &lt;resulttype&gt; is the type of the result. As void types are "
"omitted in marshalling, you can also only write the requestID if you return "
"from a void method."
msgstr ""

#: index.docbook:1779
#, no-c-format
msgid "So our string concat(string s1, string s2) would lead to a returncode like"
msgstr ""

#: index.docbook:1784
#, no-c-format
msgid ""
"struct ReturnCode {\n"
"    long   requestID;\n"
"    string result;\n"
"};"
msgstr ""

#: index.docbook:1794
#, no-c-format
msgid "Inspecting Interfaces"
msgstr ""

#: index.docbook:1796
#, no-c-format
msgid ""
"To do invocations, you need to know the methods an object supports. To do "
"so, the methodID 0, 1, 2 and 3 are hardwired to certain functionalities. "
"That is"
msgstr ""

#: index.docbook:1802
#, no-c-format
msgid ""
"long _lookupMethod(MethodDef methodDef);\t\t\t\t// methodID always 0\n"
"string _interfaceName();\t\t\t\t\t\t\t\t// methodID always 1\n"
"InterfaceDef _queryInterface(string name);\t\t\t\t// methodID always 2\n"
"TypeDef _queryType(string name);\t\t\t\t\t\t// methodID always 3"
msgstr ""

#: index.docbook:1809
#, no-c-format
msgid "to read that, you of course need also"
msgstr ""

#: index.docbook:1813
#, no-c-format
msgid ""
"struct MethodDef {\n"
"\tstring  methodName;\n"
"\tstring  type;\n"
"\tlong    flags;        // set to 0 for now (will be required for "
"streaming)\n"
"\tsequence&lt;ParamDef&gt; signature;\n"
"};\n"
"\n"
"struct ParamDef {\n"
"\tstring name;\n"
"\tlong   typeCode;\n"
"};"
msgstr ""

#: index.docbook:1827
#, no-c-format
msgid ""
"the parameters field contains type components which specify the types of the "
"parameters. The type of the returncode is specified in the MethodDef's type "
"field."
msgstr ""

#: index.docbook:1833
#, no-c-format
msgid ""
"Strictly speaking, only the methods <methodname>_lookupMethod()</methodname>"
" and <methodname>_interfaceName()</methodname>"
" differ from object to object, while the "
"<methodname>_queryInterface()</methodname> and "
"<methodname>_queryType()</methodname> are always the same."
msgstr ""

#: index.docbook:1841
#, no-c-format
msgid ""
"What are those methodIDs? If you do an &MCOP; invocation, you are expected "
"to pass a number for the method you are calling. The reason for that is, "
"that numbers can be processed much faster than strings when executing an "
"&MCOP; request."
msgstr ""

#: index.docbook:1848
#, no-c-format
msgid ""
"So how do you get those numbers? If you know the signature of the method, "
"that is a MethodDef that describes the method, (which contains name, type, "
"parameter names, parameter types and such), you can pass that to "
"_lookupMethod of the object where you wish to call a method. As "
"_lookupMethod is hardwired to methodID 0, you should encounter no problems "
"doing so."
msgstr ""

#: index.docbook:1857
#, no-c-format
msgid ""
"On the other hand, if you don't know the method signature, you can find "
"which methods are supported by using _interfaceName, _queryInterface and "
"_queryType."
msgstr ""

#: index.docbook:1865
#, no-c-format
msgid "Type Definitions"
msgstr ""

#: index.docbook:1867
#, no-c-format
msgid ""
"User defined datatypes are described using the "
"<structname>TypeDef</structname> structure:"
msgstr ""

#: index.docbook:1872
#, no-c-format
msgid ""
"struct TypeComponent {\n"
"\tstring type;\n"
"\tstring name;\n"
"};\n"
"\n"
"struct TypeDef {\n"
"\tstring name;\n"
"\n"
"\tsequence&lt;TypeComponent&gt; contents;\n"
"};"
msgstr ""

#: index.docbook:1889
#, no-c-format
msgid "Why &arts; Doesn't Use &DCOP;"
msgstr ""

#: index.docbook:1891
#, no-c-format
msgid ""
"Since &kde; dropped <acronym>CORBA</acronym>"
" completely, and is using &DCOP; everywhere instead, naturally the question "
"arises why &arts; isn't doing so. After all, &DCOP; support is in "
"<classname>KApplication</classname>, is well-maintained, supposed to "
"integrate greatly with libICE, and whatever else."
msgstr ""

#: index.docbook:1899
#, no-c-format
msgid ""
"Since there will be (potentially) a lot of people asking whether having "
"&MCOP; besides &DCOP; is really necessary, here is the answer. Please don't "
"get me wrong, I am not trying to say <quote>&DCOP; is bad</quote>"
". I am just trying to say <quote>&DCOP; isn't the right solution for "
"&arts;</quote> (while it is a nice solution for other things)."
msgstr ""

#: index.docbook:1908
#, no-c-format
msgid ""
"First, you need to understand what exactly &DCOP; was written for. Created "
"in two days during the &kde;-TWO meeting, it was intended to be as simple as "
"possible, a really <quote>lightweight</quote> communication protocol. "
"Especially the implementation left away everything that could involve "
"complexity, for instance a full blown concept how data types shall be "
"marshalled."
msgstr ""

#: index.docbook:1917
#, no-c-format
msgid ""
"Even although &DCOP; doesn't care about certain things (like: how do I send "
"a string in a network-transparent manner?) - this needs to be done. So, "
"everything that &DCOP; doesn't do, is left to &Qt; in the &kde; apps that "
"use &DCOP; today. This is mostly type management (using the &Qt; "
"serialization operator)."
msgstr ""

#: index.docbook:1925
#, no-c-format
msgid ""
"So &DCOP; is a minimal protocol which perfectly enables &kde; applications "
"to send simple messages like <quote>open a window pointing to "
"http://www.kde.org</quote> or <quote>your configuration data has "
"changed</quote>. However, inside &arts; the focus lies on other things."
msgstr ""

#: index.docbook:1932
#, no-c-format
msgid ""
"The idea is, that little plugins in &arts; will talk involving such data "
"structures as <quote>midi events</quote> and <quote>songposition "
"pointers</quote> and <quote>flow graphs</quote>."
msgstr ""

#: index.docbook:1938
#, no-c-format
msgid ""
"These are complex data types, which must be sent between different objects, "
"and be passed as streams, or parameters. &MCOP; supplies a type concept, to "
"define complex data types out of simpler ones (similar to structs or arrays "
"in C++). &DCOP; doesn't care about types at all, so this problem would be "
"left to the programmer - like: writing C++ classes for the types, and make "
"sure they can serialize properly (for instance: support the &Qt; streaming "
"operator)."
msgstr ""

#: index.docbook:1948
#, no-c-format
msgid ""
"But that way, they would be inaccessible to everything but direct C++ "
"coding. Specifically, you could not design a scripting language, that would "
"know all types plugins may ever expose, as they are not self describing."
msgstr ""

#: index.docbook:1955
#, no-c-format
msgid ""
"Much the same argument is valid for interfaces as well. &DCOP; objects don't "
"expose their relationships, inheritance hierarchies, etc. - if you were to "
"write an object browser which shows you <quote>what attributes has this "
"object got</quote>, you'd fail."
msgstr ""

#: index.docbook:1963
#, no-c-format
msgid ""
"While Matthias told me that you have a special function "
"<quote>functions</quote> on each object that tells you about the methods "
"that an object supports, this leaves out things like attributes "
"(properties), streams and inheritance relations."
msgstr ""

#: index.docbook:1970
#, no-c-format
msgid ""
"This seriously breaks applications like &artsbuilder;. But remember: &DCOP; "
"was not so much intended to be an object model (as &Qt; already has one with "
"<application>moc</application> and similar), nor to be something like "
"<acronym>CORBA</acronym>, but to supply inter-application communication."
msgstr ""

#: index.docbook:1978
#, no-c-format
msgid ""
"Why &MCOP; even exists is: it should work fine with streams between objects. "
"&arts; makes heavily use of small plugins, which interconnect themselves "
"with streams. The <acronym>CORBA</acronym> version of &arts; had to "
"introduce a very annoying split between <quote>the SynthModule "
"objects</quote>, which were the internal work modules that did do the "
"streaming, and <quote>the <acronym>CORBA</acronym> interface</quote>, which "
"was something external."
msgstr ""

#: index.docbook:1988
#, no-c-format
msgid ""
"Much code cared about making interaction between <quote>the SynthModule "
"objects</quote> and <quote>the <acronym>CORBA</acronym> interface</quote> "
"look natural, but it didn't, because <acronym>CORBA</acronym> knew nothing "
"at all about streams. &MCOP; does. Look at the code (something like "
"<filename>simplesoundserver_impl.cc</filename>). Way better! Streams can be "
"declared in the interface of modules, and implemented in a natural looking "
"way."
msgstr ""

#: index.docbook:1999
#, no-c-format
msgid ""
"One can't deny it. One of the reasons why I wrote &MCOP; was speed. Here are "
"some arguments why &MCOP; will definitely be faster than &DCOP; (even "
"without giving figures)."
msgstr ""

#: index.docbook:2006
#, no-c-format
msgid "An invocation in &MCOP; will have a six-<quote>long</quote>-header. That is:"
msgstr ""

#: index.docbook:2011
#, no-c-format
msgid "magic <quote>MCOP</quote>"
msgstr ""

#: index.docbook:2011
#, no-c-format
msgid "message type (invocation)"
msgstr ""

#: index.docbook:2011
#, no-c-format
msgid "size of the request in bytes"
msgstr ""

#: index.docbook:2011
#, no-c-format
msgid "request ID"
msgstr ""

#: index.docbook:2011
#, no-c-format
msgid "target object ID"
msgstr ""

#: index.docbook:2011
#, no-c-format
msgid "target method ID"
msgstr ""

#: index.docbook:2020
#, no-c-format
msgid ""
"After that, the parameters follow. Note that the demarshalling of this is "
"extremely fast. You can use table lookups to find the object and the method "
"demarshalling function, which means that complexity is O(1) [ it will take "
"the same amount of time, no matter how many objects are alive, or how many "
"functions are there ]."
msgstr ""

#: index.docbook:2028
#, no-c-format
msgid "Comparing this to &DCOP;, you'll see, that there are at least"
msgstr ""

#: index.docbook:2032
#, no-c-format
msgid "a string for the target object - something like <quote>myCalculator</quote>"
msgstr ""

#: index.docbook:2032
#, no-c-format
msgid "a string like <quote>addNumber(int,int)</quote> to specify the method"
msgstr ""

#: index.docbook:2032
#, no-c-format
msgid ""
"several more protocol info added by libICE, and other DCOP specifics I don't "
"know"
msgstr ""

#: index.docbook:2041
#, no-c-format
msgid ""
"These are much more painful to demarshall, as you'll need to parse the "
"string, search for the function, &etc;."
msgstr ""

#: index.docbook:2046
#, no-c-format
msgid ""
"In &DCOP;, all requests are running through a server "
"(<application>DCOPServer</application>). That means, the process of a "
"synchronous invocation looks like this:"
msgstr ""

#: index.docbook:2052 index.docbook:2091
#, no-c-format
msgid "Client process sends invocation."
msgstr ""

#: index.docbook:2052
#, no-c-format
msgid ""
"<application>DCOPserver</application> (man-in-the-middle) receives "
"invocation and looks where it needs to go, and sends it to the "
"<quote>real</quote> server."
msgstr ""

#: index.docbook:2052 index.docbook:2091
#, no-c-format
msgid "Server process receives invocation, performs request and sends result."
msgstr ""

#: index.docbook:2052
#, no-c-format
msgid ""
"<application>DCOPserver</application> (man-in-the-middle) receives result "
"and ... sends it to the client."
msgstr ""

#: index.docbook:2052 index.docbook:2091
#, no-c-format
msgid "Client decodes reply."
msgstr ""

#: index.docbook:2087
#, no-c-format
msgid "In &MCOP;, the same invocation looks like this:"
msgstr ""

#: index.docbook:2111
#, no-c-format
msgid ""
"Say both were implemented correctly, &MCOP;s peer-to-peer strategy should be "
"faster by a factor of two, than &DCOP;s man-in-the-middle strategy. Note "
"however that there were of course reasons to choose the &DCOP; strategy, "
"which is namely: if you have 20 applications running, and each app is "
"talking to each app, you need 20 connections in &DCOP;, and 200 with &MCOP;. "
"However in the multimedia case, this is not supposed to be the usual setting."
msgstr ""

#: index.docbook:2121
#, no-c-format
msgid ""
"I tried to compare &MCOP; and &DCOP;, doing an invocation like adding two "
"numbers. I modified testdcop to achieve this. However, the test may not have "
"been precise on the &DCOP; side. I invoked the method in the same process "
"that did the call for &DCOP;, and I didn't know how to get rid of one "
"debugging message, so I used output redirection."
msgstr ""

#: index.docbook:2129
#, no-c-format
msgid ""
"The test only used one object and one function, expect &DCOP;s results to "
"decrease with more objects and functions, while &MCOP;s results should stay "
"the same. Also, the <application>dcopserver</application> process wasn't "
"connected to other applications, it might be that if many applications are "
"connected, the routing performance decreases."
msgstr ""

#: index.docbook:2137
#, no-c-format
msgid ""
"The result I got was that while &DCOP; got slightly more than 2000 "
"invocations per second, &MCOP; got slightly more than 8000 invocations per "
"second. That makes a factor of 4. I know that &MCOP; isn't tuned to the "
"maximum possible, yet. (Comparision: <acronym>CORBA</acronym>, as "
"implemented with mico, does something between 1000 and 1500 invocations per "
"second)."
msgstr ""

#: index.docbook:2146
#, no-c-format
msgid ""
"If you want <quote>harder</quote> data, consider writing some small "
"benchmark app for &DCOP; and send it to me."
msgstr ""

#: index.docbook:2151
#, no-c-format
msgid ""
"<acronym>CORBA</acronym>"
" had the nice feature that you could use objects you implemented once, as "
"<quote>seperate server process</quote>, or as <quote>library</quote>. You "
"could use the same code to do so, and <acronym>CORBA</acronym> would "
"transparently descide what to do. With &DCOP;, that is not really intended, "
"and as far as I know not really possible."
msgstr ""

#: index.docbook:2160
#, no-c-format
msgid ""
"&MCOP; on the other hand should support that from the beginning. So you can "
"run an effect inside &artsd;. But if you are a wave editor, you can choose "
"to run the same effect inside your process space as well."
msgstr ""

#: index.docbook:2166
#, no-c-format
msgid ""
"While &DCOP; is mostly a way to communicate between apps, &MCOP; is also a "
"way to communicate inside apps. Especially for multimedia streaming, this is "
"important (as you can run multiple &MCOP; objects parallely, to solve a "
"multimedia task in your application)."
msgstr ""

#: index.docbook:2173
#, no-c-format
msgid ""
"Although &MCOP; does not currently do so, the possibilities are open to "
"implement quality of service features. Something like <quote>that &MIDI; "
"event is really really important, compared to this invocation</quote>. Or "
"something like <quote>needs to be there in time</quote>."
msgstr ""

#: index.docbook:2180
#, no-c-format
msgid ""
"On the other hand, stream transfer can be integrated in the &MCOP; protocol "
"nicely, and combined with <acronym>QoS</acronym> stuff. Given that the "
"protocol may be changed, &MCOP; stream transfer should not really get slower "
"than conventional <acronym>TCP</acronym> streaming, but: it will be easier "
"and more consistent to use."
msgstr ""

#: index.docbook:2188
#, no-c-format
msgid ""
"There is no need to base a middleware for multimedia on &Qt;. Deciding so, "
"and using all that nice &Qt;-streaming and stuff, will easily lead to the "
"middleware becoming a &Qt;-only (or rather &kde;-only) thing. I mean: as "
"soon as I'll see the GNOMEs using &DCOP;, too, or something like that, I am "
"certainly proven wrong."
msgstr ""

#: index.docbook:2196
#, no-c-format
msgid ""
"While I do know that &DCOP; basically doesn't know about the data types it "
"sends, so that you could use &DCOP; without using &Qt;, look at how it is "
"used in daily &kde; usage: people send types like "
"<classname>QString</classname>, <classname>QRect</classname>, "
"<classname>QPixmap</classname>, <classname>QCString</classname>, ..., "
"around. These use &Qt;-serialization. So if somebody choose to support "
"&DCOP; in a GNOME program, he would either have to claim to use "
"<classname>QString</classname>,... types (although he doesn't do so), and "
"emulate the way &Qt; does the streaming, or he would send other string, "
"pixmap and rect types around, and thus not be interoperable."
msgstr ""

#: index.docbook:2209
#, no-c-format
msgid ""
"Well, whatever. &arts; was always intended to work with or without &kde;, "
"with or without &Qt;, with or without X11, and maybe even with or without "
"&Linux; (and I have even no problems with people who port it to a popular "
"non-free operating systems)."
msgstr ""

#: index.docbook:2216
#, no-c-format
msgid ""
"It is my position that non-&GUI;-components should be written "
"non-&GUI;-dependant, to make sharing those among wider amounts of developers "
"(and users) possible."
msgstr ""

#: index.docbook:2222
#, no-c-format
msgid ""
"I see that using two <acronym>IPC</acronym> protocols may cause "
"inconveniences. Even more, if they are both non-standard. However, for the "
"reasons given above, switching to &DCOP; is no option. If there is "
"significant interest to find a way to unite the two, okay, we can try. We "
"could even try to make &MCOP; speak <acronym>IIOP</acronym>, then we'd have "
"a <acronym>CORBA</acronym> <acronym>ORB</acronym> ;)."
msgstr ""

#: index.docbook:2231
#, no-c-format
msgid ""
"I talked with Matthias Ettrich a bit about the future of the two protocols, "
"and we found lots of ways how things could go on. For instance, &MCOP; could "
"handle the message communication in &DCOP;, thus bringing the protocols a "
"bit closer together."
msgstr ""

#: index.docbook:2238
#, no-c-format
msgid "So some possible solutions would be:"
msgstr ""

#: index.docbook:2242
#, no-c-format
msgid ""
"Write an &MCOP; - &DCOP; gateway (which should be possible, and would make "
"interoperation possible) - note: there is an experimental prototype, if you "
"like to work on that."
msgstr ""

#: index.docbook:2242
#, no-c-format
msgid ""
"Integrate everything &DCOP; users expect into &MCOP;, and try to only do "
"&MCOP; - one could add an <quote>man-in-the-middle-option</quote>"
" to &MCOP;, too ;)"
msgstr ""

#: index.docbook:2242
#, no-c-format
msgid ""
"Base &DCOP; on &MCOP; instead of libICE, and slowly start integrating things "
"closer together."
msgstr ""

#: index.docbook:2267
#, no-c-format
msgid ""
"However, it may not be the worst possibility to use each protocol for "
"everything it was intended for (there are some big differences in the design "
"goals), and don't try to merge them into one."
msgstr ""
