client.h File Reference

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

Go to the source code of this file.

Data Structures
struct	lscp_server_info_t
struct	lscp_engine_info_t
struct	lscp_channel_info_t
struct	lscp_buffer_fill_t
Defines
#define	LSCP_MIDI_CHANNEL_ALL   16
Typedefs
typedef enum _lscp_usage_t	lscp_usage_t
typedef struct _lscp_client_t	lscp_client_t
typedef lscp_status_t(*	lscp_client_proc_t )(struct _lscp_client_t *pClient, lscp_event_t event, const char *pchData, int cchData, void *pvData)
Enumerations
enum	_lscp_usage_t { LSCP_USAGE_BYTES = 0, LSCP_USAGE_PERCENTAGE }
Functions
const char *	lscp_client_package (void)
const char *	lscp_client_version (void)
const char *	lscp_client_build (void)
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)
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)
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)
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)

---

Define Documentation

#define LSCP_MIDI_CHANNEL_ALL   16

---

Typedef Documentation

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 event callback procedure prototype.

typedef struct _lscp_client_t lscp_client_t

Client opaque descriptor struct.

typedef enum _lscp_usage_t lscp_usage_t

Buffer fill stream usage types.

---

Enumeration Type Documentation

enum _lscp_usage_t

Buffer fill stream usage types.

Enumerator:

LSCP_USAGE_BYTES
LSCP_USAGE_PERCENTAGE

---

Function Documentation

int lscp_add_channel

(

lscp_client_t *

pClient

)

Adding a new sampler channel: ADD CHANNEL

Parameters:

pClient

Pointer to client instance structure.

Returns:

The new sampler channel number identifier, or -1 in case of failure.

const char* lscp_client_build

(

void

)

Retrieve the current client library build timestamp string.

lscp_client_t* lscp_client_create	(	const char *	pszHost,
		int	iPort,
		lscp_client_proc_t	pfnCallback,
		void *	pvData
	)

Create a client instance, estabilishing a connection to a server hostname, which must be listening on the given port. A client callback function is also supplied for server notification event handling.

Parameters:

	pszHost	Hostname of the linuxsampler listening server.
	iPort	Port number of the linuxsampler listening server.
	pfnCallback	Callback function to receive event notifications.
	pvData	User context opaque data, that will be passed to the callback function.

Returns:

The new client instance pointer if successfull, which shall be used on all subsequent client calls, NULL otherwise.

lscp_status_t lscp_client_destroy

(

lscp_client_t *

pClient

)

Terminate and destroy a client instance.

Parameters:

pClient

Pointer to client instance structure.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

int lscp_client_get_errno

(

lscp_client_t *

pClient

)

Get the last error/warning number received.

Parameters:

pClient

Pointer to client instance structure.

Returns:

The numerical value of the last error or warning response code received.

lscp_event_t lscp_client_get_events

(

lscp_client_t *

pClient

)

Getting current subscribed events.

Parameters:

pClient

Pointer to client instance structure.

Returns:

The current subscrived bit-wise OR'ed event flags.

const char* lscp_client_get_result

(

lscp_client_t *

pClient

)

Get the last received result string. In case of error or warning, this is the text of the error or warning message issued.

Parameters:

pClient

Pointer to client instance structure.

Returns:

A pointer to the literal null-terminated result string as of the last command request.

int lscp_client_get_timeout

(

lscp_client_t *

pClient

)

Get the client transaction timeout interval.

Parameters:

pClient

Pointer to client instance structure.

Returns:

The current timeout value milliseconds, -1 in case of failure.

lscp_status_t lscp_client_join

(

lscp_client_t *

pClient

)

Wait for a client instance to terminate graciously.

Parameters:

pClient

Pointer to client instance structure.

const char* lscp_client_package

(

void

)

Retrieve the current client library version string.

lscp_status_t lscp_client_query	(	lscp_client_t *	pClient,
		const char *	pszQuery
	)

Submit a command query line string to the server. The query string must be cr/lf and null terminated. Besides the return code, the specific server response to the command request is made available by the lscp_client_get_result and lscp_client_get_errno function calls.

Parameters:

	pClient	Pointer to client instance structure.
	pszQuery	Command request line to be sent to server, must be cr/lf and null terminated.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_client_set_timeout	(	lscp_client_t *	pClient,
		int	iTimeout
	)

Set the client transaction timeout interval.

Parameters:

	pClient	Pointer to client instance structure.
	iTimeout	Transaction timeout in milliseconds.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_client_subscribe	(	lscp_client_t *	pClient,
		lscp_event_t	events
	)

Register frontend for receiving event messages: SUBSCRIBE CHANNEL_COUNT | VOICE_COUNT | STREAM_COUNT | BUFFER_FILL | CHANNEL_INFO | MISCELLANEOUS

