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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 948 - (show annotations) (download)
Tue Nov 28 15:31:20 2006 UTC (13 years, 4 months ago) by capela
File size: 11137 byte(s)
* Fixed some compilation warnings due to suspicious type
  casting and unsused header macros.

* Changed deprecated copyright attribute to license
  and added ldconfig to post-(un)install steps
  to liblscp.spec (RPM).

1 /**
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 (http://www.linuxsampler.org/api/draft-linuxsampler-protocol.html).
14
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 @ref lscp_event_t event, const char *buf, int buflen, void *client_data );
87
88 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
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 A client subscribes to receive event notifications by calling:<pre>
98
99 @ref lscp_client_subscribe (client, events);
100
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 @ref lscp_client_unsubscribe (client, events);
105
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 </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
114 @ref lscp_get_available_engines (client);
115 @ref lscp_list_available_engines (client);
116 @ref lscp_get_engine_info (client, engine_name);
117 @ref lscp_get_channels (client);
118 @ref lscp_list_channels (client);
119 @ref lscp_add_channel (client);
120 @ref lscp_load_engine (client, engine_name, channel);
121 @ref lscp_set_channel_audio_device (client, channel, audio_device);
122 @ref lscp_set_channel_audio_type (client, channel, audio_type);
123 @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 @ref lscp_set_channel_midi_channel (client, channel, midi_channel);
128 @ref lscp_set_channel_mute (client, channel, mute);
129 @ref lscp_set_channel_solo (client, channel, solo);
130 @ref lscp_set_channel_volume (client, channel, volume);
131 @ref lscp_load_instrument (client, file_name, instr_index, channel);
132 @ref lscp_load_instrument_non_modal (client, file_name, instr_index, channel);
133 @ref lscp_get_channel_info (client, channel);
134 @ref lscp_get_channel_voice_count (client, channel);
135 @ref lscp_get_channel_stream_count (client, channel);
136 @ref lscp_get_channel_buffer_fill (client, usage_type, channel);
137 @ref lscp_reset_channel (client, channel);
138 @ref lscp_remove_channel (client, channel);
139 @ref lscp_reset_sampler (client);
140 @ref lscp_get_server_info (client);
141 @ref lscp_get_server_info (client);
142 @ref lscp_get_total_voice_count (client);
143 @ref lscp_get_total_voice_count_max (client);
144
145 </pre>Specific to MIDI instrument mapping interface:<pre>
146
147 @ref lscp_map_midi_instrument (client, midi_instr, engine_name, file_name, instr_index, volume, load_mode, name);
148 @ref lscp_unmap_midi_instrument (client, midi_instr);
149 @ref lscp_get_midi_instruments (client);
150 @ref lscp_list_midi_instruments (client);
151 @ref lscp_get_midi_instrument_info (client, midi_instr);
152 @ref lscp_clear_midi_instruments (client);
153
154 </pre>For the audio output and MIDI input device configuration interface,
155 the following functions are respectively defined in <lscp/@ref:device.h>:<pre>
156
157 @ref lscp_get_available_audio_drivers (client);
158 @ref lscp_list_available_audio_drivers (client);
159 @ref lscp_get_audio_driver_info (client, audio_driver);
160 @ref lscp_get_audio_driver_param_info (client, audio_driver, param_key, deplist);
161 @ref lscp_create_audio_device (client, audio_driver, params);
162 @ref lscp_destroy_audio_device (client, audio_device);
163 @ref lscp_get_audio_devices (client);
164 @ref lscp_list_audio_devices (client);
165 @ref lscp_get_audio_device_info (client, audio_device);
166 @ref lscp_set_audio_device_param (client, audio_device, param);
167 @ref lscp_get_audio_channel_info (client, audio_device, audio_channel);
168 @ref lscp_get_audio_channel_param_info (client, audio_device, audio_channel, param);
169 @ref lscp_set_audio_channel_param (client, audio_device, audio_channel, param);
170
171 @ref lscp_get_available_midi_drivers (client);
172 @ref lscp_list_available_midi_drivers (client);
173 @ref lscp_get_midi_driver_info (client, midi_driver);
174 @ref lscp_get_midi_driver_param_info (client, midi_driver, param_key, deplist);
175 @ref lscp_create_midi_device (client, midi_driver, params);
176 @ref lscp_destroy_midi_device (client, midi_device);
177 @ref lscp_get_midi_devices (client);
178 @ref lscp_list_midi_devices (client);
179 @ref lscp_get_midi_device_info (client, midi_device);
180 @ref lscp_set_midi_device_param (client, midi_device, param);
181 @ref lscp_get_midi_port_info (client, midi_device, midi_port);
182 @ref lscp_get_midi_port_param_info (client, midi_device, midi_port, param);
183 @ref lscp_set_midi_port_param (client, midi_device, midi_port, param);
184
185 </pre>Most of these functions are wrappers to @ref lscp_client_query, and some will handle
186 and change the result string accordingly.
187
188
189 @section Server
190
191 Likewise, and least important yet as for server programming, you create a server
192 instance handle just like that:<pre>
193
194 #include <lscp/@ref:server.h>
195
196 @ref lscp_server_t *server;
197
198 server = @ref lscp_server_create (server_port, server_callback, server_data);
199
200 </pre>where server_port is the port number where the server will be
201 listening for connections; server_callback is the server supplied
202 callback function that will handle every client request; server_data is
203 any reference to data that will be fed into server_callback without
204 modification.
205
206 The server callback function prototype is very similar to the client one
207 (@ref lscp_server_proc_t):
208
209 - @ref lscp_status_t <i>server_callback</i> ( @ref lscp_connect_t *conn,
210 const char *request, int reqlen, void *server_data );
211
212 where conn is just a client connection handle, that shall be used for the
213 server responses; the request text which has a length of reqlen bytes;
214 server_data is the same value given on lscp_server_create.
215
216 There's two special server callback cases, flagged by a null request pointer
217 and described with reqlen as a boolean value: when zero it announces a new
218 client connection, otherwise it tells that a client connection has closed.
219
220 While handling each request the server must cook it's response and
221 eventually issue the following:<pre>
222
223 @ref lscp_server_result (conn, result, reslen);
224
225 </pre>where conn is the client handle, and result is a pointer to the server
226 response literal text of reslen bytes. Of course the response shall obey
227 to the protocol specification.
228
229 The server issues a broadcast to its subscribers by simply issuing:<pre>
230
231 @ref lscp_server_broadcast (server, buf, buflen);
232
233 </pre>which will trigger the client callback function, which will be fed with an
234 exact copy of buf/len; this is the intended way to deliver all
235 notifications to each subscribed client.
236
237 When its time to shutdown the server instance, just don't forget to call
238 the server destructor:<pre>
239
240 @ref lscp_server_destroy (server);
241
242 </pre>and we're done with the server.
243
244
245 @section Outro
246
247 Nuff said. If you care or dare, track the revolving under:
248
249 - http://www.rncbc.org/ls/
250
251 Please note that the code is known to compile and run on Linux AND on
252 win32 (!). On Linux the main target is a shared library (liblscp.so) so
253 remember to set your LS_LIBRARY_PATH accordingly before running the test
254 programs.
255
256 A final disclaimer goes to the fact that I AM NOT a socket nor thread
257 programming guru, whatsoever. So fundamental mistakes may be lying around,
258 somewhere. Besides that ItJustWorks(tm:).
259
260 I'm eager to hear your feedback and comments. As usual, destructive
261 criticism will be sent to /dev/null ;)
262
263 Hope to be on the right track, and towards linuxsampler integration.
264
265 Otherwise sorry for the bandwidth waste.
266
267 Cheers.
268
269 rncbc aka Rui Nuno Capela
270 rncbc@rncbc.org
271
272 @see http://www.linuxsampler.org
273
274 */

  ViewVC Help
Powered by ViewVC