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;
        char *        protocol_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;
        int           midi_map;
        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 map;
        int bank;
        int prog;

} 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;


/** MIDI instrument map mode. */
typedef enum _lscp_midi_map_mode_t
{
        LSCP_MIDI_MAP_NONE = -1,
        LSCP_MIDI_MAP_DEFAULT = -2,
        LSCP_MIDI_MAP_ALL = -3

} lscp_midi_map_mode_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 function.

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_midi_map       (lscp_client_t *pClient, int iSamplerChannel, int iMidiMap);

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.

int                     lscp_add_midi_instrument_map    (lscp_client_t *pClient, const char *pszMapName);
lscp_status_t           lscp_remove_midi_instrument_map (lscp_client_t *pClient, int iMidiMap);

int                     lscp_get_midi_instrument_maps   (lscp_client_t *pClient);
int *                   lscp_list_midi_instrument_maps  (lscp_client_t *pClient);

const char *            lscp_get_midi_instrument_map_name (lscp_client_t *pClient, int iMidiMap);
lscp_status_t           lscp_set_midi_instrument_map_name (lscp_client_t *pClient, int iMidiMap, const char *pszMapName);

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, int iMidiMap);
lscp_midi_instrument_t *lscp_list_midi_instruments      (lscp_client_t *pClient, int iMidiMap);

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, int iMidiMap);


#if defined(__cplusplus)
}
#endif

#endif // __LSCP_CLIENT_H

