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