trunk/lscp/client.h

// client.h
//
/****************************************************************************
   liblscp - LinuxSampler Control Protocol API
   Copyright (C) 2004, 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 Lesser General Public
   License along with this library; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

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

#ifndef __LSCP_CLIENT_H
#define __LSCP_CLIENT_H

#include "lscp/socket.h"

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


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

/** 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;
    int           instrument_status;
    int           midi_device;
    int           midi_port;
    int           midi_channel;
    float         volume;

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


/** Subscribable event notification bit-wise flags. */
typedef enum _lscp_event_t
{
    LSCP_EVENT_NONE             = 0x0000,
    LSCP_EVENT_CHANNELS         = 0x0001,
    LSCP_EVENT_VOICE_COUNT      = 0x0002,
    LSCP_EVENT_STREAM_COUNT     = 0x0004,
    LSCP_EVENT_BUFFER_FILL      = 0x0008,
    LSCP_EVENT_CHANNEL_INFO     = 0x0010,
    LSCP_EVENT_MISCELLANEOUS    = 0x1000

} lscp_event_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 *pchBuffer,
    int cchBuffer,
    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_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);
const char **           lscp_get_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);

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


#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, 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 Lesser General Public
18	License along with this library; if not, write to the Free Software
19	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20
21	*****************************************************************************/
22
23	#ifndef __LSCP_CLIENT_H
24	#define __LSCP_CLIENT_H
25
26	#include "lscp/socket.h"
27
28	#if defined(__cplusplus)
29	extern "C" {
30	#endif
31
32
33	//-------------------------------------------------------------------------
34	// Client data structures.
35
36	/** Engine info cache struct. */
37	typedef struct _lscp_engine_info_t
38	{
39	char * description;
40	char * version;
41
42	} lscp_engine_info_t;
43
44
45	/** Channel info cache struct. */
46	typedef struct _lscp_channel_info_t
47	{
48	char * engine_name;
49	int audio_device;
50	int audio_channels;
51	char ** audio_routing;
52	char * instrument_file;
53	int instrument_nr;
54	int instrument_status;
55	int midi_device;
56	int midi_port;
57	int midi_channel;
58	float volume;
59
60	} lscp_channel_info_t;
61
62
63	/** Buffer fill cache struct. */
64	typedef struct _lscp_buffer_fill_t
65	{
66	unsigned int stream_id;
67	unsigned long stream_usage;
68
69	} lscp_buffer_fill_t;
70
71
72	/** Buffer fill stream usage types. */
73	typedef enum _lscp_usage_t
74	{
75	LSCP_USAGE_BYTES = 0,
76	LSCP_USAGE_PERCENTAGE
77
78	} lscp_usage_t;
79
80
81	/** Subscribable event notification bit-wise flags. */
82	typedef enum _lscp_event_t
83	{
84	LSCP_EVENT_NONE = 0x0000,
85	LSCP_EVENT_CHANNELS = 0x0001,
86	LSCP_EVENT_VOICE_COUNT = 0x0002,
87	LSCP_EVENT_STREAM_COUNT = 0x0004,
88	LSCP_EVENT_BUFFER_FILL = 0x0008,
89	LSCP_EVENT_CHANNEL_INFO = 0x0010,
90	LSCP_EVENT_MISCELLANEOUS = 0x1000
91
92	} lscp_event_t;
93
94
95	//-------------------------------------------------------------------------
96	// Client socket main structure.
97
98	/** Client opaque descriptor struct. */
99	typedef struct _lscp_client_t lscp_client_t;
100
101	/** Client event callback procedure prototype. */
102	typedef lscp_status_t (*lscp_client_proc_t)
103	(
104	struct _lscp_client_t *pClient,
105	lscp_event_t event,
106	const char *pchBuffer,
107	int cchBuffer,
108	void *pvData
109	);
110
111	//-------------------------------------------------------------------------
112	// Client versioning teller fuunction.
113
114	const char * lscp_client_package (void);
115	const char * lscp_client_version (void);
116	const char * lscp_client_build (void);
117
118	//-------------------------------------------------------------------------
119	// Client socket functions.
120
121	lscp_client_t * lscp_client_create (const char pszHost, int iPort, lscp_client_proc_t pfnCallback, void pvData);
122	lscp_status_t lscp_client_join (lscp_client_t *pClient);
123	lscp_status_t lscp_client_destroy (lscp_client_t *pClient);
124
125	lscp_status_t lscp_client_set_timeout (lscp_client_t *pClient, int iTimeout);
126	int lscp_client_get_timeout (lscp_client_t *pClient);
127
128	//-------------------------------------------------------------------------
129	// Client common protocol functions.
130
131	lscp_status_t lscp_client_query (lscp_client_t pClient, const char pszQuery);
132	const char * lscp_client_get_result (lscp_client_t *pClient );
133	int lscp_client_get_errno (lscp_client_t *pClient );
134
135	//-------------------------------------------------------------------------
136	// Client registration protocol functions.
137
138	lscp_status_t lscp_client_subscribe (lscp_client_t *pClient, lscp_event_t events);
139	lscp_status_t lscp_client_unsubscribe (lscp_client_t *pClient, lscp_event_t events);
140
141	lscp_event_t lscp_client_events (lscp_client_t *pClient);
142
143	//-------------------------------------------------------------------------
144	// Client command protocol functions.
145
146	lscp_status_t lscp_load_instrument (lscp_client_t pClient, const char pszFileName, int iInstrIndex, int iSamplerChannel);
147	lscp_status_t lscp_load_instrument_non_modal (lscp_client_t pClient, const char pszFileName, int iInstrIndex, int iSamplerChannel);
148	lscp_status_t lscp_load_engine (lscp_client_t pClient, const char pszEngineName, int iSamplerChannel);
149	int lscp_get_channels (lscp_client_t *pClient);
150	int * lscp_list_channels (lscp_client_t *pClient);
151	int lscp_add_channel (lscp_client_t *pClient);
152	lscp_status_t lscp_remove_channel (lscp_client_t *pClient, int iSamplerChannel);
153	const char ** lscp_get_available_engines (lscp_client_t *pClient);
154
155	lscp_engine_info_t * lscp_get_engine_info (lscp_client_t pClient, const char pszEngineName);
156	lscp_channel_info_t * lscp_get_channel_info (lscp_client_t *pClient, int iSamplerChannel);
157
158	int lscp_get_channel_voice_count (lscp_client_t *pClient, int iSamplerChannel);
159	int lscp_get_channel_stream_count (lscp_client_t *pClient, int iSamplerChannel);
160
161	lscp_buffer_fill_t * lscp_get_channel_buffer_fill (lscp_client_t *pClient, lscp_usage_t iUsageType, int iSamplerChannel);
162
163	lscp_status_t lscp_set_channel_audio_type (lscp_client_t pClient, int iSamplerChannel, const char pszAudioType);
164	lscp_status_t lscp_set_channel_audio_device (lscp_client_t *pClient, int iSamplerChannel, int iAudioDevice);
165	lscp_status_t lscp_set_channel_audio_channel (lscp_client_t *pClient, int iSamplerChannel, int iAudioOut, int iAudioIn);
166
167	lscp_status_t lscp_set_channel_midi_type (lscp_client_t pClient, int iSamplerChannel, const char pszMidiType);
168	lscp_status_t lscp_set_channel_midi_device (lscp_client_t *pClient, int iSamplerChannel, int iMidiDevice);
169	lscp_status_t lscp_set_channel_midi_port (lscp_client_t *pClient, int iSamplerChannel, int iMidiPort);
170	lscp_status_t lscp_set_channel_midi_channel (lscp_client_t *pClient, int iSamplerChannel, int iMidiChannel);
171	lscp_status_t lscp_set_channel_volume (lscp_client_t *pClient, int iSamplerChannel, float fVolume);
172
173	lscp_status_t lscp_reset_channel (lscp_client_t *pClient, int iSamplerChannel);
174
175
176	#if defined(__cplusplus)
177	}
178	#endif
179
180	#endif // __LSCP_CLIENT_H
181
182	// end of client.h