1
------------------------------------------------------------------------
4
(edi-28): Extending the EIAM command set to allow writing standalone ECI
6
- submitted: kaiv, 29.09.2002
7
- initial implmementation: kaiv, 05.10.2002
8
- done: kaiv, 29.10.2002
10
------------------------------------------------------------------------
14
- currently all ECI implementations depend on libecasound (either
15
or directly or indirectly) and are thus susceptible to
16
library versioning conflicts
17
- a standalone implementation would not depend on ecasound
18
libraries in any way, which again would greatly improve
19
user-friendliness of ECI apps (easier installation, fewer
20
problems with libraries, etc, etc)
21
- list of goals/requirements that should be reached
22
- a reference standalone ECI implementation in some language
24
- EIAM commands for selecting the ecasound return value
25
syntax -> either normal (current) or one matching the
26
the NetECI wire-syntax
28
- new EIAM commands are needed to make it possible to
30
- redirecting all iactive mode prompt to stderr (solved
32
- adding 'e' and '-' return types to eca-control and
34
- making eca-control create the output differently in
35
wellformed and normal modes (1. whether to add
36
a type prefix, 2. whether to print empty replies
37
and 3. how to print errors)
38
- reference C implementation (libecasoundc)
39
- document the use of ECASOUND environment variable
41
------------------------------------------------------------------------
42
[kaiv on ecasound-list, 28.09.2002]
44
Tkeca-0.2.1, which btw is a really usable app, uses ecasound by forking
45
the console interface on the background and then piping commands and
46
replies via stdin and stdout.
48
Compared to using ECI or directly linking against libecasound, this
49
approach has the huge benefit of complete independence from ecasound
50
libraries. In practice, just by renaming the ecasound executable (or
51
changing PATH), I can select between ecasound 2.0.4 and 2.1dev12 (CVS).
52
Tkeca-0.2.1 works nicely with both versions!
54
Now what if all ECI apps would use the same mechanism? This could be
55
achieved by making a new C-implementation of the ECI API, which would do:
57
- fork "ecasound -c" to the background
58
- pass ECI commands to the ecasound instance via its stdin
59
- read the return codes from ecasound's stdout, parse them and
60
pass them to the ECI app
62
... that's about it. The C++, Python, Perl and PHP ECI implementations
63
could either use the C implementation or alternatively provide their own
64
implementation. For instance, a Python ECI implementation could be
65
written totally in Python. This means that no extension modules would
66
need to installed. Just a Python interpreter and the ecasound executable
69
------------------------------------------------------------------------
70
[kaiv on ecasound-list, 01.10.2002]
72
One of the best alternatives I've come up with so far is reusing the
73
NetECI protocol wire format:
78
There would be a new ecasound command for enabling
79
a parser-friendly output mode (for instance 'int-output-eci').
82
[2. well-formed stdout messages]
84
Once 'int-output-eci' is issued, all output from libecasound
85
to stdout will adhere to the following format:
87
"<loglevel> <msg-size><crlf><msg><crlf><crlf>"
89
Different types of messages already all have a different loglevel
90
associacated with them. For instance when setting ecasound's debug level
91
(with -d:x), you're actually setting a mask specifying which loglevels to
94
Example: "16 10\r\nMy message". Ie. "My message" (length=10) was sent with
100
One loglevel would be allocated to command return values. These messages
101
would adhere to the following format, which is an extension of the
102
message format in the NetECI protocol:
104
"<ECI-loglevel> <status-code> <return-type> <msg-size><crlf><msg><crlf><crlf>"
106
Example (response to 'c-selected'): "64 100 s 7\r\ndefault\r\n\r\n". Ie.
107
the response was "default" (length=7), response type s=string, status
108
100=ok and it was sent with loglevel 64.
112
With this new output mode, it should be quite easy to reliably parse
113
ecasound's output. Just issue a command and then read log messages until
114
you encounter the next message with eci-loglevel. The msg 'status-code'
115
will indicate whether the command succeeded or not. 'return-type' and
116
'msg-size' will help in parsing the actual message contents (and to find
117
the next well-formed message).
119
In addition to making parsing easier, the line-feeds (crlf) also serve as
120
a mechanism to recover from errors (parser receives an invalid message and
121
does not know where the next message starts ==> search for an empty line
122
to find a possible new well-formed message).
124
------------------------------------------------------------------------
125
[kaiv on ecasound-list, 02.10.2002]
127
1. Enabling the well-formed mode
129
The new log message mode can be enabled with the new
130
"int-output-mode-wellformed" EIAM command.
132
2. Syntax of well-format log messages
134
I've added the below documentation to Ecasound Programmer's Guide:
137
By issuing the EIAM command ``int-output-mode-wellformed'',
138
ecasound will start printing all messages using the following
141
<message> = <loglevel><sp><msgsize>(<genmsg> | <returnmsg>)
143
<loglevel> = <integer> ; loglevel number
144
<msgsize = <integer> ; size of content in octets
145
<genmsg> = <contentblock> ; generic log message
146
<returnmsg> = <sp><returntype><contentblock>
147
; EIAM return value message
148
<contentblock> = <crlf><content><crlf><crlf>
149
; actual content of the message
150
<returntype> = ``i'' | ``li'' | ``f'' | ``s''�| ``S'' | ``e''
151
; type of the return value (see ECI/EIAM docs)
152
<content> = *<octet> ; zero or more octets of message content
155
<octet> = 0x00-0xff ; 8bits of data
156
<crlf> = <cr><lf> ; new line
157
<cr> = 0x0d ; carriage return
158
<lf> = 0x0a ; line feed
159
<integer> = +<digit> ; one or more digits
160
<digit> = 0x30-0x39 ; digits 0-9
163
3. Loglevel for ECI/EIAM return values
165
I've assigned value 256 (0x100) for the return value messages. As an
169
ecasound ('h' for help)> int-output-mode-wellformed
170
ecasound ('h' for help)> cs-is-valid
174
ecasound ('h' for help)> cs-selected
180
256 = loglevel for the return-type messages
181
1 = length of content is 1 octet
182
i = return value is an integer
183
1 = the content (boolean one, ie. cs-is-valid returned true)
184
<crlf> = an empty line ends the message
187
That's about it I think. Now it should be possible to write a native,
188
standalone ECI implementation in any language that supports launching
189
external apps (ie. forking) and using pipes to communicate with the
192
PS If this turns out to work ok, I might also add this functionality
193
to the 2.x tree (-> 2.0.5 release).
195
------------------------------------------------------------------------
b'\\ No newline at end of file'
added
removed
Documentation/archived/edi-28.txt
