trunk/lscp/client.h

// client.h
//
/****************************************************************************
   liblscp - LinuxSampler Control Protocol API
   Copyright (C) 2004-2006, rncbc aka Rui Nuno Capela. All rights reserved.

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2.1 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU General Public License along
   with this program; if not, write to the Free Software Foundation, Inc.,
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

*****************************************************************************/

#ifndef __LSCP_CLIENT_H
#define __LSCP_CLIENT_H

#include "lscp/socket.h"
#include "lscp/event.h"

#if defined(__cplusplus)
extern "C" {
#endif

//-------------------------------------------------------------------------
// MIDI channel omni mode.

#define LSCP_MIDI_CHANNEL_ALL   16


//-------------------------------------------------------------------------
// Client data structures.

/** Server info cache struct. */
typedef struct _lscp_server_info_t
{
        char *        description;
        char *        version;

} lscp_server_info_t;


/** Engine info cache struct. */
typedef struct _lscp_engine_info_t
{
        char *        description;
        char *        version;

} lscp_engine_info_t;


/** Channel info cache struct. */
typedef struct _lscp_channel_info_t
{
        char *        engine_name;
        int           audio_device;
        int           audio_channels;
        char **       audio_routing;
        char *        instrument_file;
        int           instrument_nr;
        char *        instrument_name;
        int           instrument_status;
        int           midi_device;
        int           midi_port;
        int           midi_channel;
        float         volume;
        int           mute;
        int           solo;

} lscp_channel_info_t;


/** Buffer fill cache struct. */
typedef struct _lscp_buffer_fill_t
{
        unsigned int  stream_id;
        unsigned long stream_usage;

} lscp_buffer_fill_t;


/** Buffer fill stream usage types. */
typedef enum _lscp_usage_t
{
        LSCP_USAGE_BYTES = 0,
        LSCP_USAGE_PERCENTAGE

} lscp_usage_t;


/** MIDI instrument parameter struct. */
typedef struct _lscp_midi_instrument_t
{
        int bank_msb;
        int bank_lsb;
        int program;

} lscp_midi_instrument_t;


/** MIDI instrument load mode. */
typedef enum _lscp_load_mode_t
{
        LSCP_LOAD_DEFAULT = 0,
        LSCP_LOAD_ON_DEMAND,
        LSCP_LOAD_ON_DEMAND_HOLD,
        LSCP_LOAD_PERSISTENT

} lscp_load_mode_t;


/** MIDI instrument info cache struct. */
typedef struct _lscp_midi_instrument_info_t
{
        char *           name;
        char *           engine_name;
        char *           instrument_file;
        int              instrument_nr;
        char *           instrument_name;
        lscp_load_mode_t load_mode;
        float            volume;

} lscp_midi_instrument_info_t;


//-------------------------------------------------------------------------
// Client socket main structure.

/** Client opaque descriptor struct. */
typedef struct _lscp_client_t lscp_client_t;

/** Client event callback procedure prototype. */
typedef lscp_status_t (*lscp_client_proc_t)
(
        struct _lscp_client_t *pClient,
        lscp_event_t event,
        const char *pchData,
        int cchData,
        void *pvData
);

//-------------------------------------------------------------------------
// Client versioning teller fuunction.

const char *            lscp_client_package             (void);
const char *            lscp_client_version             (void);
const char *            lscp_client_build               (void);

//-------------------------------------------------------------------------
// Client socket functions.

lscp_client_t *         lscp_client_create              (const char *pszHost, int iPort, lscp_client_proc_t pfnCallback, void *pvData);
lscp_status_t           lscp_client_join                (lscp_client_t *pClient);
lscp_status_t           lscp_client_destroy             (lscp_client_t *pClient);

lscp_status_t           lscp_client_set_timeout         (lscp_client_t *pClient, int iTimeout);
int                     lscp_client_get_timeout         (lscp_client_t *pClient);

//-------------------------------------------------------------------------
// Client common protocol functions.

lscp_status_t           lscp_client_query               (lscp_client_t *pClient, const char *pszQuery);
const char *            lscp_client_get_result          (lscp_client_t *pClient );
int                     lscp_client_get_errno           (lscp_client_t *pClient );

//-------------------------------------------------------------------------
// Client registration protocol functions.

lscp_status_t           lscp_client_subscribe           (lscp_client_t *pClient, lscp_event_t events);
lscp_status_t           lscp_client_unsubscribe         (lscp_client_t *pClient, lscp_event_t events);

lscp_event_t            lscp_client_get_events          (lscp_client_t *pClient);

//-------------------------------------------------------------------------
// Client command protocol functions.

lscp_status_t           lscp_load_instrument            (lscp_client_t *pClient, const char *pszFileName, int iInstrIndex, int iSamplerChannel);
lscp_status_t           lscp_load_instrument_non_modal  (lscp_client_t *pClient, const char *pszFileName, int iInstrIndex, int iSamplerChannel);
lscp_status_t           lscp_load_engine                (lscp_client_t *pClient, const char *pszEngineName, int iSamplerChannel);
int                     lscp_get_channels               (lscp_client_t *pClient);
int *                   lscp_list_channels              (lscp_client_t *pClient);
int                     lscp_add_channel                (lscp_client_t *pClient);
lscp_status_t           lscp_remove_channel             (lscp_client_t *pClient, int iSamplerChannel);

int                     lscp_get_available_engines      (lscp_client_t *pClient);
const char **           lscp_list_available_engines     (lscp_client_t *pClient);

lscp_engine_info_t *    lscp_get_engine_info            (lscp_client_t *pClient, const char *pszEngineName);
lscp_channel_info_t *   lscp_get_channel_info           (lscp_client_t *pClient, int iSamplerChannel);

int                     lscp_get_channel_voice_count    (lscp_client_t *pClient, int iSamplerChannel);
int                     lscp_get_channel_stream_count   (lscp_client_t *pClient, int iSamplerChannel);
int                     lscp_get_channel_stream_usage   (lscp_client_t *pClient, int iSamplerChannel);

lscp_buffer_fill_t *    lscp_get_channel_buffer_fill    (lscp_client_t *pClient, lscp_usage_t iUsageType, int iSamplerChannel);

lscp_status_t           lscp_set_channel_audio_type     (lscp_client_t *pClient, int iSamplerChannel, const char *pszAudioType);
lscp_status_t           lscp_set_channel_audio_device   (lscp_client_t *pClient, int iSamplerChannel, int iAudioDevice);
lscp_status_t           lscp_set_channel_audio_channel  (lscp_client_t *pClient, int iSamplerChannel, int iAudioOut, int iAudioIn);

lscp_status_t           lscp_set_channel_midi_type      (lscp_client_t *pClient, int iSamplerChannel, const char *pszMidiType);
lscp_status_t           lscp_set_channel_midi_device    (lscp_client_t *pClient, int iSamplerChannel, int iMidiDevice);
lscp_status_t           lscp_set_channel_midi_port      (lscp_client_t *pClient, int iSamplerChannel, int iMidiPort);
lscp_status_t           lscp_set_channel_midi_channel   (lscp_client_t *pClient, int iSamplerChannel, int iMidiChannel);
lscp_status_t           lscp_set_channel_volume         (lscp_client_t *pClient, int iSamplerChannel, float fVolume);

lscp_status_t           lscp_set_channel_mute           (lscp_client_t *pClient, int iSamplerChannel, int iMute);
lscp_status_t           lscp_set_channel_solo           (lscp_client_t *pClient, int iSamplerChannel, int iSolo);

lscp_status_t           lscp_reset_channel              (lscp_client_t *pClient, int iSamplerChannel);

lscp_status_t           lscp_reset_sampler              (lscp_client_t *pClient);

lscp_server_info_t *    lscp_get_server_info            (lscp_client_t *pClient);

int                     lscp_get_total_voice_count      (lscp_client_t *pClient);
int                     lscp_get_total_voice_count_max  (lscp_client_t *pClient);

//-------------------------------------------------------------------------
// MIDI instrument mapping control functions.

lscp_status_t           lscp_map_midi_instrument        (lscp_client_t *pClient, lscp_midi_instrument_t *pMidiInstr, const char *pszEngineName, const char *pszFileName, int iInstrIndex, float fVolume, lscp_load_mode_t load_mode, const char *pszName);
lscp_status_t           lscp_unmap_midi_instrument      (lscp_client_t *pClient, lscp_midi_instrument_t *pMidiInstr);

int                     lscp_get_midi_instruments       (lscp_client_t *pClient);
lscp_midi_instrument_t *lscp_list_midi_instruments      (lscp_client_t *pClient);

lscp_midi_instrument_info_t *lscp_get_midi_instrument_info(lscp_client_t *pClient, lscp_midi_instrument_t *pMidiInstr);

lscp_status_t           lscp_clear_midi_instruments     (lscp_client_t *pClient);


#if defined(__cplusplus)
}
#endif

