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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 125 - (hide annotations) (download)
Mon Jun 14 21:04:04 2004 UTC (19 years, 9 months ago) by capela
File size: 8134 byte(s)
* Added support for the new LIST commands (draft v.08).

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 125 (http://www.linuxsampler.org/api/draft-linuxsampler-protocol-08.pdf).
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     const char *buf, int buflen, void *client_data );
87    
88     where buf will be a pointer to the event text which is buflen bytes in
89     length; client_data is exactly the same value given on @ref lscp_client_create
90     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 notifications by calling:<pre>
98    
99     @ref lscp_client_subscribe (client);
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);
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 (04), the client interface already maps
111     the following functions defined in "@ref lscp_client.h", one for each corresponding
112     LSCP comand:<pre>
113    
114     @ref lscp_get_available_engines (client);
115     @ref lscp_get_engine_info (client, engine_name);
116     @ref lscp_get_channels (client);
117     @ref lscp_add_channel (client);
118     @ref lscp_load_engine (client, engine_name, channel);
119     @ref lscp_set_channel_audio_channel (client, channel, audio_channel);
120     @ref lscp_set_channel_audio_type (client, channel, audio_type);
121     @ref lscp_set_channel_midi_channel (client, channel, midi_channel);
122     @ref lscp_set_channel_midi_port (client, channel, midi_port);
123     @ref lscp_set_channel_midi_type (client, channel, midi_type);
124     @ref lscp_set_channel_volume (client, channel, volume);
125     @ref lscp_load_instrument (client, file_name, instr_index, channel);
126     @ref lscp_get_channel_info (client, channel);
127     @ref lscp_get_channel_voice_count (client, channel);
128     @ref lscp_get_channel_stream_count (client, channel);
129     @ref lscp_get_channel_buffer_fill (client, usage_type, channel);
130     @ref lscp_reset_channel (client, channel);
131     @ref lscp_remove_channel (client, channel);
132    
133     </pre>All these functions are wrappers to @ref lscp_client_query, and some will handle
134     and change the result string accordingly.
135    
136    
137     @section Server
138    
139     Likewise, and least important yet as for server programming, you create a server
140     instance handle just like that:<pre>
141    
142     #include <lscp/@ref:server.h>
143    
144     @ref lscp_server_t *server;
145    
146     server = @ref lscp_server_create (server_port, server_callback, server_data);
147    
148     </pre>where server_port is the port number where the server will be
149     listening for connections; server_callback is the server supplied
150     callback function that will handle every client request; server_data is
151     any reference to data that will be fed into server_callback without
152     modification.
153    
154     The server callback function prototype is very similar to the client one
155     (@ref lscp_server_proc_t):
156    
157     - @ref lscp_status_t <i>server_callback</i> ( @ref lscp_connect_t *conn,
158     const char *request, int reqlen, void *server_data );
159    
160     where conn is just a client connection handle, that shall be used for the
161     server responses; the request text which has a length of reqlen bytes;
162     server_data is the same value given on lscp_server_create.
163    
164     There's two special server callback cases, flagged by a null request pointer
165     and described with reqlen as a boolean value: when zero it announces a new
166     client connection, otherwise it tells that a client connection has closed.
167    
168     While handling each request the server must cook it's response and
169     eventually issue the following:<pre>
170    
171     @ref lscp_server_result (conn, result, reslen);
172    
173     </pre>where conn is the client handle, and result is a pointer to the server
174     response literal text of reslen bytes. Of course the response shall obey
175     to the protocol specification.
176    
177     The server issues a broadcast to its subscribers by simply issuing:<pre>
178    
179     @ref lscp_server_broadcast (server, buf, buflen);
180    
181     </pre>which will trigger the client callback function, which will be fed with an
182     exact copy of buf/len; this is the intended way to deliver all
183     notifications to each subscribed client.
184    
185     When its time to shutdown the server instance, just don't forget to call
186     the server destructor:<pre>
187    
188     @ref lscp_server_destroy (server);
189    
190     </pre>and we're done with the server.
191    
192    
193     @section Outro
194    
195     Nuff said. If you care or dare, track the revolving under:
196    
197     - http://www.rncbc.org/ls/
198    
199     Please note that the code is known to compile and run on Linux AND on
200     win32 (!). On Linux the main target is a shared library (liblscp.so) so
201     remember to set your LS_LIBRARY_PATH accordingly before running the test
202     programs.
203    
204     A final disclaimer goes to the fact that I AM NOT a socket nor thread
205     programming guru, whatsoever. So fundamental mistakes may be lying around,
206     somewhere. Besides that ItJustWorks(tm:).
207    
208     I'm eager to hear your feedback and comments. As usual, destructive
209     criticism will be sent to /dev/null ;)
210    
211     Hope to be on the right track, and towards linuxsampler integration.
212    
213     Otherwise sorry for the bandwidth waste.
214    
215     Cheers.
216    
217     rncbc aka Rui Nuno Capela
218     rncbc@rncbc.org
219    
220     @see http://www.linuxsampler.org
221    
222     */

  ViewVC Help
Powered by ViewVC