Parameters:

	pClient	Pointer to client instance structure.
	events	Bit-wise OR'ed event flags to subscribe.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_client_unsubscribe	(	lscp_client_t *	pClient,
		lscp_event_t	events
	)

Deregister frontend from receiving UDP event messages anymore: SUBSCRIBE CHANNEL_COUNT | VOICE_COUNT | STREAM_COUNT | BUFFER_FILL | CHANNEL_INFO | MISCELLANEOUS

Parameters:

	pClient	Pointer to client instance structure.
	events	Bit-wise OR'ed event flags to unsubscribe.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

const char* lscp_client_version

(

void

)

Retrieve the current client library version string.

int lscp_get_available_engines

(

lscp_client_t *

pClient

)

Getting all available engines count: GET AVAILABLE_ENGINES

Parameters:

pClient

Pointer to client instance structure.

Returns:

The current total number of sampler engines on success, -1 otherwise.

lscp_buffer_fill_t* lscp_get_channel_buffer_fill	(	lscp_client_t *	pClient,
		lscp_usage_t	usage_type,
		int	iSamplerChannel
	)

Current fill state of disk stream buffers: GET CHANNEL BUFFER_FILL {BYTES|PERCENTAGE} <sampler-channel>

Parameters:

	pClient	Pointer to client instance structure.
	usage_type	Usage type to be returned, either LSCP_USAGE_BYTES, or LSCP_USAGE_PERCENTAGE.
	iSamplerChannel	Sampler channel number.

Returns:

A pointer to a lscp_buffer_fill_t structure, with the information of the current disk stream buffer fill usage, for the given sampler channel, or NULL in case of failure.

lscp_channel_info_t* lscp_get_channel_info	(	lscp_client_t *	pClient,
		int	iSamplerChannel
	)

Getting sampler channel informations: GET CHANNEL INFO <sampler-channel>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.

Returns:

A pointer to a lscp_channel_info_t structure, with all the information of the given sampler channel, or NULL in case of failure.

int lscp_get_channel_stream_count	(	lscp_client_t *	pClient,
		int	iSamplerChannel
	)

Current number of active disk streams: GET CHANNEL STREAM_COUNT <sampler-channel>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.

Returns:

The number of active disk streams on success, -1 otherwise.

int lscp_get_channel_stream_usage	(	lscp_client_t *	pClient,
		int	iSamplerChannel
	)

Current least usage of active disk streams.

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.

Returns:

The usage percentage of the least filled active disk stream on success, -1 otherwise.

int lscp_get_channel_voice_count	(	lscp_client_t *	pClient,
		int	iSamplerChannel
	)

Current number of active voices: GET CHANNEL VOICE_COUNT <sampler-channel>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.

Returns:

The number of voices currently active, -1 in case of failure.

int lscp_get_channels

(

lscp_client_t *

pClient

)

Current number of sampler channels: GET CHANNELS

Parameters:

pClient

Pointer to client instance structure.

Returns:

The current total number of sampler channels on success, -1 otherwise.

lscp_engine_info_t* lscp_get_engine_info	(	lscp_client_t *	pClient,
		const char *	pszEngineName
	)

Getting information about an engine. GET ENGINE INFO <engine-name>

Parameters:

	pClient	Pointer to client instance structure.
	pszEngineName	Engine name.

Returns:

A pointer to a lscp_engine_info_t structure, with all the information of the given sampler engine, or NULL in case of failure.

lscp_server_info_t* lscp_get_server_info

(

lscp_client_t *

pClient

)

Getting information about the server. GET SERVER INFO

Parameters:

pClient

Pointer to client instance structure.

Returns:

A pointer to a lscp_server_info_t structure, with all the information of the current connected server, or NULL in case of failure.

const char** lscp_list_available_engines

(

lscp_client_t *

pClient

)

Getting all available engines: LIST AVAILABLE_ENGINES

Parameters:

pClient

Pointer to client instance structure.

Returns:

A NULL terminated array of engine name strings, or NULL in case of failure.

int* lscp_list_channels

(

lscp_client_t *

pClient

)

List current sampler channels number identifiers: LIST CHANNELS

Parameters:

pClient

Pointer to client instance structure.

Returns:

An array of the sampler channels identifiers as positive integers, terminated with -1 on success, NULL otherwise.

lscp_status_t lscp_load_engine	(	lscp_client_t *	pClient,
		const char *	pszEngineName,
		int	iSamplerChannel
	)

Loading a sampler engine: LOAD ENGINE <engine-name> <sampler-channel>

Parameters:

	pClient	Pointer to client instance structure.
	pszEngineName	Engine name.
	iSamplerChannel	Sampler channel number.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_load_instrument	(	lscp_client_t *	pClient,
		const char *	pszFileName,
		int	iInstrIndex,
		int	iSamplerChannel
	)