#endif // __LSCP_CLIENT_H

// end of client.h
1	// client.h
2	//
3	/****************************************************************************
4	liblscp - LinuxSampler Control Protocol API
5	Copyright (C) 2004-2006, rncbc aka Rui Nuno Capela. All rights reserved.
6
7	This library is free software; you can redistribute it and/or
8	modify it under the terms of the GNU Lesser General Public
9	License as published by the Free Software Foundation; either
10	version 2.1 of the License, or (at your option) any later version.
11
12	This library is distributed in the hope that it will be useful,
13	but WITHOUT ANY WARRANTY; without even the implied warranty of
14	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15	Lesser General Public License for more details.
16
17	You should have received a copy of the GNU General Public License along
18	with this program; if not, write to the Free Software Foundation, Inc.,
19	51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
20
21	*****************************************************************************/
22
23	#ifndef __LSCP_CLIENT_H
24	#define __LSCP_CLIENT_H
25
26	#include "lscp/socket.h"
27	#include "lscp/event.h"
28
29	#if defined(__cplusplus)
30	extern "C" {
31	#endif
32
33	//-------------------------------------------------------------------------
34	// MIDI channel omni mode.
35
36	#define LSCP_MIDI_CHANNEL_ALL 16
37
38
39	//-------------------------------------------------------------------------
40	// Client data structures.
41
42	/** Server info cache struct. */
43	typedef struct _lscp_server_info_t
44	{
45	char * description;
46	char * version;
47
48	} lscp_server_info_t;
49
50
51	/** Engine info cache struct. */
52	typedef struct _lscp_engine_info_t
53	{
54	char * description;
55	char * version;
56
57	} lscp_engine_info_t;
58
59
60	/** Channel info cache struct. */
61	typedef struct _lscp_channel_info_t
62	{
63	char * engine_name;
64	int audio_device;
65	int audio_channels;
66	char ** audio_routing;
67	char * instrument_file;
68	int instrument_nr;
69	char * instrument_name;
70	int instrument_status;
71	int midi_device;
72	int midi_port;
73	int midi_channel;
74	float volume;
75	int mute;
76	int solo;
77
78	} lscp_channel_info_t;
79
80
81	/** Buffer fill cache struct. */
82	typedef struct _lscp_buffer_fill_t
83	{
84	unsigned int stream_id;
85	unsigned long stream_usage;
86
87	} lscp_buffer_fill_t;
88
89
90	/** Buffer fill stream usage types. */
91	typedef enum _lscp_usage_t
92	{
93	LSCP_USAGE_BYTES = 0,
94	LSCP_USAGE_PERCENTAGE
95
96	} lscp_usage_t;
97
98
99	/** MIDI instrument parameter struct. */
100	typedef struct _lscp_midi_instrument_t
101	{
102	int bank_msb;
103	int bank_lsb;
104	int program;
105
106	} lscp_midi_instrument_t;
107
108
109	/** MIDI instrument load mode. */
110	typedef enum _lscp_load_mode_t
111	{
112	LSCP_LOAD_DEFAULT = 0,
113	LSCP_LOAD_ON_DEMAND,
114	LSCP_LOAD_ON_DEMAND_HOLD,
115	LSCP_LOAD_PERSISTENT
116
117	} lscp_load_mode_t;
118
119
120	/** MIDI instrument info cache struct. */
121	typedef struct _lscp_midi_instrument_info_t
122	{
123	char * name;
124	char * engine_name;
125	char * instrument_file;
126	int instrument_nr;
127	char * instrument_name;
128	lscp_load_mode_t load_mode;
129	float volume;
130
131	} lscp_midi_instrument_info_t;
132
133
134	//-------------------------------------------------------------------------
135	// Client socket main structure.
136
137	/** Client opaque descriptor struct. */
138	typedef struct _lscp_client_t lscp_client_t;
139
140	/** Client event callback procedure prototype. */
141	typedef lscp_status_t (*lscp_client_proc_t)
142	(
143	struct _lscp_client_t *pClient,
144	lscp_event_t event,
145	const char *pchData,
146	int cchData,
147	void *pvData
148	);
149
150	//-------------------------------------------------------------------------
151	// Client versioning teller fuunction.
152
153	const char * lscp_client_package (void);
154	const char * lscp_client_version (void);
155	const char * lscp_client_build (void);
156
157	//-------------------------------------------------------------------------
158	// Client socket functions.
159
160	lscp_client_t * lscp_client_create (const char pszHost, int iPort, lscp_client_proc_t pfnCallback, void pvData);
161	lscp_status_t lscp_client_join (lscp_client_t *pClient);
162	lscp_status_t lscp_client_destroy (lscp_client_t *pClient);
163
164	lscp_status_t lscp_client_set_timeout (lscp_client_t *pClient, int iTimeout);
165	int lscp_client_get_timeout (lscp_client_t *pClient);
166
167	//-------------------------------------------------------------------------
168	// Client common protocol functions.
169
170	lscp_status_t lscp_client_query (lscp_client_t pClient, const char pszQuery);
171	const char * lscp_client_get_result (lscp_client_t *pClient );
172	int lscp_client_get_errno (lscp_client_t *pClient );
173
174	//-------------------------------------------------------------------------
175	// Client registration protocol functions.
176
177	lscp_status_t lscp_client_subscribe (lscp_client_t *pClient, lscp_event_t events);
178	lscp_status_t lscp_client_unsubscribe (lscp_client_t *pClient, lscp_event_t events);
179
180	lscp_event_t lscp_client_get_events (lscp_client_t *pClient);
181
182	//-------------------------------------------------------------------------
183	// Client command protocol functions.
184
185	lscp_status_t lscp_load_instrument (lscp_client_t pClient, const char pszFileName, int iInstrIndex, int iSamplerChannel);
186	lscp_status_t lscp_load_instrument_non_modal (lscp_client_t pClient, const char pszFileName, int iInstrIndex, int iSamplerChannel);
187	lscp_status_t lscp_load_engine (lscp_client_t pClient, const char pszEngineName, int iSamplerChannel);
188	int lscp_get_channels (lscp_client_t *pClient);
189	int * lscp_list_channels (lscp_client_t *pClient);
190	int lscp_add_channel (lscp_client_t *pClient);
191	lscp_status_t lscp_remove_channel (lscp_client_t *pClient, int iSamplerChannel);
192
193	int lscp_get_available_engines (lscp_client_t *pClient);
194	const char ** lscp_list_available_engines (lscp_client_t *pClient);
195
196	lscp_engine_info_t * lscp_get_engine_info (lscp_client_t pClient, const char pszEngineName);
197	lscp_channel_info_t * lscp_get_channel_info (lscp_client_t *pClient, int iSamplerChannel);
198
199	int lscp_get_channel_voice_count (lscp_client_t *pClient, int iSamplerChannel);
200	int lscp_get_channel_stream_count (lscp_client_t *pClient, int iSamplerChannel);
201	int lscp_get_channel_stream_usage (lscp_client_t *pClient, int iSamplerChannel);
202
203	lscp_buffer_fill_t * lscp_get_channel_buffer_fill (lscp_client_t *pClient, lscp_usage_t iUsageType, int iSamplerChannel);
204
205	lscp_status_t lscp_set_channel_audio_type (lscp_client_t pClient, int iSamplerChannel, const char pszAudioType);
206	lscp_status_t lscp_set_channel_audio_device (lscp_client_t *pClient, int iSamplerChannel, int iAudioDevice);
207	lscp_status_t lscp_set_channel_audio_channel (lscp_client_t *pClient, int iSamplerChannel, int iAudioOut, int iAudioIn);
208
209	lscp_status_t lscp_set_channel_midi_type (lscp_client_t pClient, int iSamplerChannel, const char pszMidiType);
210	lscp_status_t lscp_set_channel_midi_device (lscp_client_t *pClient, int iSamplerChannel, int iMidiDevice);
211	lscp_status_t lscp_set_channel_midi_port (lscp_client_t *pClient, int iSamplerChannel, int iMidiPort);
212	lscp_status_t lscp_set_channel_midi_channel (lscp_client_t *pClient, int iSamplerChannel, int iMidiChannel);
213	lscp_status_t lscp_set_channel_volume (lscp_client_t *pClient, int iSamplerChannel, float fVolume);
214
215	lscp_status_t lscp_set_channel_mute (lscp_client_t *pClient, int iSamplerChannel, int iMute);
216	lscp_status_t lscp_set_channel_solo (lscp_client_t *pClient, int iSamplerChannel, int iSolo);
217
218	lscp_status_t lscp_reset_channel (lscp_client_t *pClient, int iSamplerChannel);
219
220	lscp_status_t lscp_reset_sampler (lscp_client_t *pClient);
221
222	lscp_server_info_t * lscp_get_server_info (lscp_client_t *pClient);
223
224	int lscp_get_total_voice_count (lscp_client_t *pClient);
225	int lscp_get_total_voice_count_max (lscp_client_t *pClient);
226
227	//-------------------------------------------------------------------------
228	// MIDI instrument mapping control functions.
229
230	lscp_status_t lscp_map_midi_instrument (lscp_client_t pClient, lscp_midi_instrument_t pMidiInstr, const char pszEngineName, const char pszFileName, int iInstrIndex, float fVolume, lscp_load_mode_t load_mode, const char *pszName);
231	lscp_status_t lscp_unmap_midi_instrument (lscp_client_t pClient, lscp_midi_instrument_t pMidiInstr);
232
233	int lscp_get_midi_instruments (lscp_client_t *pClient);
234	lscp_midi_instrument_t lscp_list_midi_instruments (lscp_client_t pClient);
235
236	lscp_midi_instrument_info_t lscp_get_midi_instrument_info(lscp_client_t pClient, lscp_midi_instrument_t *pMidiInstr);
237
238	lscp_status_t lscp_clear_midi_instruments (lscp_client_t *pClient);
239
240
241	#if defined(__cplusplus)
242	}
243	#endif
244
245	#endif // __LSCP_CLIENT_H
246
247	// end of client.h