client.h

Go to the documentation of this file.
00001 // client.h
00002 //
00003 /****************************************************************************
00004    liblscp - LinuxSampler Control Protocol API
00005    Copyright (C) 2004-2008, rncbc aka Rui Nuno Capela. All rights reserved.
00006 
00007    This library is free software; you can redistribute it and/or
00008    modify it under the terms of the GNU Lesser General Public
00009    License as published by the Free Software Foundation; either
00010    version 2.1 of the License, or (at your option) any later version.
00011 
00012    This library is distributed in the hope that it will be useful,
00013    but WITHOUT ANY WARRANTY; without even the implied warranty of
00014    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
00015    Lesser General Public License for more details.
00016 
00017    You should have received a copy of the GNU General Public License along
00018    with this program; if not, write to the Free Software Foundation, Inc.,
00019    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
00020 
00021 *****************************************************************************/
00022 
00023 #ifndef __LSCP_CLIENT_H
00024 #define __LSCP_CLIENT_H
00025 
00026 #include "lscp/socket.h"
00027 #include "lscp/event.h"
00028 
00029 #if defined(__cplusplus)
00030 extern "C" {
00031 #endif
00032 
00033 //-------------------------------------------------------------------------
00034 // MIDI channel omni mode.
00035 
00036 #define LSCP_MIDI_CHANNEL_ALL   16
00037 
00038 
00039 //-------------------------------------------------------------------------
00040 // Client data structures.
00041 
00043 typedef struct _lscp_server_info_t
00044 {
00045     char *        description;
00046     char *        version;
00047     char *        protocol_version;
00048 
00049 } lscp_server_info_t;
00050 
00051 
00053 typedef struct _lscp_engine_info_t
00054 {
00055     char *        description;
00056     char *        version;
00057 
00058 } lscp_engine_info_t;
00059 
00060 
00062 typedef struct _lscp_channel_info_t
00063 {
00064     char *        engine_name;
00065     int           audio_device;
00066     int           audio_channels;
00067     int  *        audio_routing;
00068     char *        instrument_file;
00069     int           instrument_nr;
00070     char *        instrument_name;
00071     int           instrument_status;
00072     int           midi_device;
00073     int           midi_port;
00074     int           midi_channel;
00075     int           midi_map;
00076     float         volume;
00077     int           mute;
00078     int           solo;
00079 
00080 } lscp_channel_info_t;
00081 
00082 
00084 typedef struct _lscp_buffer_fill_t
00085 {
00086     unsigned int  stream_id;
00087     unsigned long stream_usage;
00088 
00089 } lscp_buffer_fill_t;
00090 
00091 
00093 typedef enum _lscp_usage_t
00094 {
00095     LSCP_USAGE_BYTES = 0,
00096     LSCP_USAGE_PERCENTAGE
00097 
00098 } lscp_usage_t;
00099 
00100 
00102 typedef struct _lscp_fxsend_info_t
00103 {
00104     char *        name;
00105     int           midi_controller;
00106     int *         audio_routing;
00107     float         level;
00108 
00109 } lscp_fxsend_info_t;
00110 
00111 
00113 typedef struct _lscp_midi_instrument_t
00114 {
00115     int           map;
00116     int           bank;
00117     int           prog;
00118 
00119 } lscp_midi_instrument_t;
00120 
00121 
00123 typedef enum _lscp_load_mode_t
00124 {
00125     LSCP_LOAD_DEFAULT = 0,
00126     LSCP_LOAD_ON_DEMAND,
00127     LSCP_LOAD_ON_DEMAND_HOLD,
00128     LSCP_LOAD_PERSISTENT
00129 
00130 } lscp_load_mode_t;
00131 
00132 
00134 typedef struct _lscp_midi_instrument_info_t
00135 {
00136     char *           name;
00137     char *           engine_name;
00138     char *           instrument_file;
00139     int              instrument_nr;
00140     char *           instrument_name;
00141     lscp_load_mode_t load_mode;
00142     float            volume;
00143 
00144 } lscp_midi_instrument_info_t;
00145 
00146 
00148 typedef enum _lscp_midi_map_mode_t
00149 {
00150     LSCP_MIDI_MAP_NONE = -1,
00151     LSCP_MIDI_MAP_DEFAULT = -2,
00152     LSCP_MIDI_MAP_ALL = -3
00153 
00154 } lscp_midi_map_mode_t;
00155 
00156 
00157 //-------------------------------------------------------------------------
00158 // Client socket main structure.
00159 
00161 typedef struct _lscp_client_t lscp_client_t;
00162 
00164 typedef lscp_status_t (*lscp_client_proc_t)
00165 (
00166     struct _lscp_client_t *pClient,
00167     lscp_event_t event,
00168     const char *pchData,
00169     int cchData,
00170     void *pvData
00171 );
00172 
00173 //-------------------------------------------------------------------------
00174 // Client versioning teller function.
00175 
00176 const char *            lscp_client_package             (void);
00177 const char *            lscp_client_version             (void);
00178 const char *            lscp_client_build               (void);
00179 
00180 //-------------------------------------------------------------------------
00181 // Client socket functions.
00182 
00183 lscp_client_t *         lscp_client_create              (const char *pszHost, int iPort, lscp_client_proc_t pfnCallback, void *pvData);
00184 lscp_status_t           lscp_client_join                (lscp_client_t *pClient);
00185 lscp_status_t           lscp_client_destroy             (lscp_client_t *pClient);
00186 
00187 lscp_status_t           lscp_client_set_timeout         (lscp_client_t *pClient, int iTimeout);
00188 int                     lscp_client_get_timeout         (lscp_client_t *pClient);
00189 
00190 //-------------------------------------------------------------------------
00191 // Client common protocol functions.
00192 
00193 lscp_status_t           lscp_client_query               (lscp_client_t *pClient, const char *pszQuery);
00194 const char *            lscp_client_get_result          (lscp_client_t *pClient );
00195 int                     lscp_client_get_errno           (lscp_client_t *pClient );
00196 
00197 //-------------------------------------------------------------------------
00198 // Client registration protocol functions.
00199 
00200 lscp_status_t           lscp_client_subscribe           (lscp_client_t *pClient, lscp_event_t events);
00201 lscp_status_t           lscp_client_unsubscribe         (lscp_client_t *pClient, lscp_event_t events);
00202 
00203 lscp_event_t            lscp_client_get_events          (lscp_client_t *pClient);
00204 
00205 //-------------------------------------------------------------------------
00206 // Client command protocol functions.
00207 
00208 lscp_status_t           lscp_load_instrument            (lscp_client_t *pClient, const char *pszFileName, int iInstrIndex, int iSamplerChannel);
00209 lscp_status_t           lscp_load_instrument_non_modal  (lscp_client_t *pClient, const char *pszFileName, int iInstrIndex, int iSamplerChannel);
00210 lscp_status_t           lscp_load_engine                (lscp_client_t *pClient, const char *pszEngineName, int iSamplerChannel);
00211 int                     lscp_get_channels               (lscp_client_t *pClient);
00212 int *                   lscp_list_channels              (lscp_client_t *pClient);
00213 int                     lscp_add_channel                (lscp_client_t *pClient);
00214 lscp_status_t           lscp_remove_channel             (lscp_client_t *pClient, int iSamplerChannel);
00215 
00216 int                     lscp_get_available_engines      (lscp_client_t *pClient);
00217 const char **           lscp_list_available_engines     (lscp_client_t *pClient);
00218 
00219 lscp_engine_info_t *    lscp_get_engine_info            (lscp_client_t *pClient, const char *pszEngineName);
00220 lscp_channel_info_t *   lscp_get_channel_info           (lscp_client_t *pClient, int iSamplerChannel);
00221 
00222 int                     lscp_get_channel_voice_count    (lscp_client_t *pClient, int iSamplerChannel);
00223 int                     lscp_get_channel_stream_count   (lscp_client_t *pClient, int iSamplerChannel);
00224 int                     lscp_get_channel_stream_usage   (lscp_client_t *pClient, int iSamplerChannel);
00225 
00226 lscp_buffer_fill_t *    lscp_get_channel_buffer_fill    (lscp_client_t *pClient, lscp_usage_t iUsageType, int iSamplerChannel);
00227 
00228 lscp_status_t           lscp_set_channel_audio_type     (lscp_client_t *pClient, int iSamplerChannel, const char *pszAudioType);
00229 lscp_status_t           lscp_set_channel_audio_device   (lscp_client_t *pClient, int iSamplerChannel, int iAudioDevice);
00230 lscp_status_t           lscp_set_channel_audio_channel  (lscp_client_t *pClient, int iSamplerChannel, int iAudioOut, int iAudioIn);
00231 
00232 lscp_status_t           lscp_set_channel_midi_type      (lscp_client_t *pClient, int iSamplerChannel, const char *pszMidiType);
00233 lscp_status_t           lscp_set_channel_midi_device    (lscp_client_t *pClient, int iSamplerChannel, int iMidiDevice);
00234 lscp_status_t           lscp_set_channel_midi_port      (lscp_client_t *pClient, int iSamplerChannel, int iMidiPort);
00235 lscp_status_t           lscp_set_channel_midi_channel   (lscp_client_t *pClient, int iSamplerChannel, int iMidiChannel);
00236 lscp_status_t           lscp_set_channel_midi_map       (lscp_client_t *pClient, int iSamplerChannel, int iMidiMap);
00237 
00238 lscp_status_t           lscp_set_channel_volume         (lscp_client_t *pClient, int iSamplerChannel, float fVolume);
00239 
00240 lscp_status_t           lscp_set_channel_mute           (lscp_client_t *pClient, int iSamplerChannel, int iMute);
00241 lscp_status_t           lscp_set_channel_solo           (lscp_client_t *pClient, int iSamplerChannel, int iSolo);
00242 
00243 lscp_status_t           lscp_reset_channel              (lscp_client_t *pClient, int iSamplerChannel);
00244 
00245 lscp_status_t           lscp_reset_sampler              (lscp_client_t *pClient);
00246 
00247 lscp_server_info_t *    lscp_get_server_info            (lscp_client_t *pClient);
00248 
00249 int                     lscp_get_total_voice_count      (lscp_client_t *pClient);
00250 int                     lscp_get_total_voice_count_max  (lscp_client_t *pClient);
00251 
00252 float                   lscp_get_volume                 (lscp_client_t *pClient);
00253 lscp_status_t           lscp_set_volume                 (lscp_client_t *pClient, float fVolume);
00254 
00255 int                     lscp_get_voices                 (lscp_client_t *pClient);
00256 lscp_status_t           lscp_set_voices                 (lscp_client_t *pClient, int iMaxVoices);
00257 
00258 int                     lscp_get_streams                (lscp_client_t *pClient);
00259 lscp_status_t           lscp_set_streams                (lscp_client_t *pClient, int iMaxStreams);
00260 
00261 //-------------------------------------------------------------------------
00262 // Effect sends control functions.
00263 
00264 int                     lscp_create_fxsend              (lscp_client_t *pClient, int iSamplerChannel, int iMidiController, const char *pszFxName);
00265 lscp_status_t           lscp_destroy_fxsend             (lscp_client_t *pClient, int iSamplerChannel, int iFxSend);
00266 
00267 int                     lscp_get_fxsends                (lscp_client_t *pClient, int iSamplerChannel);
00268 int *                   lscp_list_fxsends               (lscp_client_t *pClient, int iSamplerChannel);
00269 
00270 lscp_fxsend_info_t *    lscp_get_fxsend_info            (lscp_client_t *pClient, int iSamplerChannel, int iFxSend);
00271 
00272 lscp_status_t           lscp_set_fxsend_name            (lscp_client_t *pClient, int iSamplerChannel, int iFxSend, const char *pszFxName);
00273 lscp_status_t           lscp_set_fxsend_audio_channel   (lscp_client_t *pClient, int iSamplerChannel, int iFxSend, int iAudioSrc, int iAudioDst);
00274 lscp_status_t           lscp_set_fxsend_midi_controller (lscp_client_t *pClient, int iSamplerChannel, int iFxSend, int iMidiController);
00275 lscp_status_t           lscp_set_fxsend_level           (lscp_client_t *pClient, int iSamplerChannel, int iFxSend, float fLevel);
00276 
00277 //-------------------------------------------------------------------------
00278 // MIDI instrument mapping control functions.
00279 
00280 int                     lscp_add_midi_instrument_map    (lscp_client_t *pClient, const char *pszMapName);
00281 lscp_status_t           lscp_remove_midi_instrument_map (lscp_client_t *pClient, int iMidiMap);
00282 
00283 int                     lscp_get_midi_instrument_maps   (lscp_client_t *pClient);
00284 int *                   lscp_list_midi_instrument_maps  (lscp_client_t *pClient);
00285 
00286 const char *            lscp_get_midi_instrument_map_name (lscp_client_t *pClient, int iMidiMap);
00287 lscp_status_t           lscp_set_midi_instrument_map_name (lscp_client_t *pClient, int iMidiMap, const char *pszMapName);
00288 
00289 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);
00290 lscp_status_t           lscp_unmap_midi_instrument      (lscp_client_t *pClient, lscp_midi_instrument_t *pMidiInstr);
00291 
00292 int                     lscp_get_midi_instruments       (lscp_client_t *pClient, int iMidiMap);
00293 lscp_midi_instrument_t *lscp_list_midi_instruments      (lscp_client_t *pClient, int iMidiMap);
00294 
00295 lscp_midi_instrument_info_t *lscp_get_midi_instrument_info(lscp_client_t *pClient, lscp_midi_instrument_t *pMidiInstr);
00296 
00297 lscp_status_t           lscp_clear_midi_instruments     (lscp_client_t *pClient, int iMidiMap);
00298 
00299 //-------------------------------------------------------------------------
00300 // Instrument editor functions.
00301 
00302 lscp_status_t           lscp_edit_channel_instrument    (lscp_client_t *pClient, int iSamplerChannel);
00303 
00304 #if defined(__cplusplus)
00305 }
00306 #endif
00307 
00308 #endif // __LSCP_CLIENT_H
00309 
00310 // end of client.h