Loading an instrument: LOAD INSTRUMENT <filename> <instr-index> <sampler-channel>

Parameters:

	pClient	Pointer to client instance structure.
	pszFileName	Instrument file name.
	iInstrIndex	Instrument index number.
	iSamplerChannel	Sampler Channel.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_load_instrument_non_modal	(	lscp_client_t *	pClient,
		const char *	pszFileName,
		int	iInstrIndex,
		int	iSamplerChannel
	)

Loading an instrument in the background (non modal): LOAD INSTRUMENT NON_MODAL <filename> <instr-index> <sampler-channel>

Parameters:

	pClient	Pointer to client instance structure.
	pszFileName	Instrument file name.
	iInstrIndex	Instrument index number.
	iSamplerChannel	Sampler Channel.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_remove_channel	(	lscp_client_t *	pClient,
		int	iSamplerChannel
	)

Removing a sampler channel: REMOVE CHANNEL <sampler-channel>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_reset_channel	(	lscp_client_t *	pClient,
		int	iSamplerChannel
	)

Resetting a sampler channel: RESET CHANNEL <sampler-channel>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_reset_sampler

(

lscp_client_t *

pClient

)

Resetting the sampler: RESET

Parameters:

pClient

Pointer to client instance structure.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_set_channel_audio_channel	(	lscp_client_t *	pClient,
		int	iSamplerChannel,
		int	iAudioOut,
		int	iAudioIn
	)

Setting audio output channel: SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-channel> <audio-output-chan> <audio-input-chan>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.
	iAudioOut	Audio output device channel to be routed from.
	iAudioIn	Audio output device channel to be routed into.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_set_channel_audio_device	(	lscp_client_t *	pClient,
		int	iSamplerChannel,
		int	iAudioDevice
	)

Setting audio output device: SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel> <device-id>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.
	iAudioDevice	Audio output device number identifier.

lscp_status_t lscp_set_channel_audio_type	(	lscp_client_t *	pClient,
		int	iSamplerChannel,
		const char *	pszAudioDriver
	)

Setting audio output type: SET CHANNEL AUDIO_OUTPUT_TYPE <sampler-channel> <audio-output-type>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.
	pszAudioDriver	Audio output driver type (e.g. "ALSA" or "JACK").

lscp_status_t lscp_set_channel_midi_channel	(	lscp_client_t *	pClient,
		int	iSamplerChannel,
		int	iMidiChannel
	)

Setting MIDI input channel: SET CHANNEL MIDI_INPUT_CHANNEL <sampler-channel> <midi-input-chan>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.
	iMidiChannel	MIDI channel address number to listen (0-15) or LSCP_MIDI_CHANNEL_ALL (16) to listen on all channels.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_set_channel_midi_device	(	lscp_client_t *	pClient,
		int	iSamplerChannel,
		int	iMidiDevice
	)

Setting MIDI input device: SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <device-id>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.
	iMidiDevice	MIDI input device number identifier.

lscp_status_t lscp_set_channel_midi_port	(	lscp_client_t *	pClient,
		int	iSamplerChannel,
		int	iMidiPort
	)

Setting MIDI input port: SET CHANNEL MIDI_INPUT_PORT <sampler-channel> <midi-input-port>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.
	iMidiPort	MIDI input driver virtual port number.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_set_channel_midi_type	(	lscp_client_t *	pClient,
		int	iSamplerChannel,
		const char *	pszMidiDriver
	)

Setting MIDI input type: SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.
	pszMidiDriver	MIDI input driver type (e.g. "ALSA").

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_set_channel_mute	(	lscp_client_t *	pClient,
		int	iSamplerChannel,
		int	iMute
	)

Muting a sampler channel: SET CHANNEL MUTE <sampler-channel> <mute>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.
	iMute	Sampler channel mute state as a boolean value, either 1 (one) to mute the channel or 0 (zero) to unmute the channel.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_set_channel_solo	(	lscp_client_t *	pClient,
		int	iSamplerChannel,
		int	iSolo
	)

Soloing a sampler channel: SET CHANNEL SOLO <sampler-channel> <solo>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.
	iSolo	Sampler channel solo state as a boolean value, either 1 (one) to solo the channel or 0 (zero) to unsolo the channel.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

lscp_status_t lscp_set_channel_volume	(	lscp_client_t *	pClient,
		int	iSamplerChannel,
		float	fVolume
	)

Setting channel volume: SET CHANNEL VOLUME <sampler-channel> <volume>

Parameters:

	pClient	Pointer to client instance structure.
	iSamplerChannel	Sampler channel number.
	fVolume	Sampler channel volume as a positive floating point number, where a value less than 1.0 for attenuation, and greater than 1.0 for amplification.

Returns:

LSCP_OK on success, LSCP_FAILED otherwise.

---