/[svn]/liblscp/trunk/doc/reference.dox
ViewVC logotype

Annotation of /liblscp/trunk/doc/reference.dox

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2468 - (hide annotations) (download)
Mon Sep 9 20:54:28 2013 UTC (8 years, 11 months ago) by capela
File size: 12436 byte(s)
- Lame docx typo fixing.
1 capela 103 /**
2    
3     @mainpage liblscp
4    
5    
6     @section Intro
7    
8     Hi all,
9    
10     On the path to a GUI for linuxsampler, I've been taking some of my spare
11     time by writing an early implementation for the LSCP (the LinuxSampler
12     Control Protocol), as defined from the current available draft document
13 capela 213 (http://www.linuxsampler.org/api/draft-linuxsampler-protocol.html).
14 capela 103
15     My implementation, while still rather crude, is taking the form of a
16     programming library for plain conventional C, codenamed liblscp.
17    
18     One of my objectives is that liblscp evolves as the implementation for a
19     linuxsampler API, while being a fair abstraction for the network and/or
20     IPC aspects of LSCP.
21    
22     For the facts, liblscp is actually a wrapper for the LSCP specification,
23     taking all the TCP/UDP socket communication into it's main control, hiding
24     all or some of the protocol bureoucracy from the user and exposing a
25     simple and opaque C programming language interface, mainly by mapping
26     events to user function callback handlers.
27    
28     The design of liblscp assumed that the programming interface provided is
29     useable and applicable either for server (linuxsampler itself) and/or
30     client (gui's) development.
31    
32     Some design features (no rocket-sci here :)
33    
34     - Multi-threaded or multiplexed server; clients block for synchronous
35     request calls.
36     - Multi-client; one server instance serves many clients, local and/or
37     remote.
38     - Server events broadcasted and delivered to client callbacks.
39     - Client requests processed on server supplied callback.
40    
41     Please note that (as usual :) documentation is none at this stage but I'll
42     challenge you to look at the source code provided on the tarball below. A
43     barebones server and client test programs are included (lscp_server_test
44     and lscp_client_test).
45    
46    
47     @section Client
48    
49     As a quick reference for the client programming, one links to liblscp to
50     create a client instance handle, just like this:<pre>
51    
52     #include <lscp/@ref:client.h>
53    
54     @ref lscp_client_t *client;
55    
56     client = @ref lscp_client_create (server_host, server_port,
57     client_callback, client_data);
58    
59     </pre>where server_host is the hostname of the server we wish to connect, and
60     server_port is the respective port number; client_callback is the client
61     supplied callback function that will handle every server notification
62     event; client_data is intended for client context and will be fed to
63     client_callback without intervention.
64    
65     The client may issue a request to server by use of:<pre>
66    
67     @ref lscp_client_query (client, query);
68    
69     </pre>where you'll submit a single command to the server and wait for it's response.
70     The query string must be null terminated. The server response result maybe
71     retrieved by:<pre>
72    
73     char *result;
74    
75     result = @ref lscp_client_get_result(client);
76    
77     </pre>and the eventual error status code:<pre>
78    
79     int errno;
80    
81     errno = @ref lscp_client_get_errno(client);
82    
83     </pre>The client callback function must have the following prototype (@ref lscp_client_proc_t):
84    
85     - @ref lscp_status_t <i>client_callback</i> ( @ref lscp_client_t *client,
86 capela 156 @ref lscp_event_t event, const char *buf, int buflen, void *client_data );
87 capela 103
88 capela 156 where event is the specific event type notification, buf will be a pointer to
89     the event text which is buflen bytes in length; client_data is exactly the same
90     value given on @ref lscp_client_create call.
91 capela 103
92     This callback function is the place to handle all server notifications and
93     will be only called if the client is currently subscribed. No response
94     from the client is expected while processing an event within
95     client_callback.
96    
97 capela 156 A client subscribes to receive event notifications by calling:<pre>
98 capela 103
99 capela 156 @ref lscp_client_subscribe (client, events);
100 capela 103
101     </pre>after which it will start receiving events by means of the supplied
102     client_callback function. To unsubscribe and stop this deliverance:<pre>
103    
104 capela 156 @ref lscp_client_unsubscribe (client, events);
105 capela 103
106     </pre>Finally, when a client is about to quit, the proper terminator is in order:<pre>
107    
108     @ref lscp_client_destroy (client);
109    
110 capela 188 </pre>As for the current protocol draft (11), the client interface already maps
111     the following functions defined in <lscp/@ref:client.h>, one for each corresponding
112     LSCP comand, and regarding the sampler channel space:<pre>
113 capela 103
114     @ref lscp_get_available_engines (client);
115 capela 562 @ref lscp_list_available_engines (client);
116 capela 103 @ref lscp_get_engine_info (client, engine_name);
117     @ref lscp_get_channels (client);
118 capela 562 @ref lscp_list_channels (client);
119 capela 103 @ref lscp_add_channel (client);
120     @ref lscp_load_engine (client, engine_name, channel);
121 capela 156 @ref lscp_set_channel_audio_device (client, channel, audio_device);
122 capela 103 @ref lscp_set_channel_audio_type (client, channel, audio_type);
123 capela 156 @ref lscp_set_channel_audio_channel (client, channel, audio_in, audio_out);
124     @ref lscp_set_channel_midi_device (client, channel, midi_device);
125     @ref lscp_set_channel_midi_type (client, channel, midi_type);
126     @ref lscp_set_channel_midi_port (client, channel, midi_port);
127 capela 103 @ref lscp_set_channel_midi_channel (client, channel, midi_channel);
128 capela 975 @ref lscp_set_channel_midi_map (client, channel, midi_map);
129 capela 735 @ref lscp_set_channel_mute (client, channel, mute);
130     @ref lscp_set_channel_solo (client, channel, solo);
131 capela 103 @ref lscp_set_channel_volume (client, channel, volume);
132     @ref lscp_load_instrument (client, file_name, instr_index, channel);
133 capela 156 @ref lscp_load_instrument_non_modal (client, file_name, instr_index, channel);
134 capela 103 @ref lscp_get_channel_info (client, channel);
135     @ref lscp_get_channel_voice_count (client, channel);
136     @ref lscp_get_channel_stream_count (client, channel);
137     @ref lscp_get_channel_buffer_fill (client, usage_type, channel);
138     @ref lscp_reset_channel (client, channel);
139     @ref lscp_remove_channel (client, channel);
140 capela 213 @ref lscp_reset_sampler (client);
141 capela 564 @ref lscp_get_server_info (client);
142 capela 946 @ref lscp_get_server_info (client);
143     @ref lscp_get_total_voice_count (client);
144     @ref lscp_get_total_voice_count_max (client);
145 capela 1019 @ref lscp_get_volume (client);
146     @ref lscp_set_volume (client);
147 capela 103
148 capela 1019 </pre>Specific for sampler channel effect sends control:<pre>
149    
150     @ref lscp_create_fxsend (client, channel, midi_controller, name);
151     @ref lscp_destroy_fxsend (client, channel, fxsend);
152     @ref lscp_get_fxsends (client, channel);
153     @ref lscp_list_fxsends (client, channel);
154     @ref lscp_get_fxsend_info (client, channel, fxsend);
155 schoenebeck 1665 @ref lscp_set_fxsend_name (client, channel, fxsend, name);
156 capela 1031 @ref lscp_set_fxsend_midi_controller (client, channel, fxsend, midi_controller);
157 capela 1019 @ref lscp_set_fxsend_audio_channel (client, channel, fxsend, audio_src, audio_dst);
158 capela 1031 @ref lscp_set_fxsend_level (client, channel, fxsend, level);
159 capela 1019
160 capela 946 </pre>Specific to MIDI instrument mapping interface:<pre>
161    
162 capela 975 @ref lscp_add_midi_instrument_map (client, map_name);
163     @ref lscp_remove_midi_instrument_map (client, midi_map);
164     @ref lscp_get_midi_instrument_maps (client);
165     @ref lscp_list_midi_instrument_maps (client);
166     @ref lscp_get_midi_instrument_map_name (client, midi_map);
167     @ref lscp_set_midi_instrument_map_name (client, midi_map, map_name);
168 capela 946 @ref lscp_map_midi_instrument (client, midi_instr, engine_name, file_name, instr_index, volume, load_mode, name);
169     @ref lscp_unmap_midi_instrument (client, midi_instr);
170 capela 975 @ref lscp_get_midi_instruments (client, midi_map);
171     @ref lscp_list_midi_instruments (client, midi_map);
172 capela 946 @ref lscp_get_midi_instrument_info (client, midi_instr);
173 capela 975 @ref lscp_clear_midi_instruments (client, midi_map);
174 capela 946
175 capela 188 </pre>For the audio output and MIDI input device configuration interface,
176     the following functions are respectively defined in <lscp/@ref:device.h>:<pre>
177    
178     @ref lscp_get_available_audio_drivers (client);
179 capela 562 @ref lscp_list_available_audio_drivers (client);
180 capela 188 @ref lscp_get_audio_driver_info (client, audio_driver);
181     @ref lscp_get_audio_driver_param_info (client, audio_driver, param_key, deplist);
182     @ref lscp_create_audio_device (client, audio_driver, params);
183     @ref lscp_destroy_audio_device (client, audio_device);
184     @ref lscp_get_audio_devices (client);
185     @ref lscp_list_audio_devices (client);
186     @ref lscp_get_audio_device_info (client, audio_device);
187     @ref lscp_set_audio_device_param (client, audio_device, param);
188     @ref lscp_get_audio_channel_info (client, audio_device, audio_channel);
189     @ref lscp_get_audio_channel_param_info (client, audio_device, audio_channel, param);
190     @ref lscp_set_audio_channel_param (client, audio_device, audio_channel, param);
191    
192     @ref lscp_get_available_midi_drivers (client);
193 capela 562 @ref lscp_list_available_midi_drivers (client);
194 capela 188 @ref lscp_get_midi_driver_info (client, midi_driver);
195     @ref lscp_get_midi_driver_param_info (client, midi_driver, param_key, deplist);
196     @ref lscp_create_midi_device (client, midi_driver, params);
197     @ref lscp_destroy_midi_device (client, midi_device);
198     @ref lscp_get_midi_devices (client);
199     @ref lscp_list_midi_devices (client);
200     @ref lscp_get_midi_device_info (client, midi_device);
201     @ref lscp_set_midi_device_param (client, midi_device, param);
202     @ref lscp_get_midi_port_info (client, midi_device, midi_port);
203     @ref lscp_get_midi_port_param_info (client, midi_device, midi_port, param);
204     @ref lscp_set_midi_port_param (client, midi_device, midi_port, param);
205    
206 schoenebeck 1365 </pre>For editing instruments while playing them with the sampler:<pre>
207    
208 capela 1412 @ref lscp_edit_channel_instrument (client, channel);
209 schoenebeck 1365
210 capela 188 </pre>Most of these functions are wrappers to @ref lscp_client_query, and some will handle
211 capela 103 and change the result string accordingly.
212    
213    
214     @section Server
215    
216     Likewise, and least important yet as for server programming, you create a server
217     instance handle just like that:<pre>
218    
219     #include <lscp/@ref:server.h>
220    
221     @ref lscp_server_t *server;
222    
223     server = @ref lscp_server_create (server_port, server_callback, server_data);
224    
225     </pre>where server_port is the port number where the server will be
226     listening for connections; server_callback is the server supplied
227     callback function that will handle every client request; server_data is
228     any reference to data that will be fed into server_callback without
229     modification.
230    
231     The server callback function prototype is very similar to the client one
232     (@ref lscp_server_proc_t):
233    
234     - @ref lscp_status_t <i>server_callback</i> ( @ref lscp_connect_t *conn,
235     const char *request, int reqlen, void *server_data );
236    
237     where conn is just a client connection handle, that shall be used for the
238     server responses; the request text which has a length of reqlen bytes;
239     server_data is the same value given on lscp_server_create.
240    
241     There's two special server callback cases, flagged by a null request pointer
242     and described with reqlen as a boolean value: when zero it announces a new
243     client connection, otherwise it tells that a client connection has closed.
244    
245     While handling each request the server must cook it's response and
246     eventually issue the following:<pre>
247    
248     @ref lscp_server_result (conn, result, reslen);
249    
250     </pre>where conn is the client handle, and result is a pointer to the server
251     response literal text of reslen bytes. Of course the response shall obey
252     to the protocol specification.
253    
254     The server issues a broadcast to its subscribers by simply issuing:<pre>
255    
256     @ref lscp_server_broadcast (server, buf, buflen);
257    
258     </pre>which will trigger the client callback function, which will be fed with an
259     exact copy of buf/len; this is the intended way to deliver all
260     notifications to each subscribed client.
261    
262     When its time to shutdown the server instance, just don't forget to call
263     the server destructor:<pre>
264    
265     @ref lscp_server_destroy (server);
266    
267     </pre>and we're done with the server.
268    
269    
270     @section Outro
271    
272     Nuff said. If you care or dare, track the revolving under:
273    
274 capela 2468 - http://www.rncbc.org/linuxsampler/
275 capela 103
276     Please note that the code is known to compile and run on Linux AND on
277     win32 (!). On Linux the main target is a shared library (liblscp.so) so
278 capela 2468 remember to set your LD_LIBRARY_PATH accordingly before running the test
279 capela 103 programs.
280    
281     A final disclaimer goes to the fact that I AM NOT a socket nor thread
282 capela 2468 programming guru, whatsoever. So fundamental mistakes may be laying around,
283 capela 103 somewhere. Besides that ItJustWorks(tm:).
284    
285     I'm eager to hear your feedback and comments. As usual, destructive
286     criticism will be sent to /dev/null ;)
287    
288     Hope to be on the right track, and towards linuxsampler integration.
289    
290     Otherwise sorry for the bandwidth waste.
291    
292     Cheers.
293    
294     rncbc aka Rui Nuno Capela
295     rncbc@rncbc.org
296    
297     @see http://www.linuxsampler.org
298    
299     */

  ViewVC Help
Powered by ViewVC