// end of client.h
1	capela	107	// client.h
2			//
3			/****************************************************************************
4			liblscp - LinuxSampler Control Protocol API
5	capela	869	Copyright (C) 2004-2006, rncbc aka Rui Nuno Capela. All rights reserved.
6	capela	107
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	capela	921	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	capela	107
21			*****************************************************************************/
22
23			#ifndef __LSCP_CLIENT_H
24			#define __LSCP_CLIENT_H
25
26			#include "lscp/socket.h"
27	capela	146	#include "lscp/event.h"
28	capela	107
29			#if defined(__cplusplus)
30			extern "C" {
31			#endif
32
33	capela	253	//-------------------------------------------------------------------------
34			// MIDI channel omni mode.
35	capela	107
36	capela	278	#define LSCP_MIDI_CHANNEL_ALL 16
37	capela	253
38
39	capela	107	//-------------------------------------------------------------------------
40			// Client data structures.
41
42	capela	564	/** Server info cache struct. */
43			typedef struct _lscp_server_info_t
44			{
45	capela	952	char * description;
46			char * version;
47	capela	977	char * protocol_version;
48	capela	564
49			} lscp_server_info_t;
50
51
52	capela	107	/** Engine info cache struct. */
53			typedef struct _lscp_engine_info_t
54			{
55	capela	952	char * description;
56			char * version;
57	capela	107
58			} lscp_engine_info_t;
59
60
61			/** Channel info cache struct. */
62			typedef struct _lscp_channel_info_t
63			{
64	capela	952	char * engine_name;
65			int audio_device;
66			int audio_channels;
67			char ** audio_routing;
68			char * instrument_file;
69			int instrument_nr;
70			char * instrument_name;
71			int instrument_status;
72			int midi_device;
73			int midi_port;
74			int midi_channel;
75	capela	975	int midi_map;
76	capela	952	float volume;
77			int mute;
78			int solo;
79	capela	107
80			} lscp_channel_info_t;
81
82
83			/** Buffer fill cache struct. */
84			typedef struct _lscp_buffer_fill_t
85			{
86	capela	952	unsigned int stream_id;
87			unsigned long stream_usage;
88	capela	107
89			} lscp_buffer_fill_t;
90
91
92			/** Buffer fill stream usage types. */
93			typedef enum _lscp_usage_t
94			{
95	capela	952	LSCP_USAGE_BYTES = 0,
96			LSCP_USAGE_PERCENTAGE
97	capela	107
98			} lscp_usage_t;
99
100
101	capela	946	/** MIDI instrument parameter struct. */
102			typedef struct _lscp_midi_instrument_t
103			{
104	capela	975	int map;
105			int bank;
106			int prog;
107	capela	946
108			} lscp_midi_instrument_t;
109
110
111			/** MIDI instrument load mode. */
112			typedef enum _lscp_load_mode_t
113			{
114	capela	952	LSCP_LOAD_DEFAULT = 0,
115			LSCP_LOAD_ON_DEMAND,
116			LSCP_LOAD_ON_DEMAND_HOLD,
117			LSCP_LOAD_PERSISTENT
118	capela	946
119			} lscp_load_mode_t;
120
121
122			/** MIDI instrument info cache struct. */
123			typedef struct _lscp_midi_instrument_info_t
124			{
125	capela	952	char * name;
126			char * engine_name;
127			char * instrument_file;
128			int instrument_nr;
129			char * instrument_name;
130			lscp_load_mode_t load_mode;
131			float volume;
132	capela	946
133			} lscp_midi_instrument_info_t;
134
135
136	capela	975	/** MIDI instrument map mode. */
137			typedef enum _lscp_midi_map_mode_t
138			{
139			LSCP_MIDI_MAP_NONE = -1,
140			LSCP_MIDI_MAP_DEFAULT = -2,
141			LSCP_MIDI_MAP_ALL = -3
142
143			} lscp_midi_map_mode_t;
144
145
146	capela	107	//-------------------------------------------------------------------------
147			// Client socket main structure.
148
149			/** Client opaque descriptor struct. */
150			typedef struct _lscp_client_t lscp_client_t;
151
152	capela	144	/** Client event callback procedure prototype. */
153	capela	107	typedef lscp_status_t (*lscp_client_proc_t)
154			(
155	capela	952	struct _lscp_client_t *pClient,
156			lscp_event_t event,
157			const char *pchData,
158			int cchData,
159			void *pvData
160	capela	107	);
161
162			//-------------------------------------------------------------------------
163	capela	977	// Client versioning teller function.
164	capela	107
165			const char * lscp_client_package (void);
166			const char * lscp_client_version (void);
167			const char * lscp_client_build (void);
168
169			//-------------------------------------------------------------------------
170			// Client socket functions.
171
172			lscp_client_t * lscp_client_create (const char pszHost, int iPort, lscp_client_proc_t pfnCallback, void pvData);
173			lscp_status_t lscp_client_join (lscp_client_t *pClient);
174			lscp_status_t lscp_client_destroy (lscp_client_t *pClient);
175
176			lscp_status_t lscp_client_set_timeout (lscp_client_t *pClient, int iTimeout);
177			int lscp_client_get_timeout (lscp_client_t *pClient);
178
179			//-------------------------------------------------------------------------
180			// Client common protocol functions.
181
182			lscp_status_t lscp_client_query (lscp_client_t pClient, const char pszQuery);
183			const char * lscp_client_get_result (lscp_client_t *pClient );
184			int lscp_client_get_errno (lscp_client_t *pClient );
185
186			//-------------------------------------------------------------------------
187			// Client registration protocol functions.
188
189	capela	144	lscp_status_t lscp_client_subscribe (lscp_client_t *pClient, lscp_event_t events);
190			lscp_status_t lscp_client_unsubscribe (lscp_client_t *pClient, lscp_event_t events);
191	capela	107
192	capela	213	lscp_event_t lscp_client_get_events (lscp_client_t *pClient);
193	capela	144
194	capela	107	//-------------------------------------------------------------------------
195			// Client command protocol functions.
196
197			lscp_status_t lscp_load_instrument (lscp_client_t pClient, const char pszFileName, int iInstrIndex, int iSamplerChannel);
198	capela	144	lscp_status_t lscp_load_instrument_non_modal (lscp_client_t pClient, const char pszFileName, int iInstrIndex, int iSamplerChannel);
199	capela	107	lscp_status_t lscp_load_engine (lscp_client_t pClient, const char pszEngineName, int iSamplerChannel);
200			int lscp_get_channels (lscp_client_t *pClient);
201	capela	125	int * lscp_list_channels (lscp_client_t *pClient);
202	capela	107	int lscp_add_channel (lscp_client_t *pClient);
203			lscp_status_t lscp_remove_channel (lscp_client_t *pClient, int iSamplerChannel);
204
205	capela	523	int lscp_get_available_engines (lscp_client_t *pClient);
206			const char ** lscp_list_available_engines (lscp_client_t *pClient);
207
208	capela	107	lscp_engine_info_t * lscp_get_engine_info (lscp_client_t pClient, const char pszEngineName);
209			lscp_channel_info_t * lscp_get_channel_info (lscp_client_t *pClient, int iSamplerChannel);
210
211			int lscp_get_channel_voice_count (lscp_client_t *pClient, int iSamplerChannel);
212			int lscp_get_channel_stream_count (lscp_client_t *pClient, int iSamplerChannel);
213	capela	167	int lscp_get_channel_stream_usage (lscp_client_t *pClient, int iSamplerChannel);
214	capela	107
215			lscp_buffer_fill_t * lscp_get_channel_buffer_fill (lscp_client_t *pClient, lscp_usage_t iUsageType, int iSamplerChannel);
216
217			lscp_status_t lscp_set_channel_audio_type (lscp_client_t pClient, int iSamplerChannel, const char pszAudioType);
218	capela	144	lscp_status_t lscp_set_channel_audio_device (lscp_client_t *pClient, int iSamplerChannel, int iAudioDevice);
219	capela	107	lscp_status_t lscp_set_channel_audio_channel (lscp_client_t *pClient, int iSamplerChannel, int iAudioOut, int iAudioIn);
220
221			lscp_status_t lscp_set_channel_midi_type (lscp_client_t pClient, int iSamplerChannel, const char pszMidiType);
222	capela	144	lscp_status_t lscp_set_channel_midi_device (lscp_client_t *pClient, int iSamplerChannel, int iMidiDevice);
223	capela	107	lscp_status_t lscp_set_channel_midi_port (lscp_client_t *pClient, int iSamplerChannel, int iMidiPort);
224			lscp_status_t lscp_set_channel_midi_channel (lscp_client_t *pClient, int iSamplerChannel, int iMidiChannel);
225	capela	975	lscp_status_t lscp_set_channel_midi_map (lscp_client_t *pClient, int iSamplerChannel, int iMidiMap);
226
227	capela	107	lscp_status_t lscp_set_channel_volume (lscp_client_t *pClient, int iSamplerChannel, float fVolume);
228
229	capela	735	lscp_status_t lscp_set_channel_mute (lscp_client_t *pClient, int iSamplerChannel, int iMute);
230			lscp_status_t lscp_set_channel_solo (lscp_client_t *pClient, int iSamplerChannel, int iSolo);
231
232	capela	107	lscp_status_t lscp_reset_channel (lscp_client_t *pClient, int iSamplerChannel);
233
234	capela	213	lscp_status_t lscp_reset_sampler (lscp_client_t *pClient);
235	capela	107
236	capela	564	lscp_server_info_t * lscp_get_server_info (lscp_client_t *pClient);
237
238	capela	946	int lscp_get_total_voice_count (lscp_client_t *pClient);
239			int lscp_get_total_voice_count_max (lscp_client_t *pClient);
240
241			//-------------------------------------------------------------------------
242			// MIDI instrument mapping control functions.
243
244	capela	975	int lscp_add_midi_instrument_map (lscp_client_t pClient, const char pszMapName);
245			lscp_status_t lscp_remove_midi_instrument_map (lscp_client_t *pClient, int iMidiMap);
246
247			int lscp_get_midi_instrument_maps (lscp_client_t *pClient);
248			int * lscp_list_midi_instrument_maps (lscp_client_t *pClient);
249
250			const char * lscp_get_midi_instrument_map_name (lscp_client_t *pClient, int iMidiMap);
251			lscp_status_t lscp_set_midi_instrument_map_name (lscp_client_t pClient, int iMidiMap, const char pszMapName);
252
253	capela	946	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);
254			lscp_status_t lscp_unmap_midi_instrument (lscp_client_t pClient, lscp_midi_instrument_t pMidiInstr);
255
256	capela	975	int lscp_get_midi_instruments (lscp_client_t *pClient, int iMidiMap);
257			lscp_midi_instrument_t lscp_list_midi_instruments (lscp_client_t pClient, int iMidiMap);
258	capela	946
259			lscp_midi_instrument_info_t lscp_get_midi_instrument_info(lscp_client_t pClient, lscp_midi_instrument_t *pMidiInstr);
260
261	capela	975	lscp_status_t lscp_clear_midi_instruments (lscp_client_t *pClient, int iMidiMap);
262	capela	946
263
264	capela	107	#if defined(__cplusplus)
265			}
266			#endif
267
268			#endif // __LSCP_CLIENT_H
269
270			// end of client.h