1 /* 2 Copyright (C) 2009-2010 Grame 3 4 This program is free software; you can redistribute it and/or modify 5 it under the terms of the GNU Lesser General Public License as published by 6 the Free Software Foundation; either version 2.1 of the License, or 7 (at your option) any later version. 8 9 This program is distributed in the hope that it will be useful, 10 but WITHOUT ANY WARRANTY; without even the implied warranty of 11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 GNU Lesser General Public License for more details. 13 14 You should have received a copy of the GNU Lesser General Public License 15 along with this program; if not, write to the Free Software 16 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 17 18 */ 19 20 #ifndef __net_h__ 21 #define __net_h__ 22 23 #ifdef __cplusplus 24 extern "C" 25 { 26 #endif 27 28 #include <jack/systemdeps.h> 29 #include <jack/types.h> 30 #include <jack/weakmacros.h> 31 32 #define DEFAULT_MULTICAST_IP "225.3.19.154" 33 #define DEFAULT_PORT 19000 34 #define DEFAULT_MTU 1500 35 #define MASTER_NAME_SIZE 256 36 37 // Possible error codes 38 39 #define NO_ERROR 0 40 #define SOCKET_ERROR -1 41 #define SYNC_PACKET_ERROR -2 42 #define DATA_PACKET_ERROR -3 43 44 #define RESTART_CB_API 1 45 46 enum JackNetEncoder { 47 48 JackFloatEncoder = 0, // samples are transmitted as float 49 JackIntEncoder = 1, // samples are transmitted as 16 bits integer 50 JackCeltEncoder = 2, // samples are transmitted using CELT codec (http://www.celt-codec.org/) 51 JackOpusEncoder = 3, // samples are transmitted using OPUS codec (http://www.opus-codec.org/) 52 }; 53 54 typedef struct { 55 56 int audio_input; // from master or to slave (-1 to take master audio physical inputs) 57 int audio_output; // to master or from slave (-1 to take master audio physical outputs) 58 int midi_input; // from master or to slave (-1 to take master MIDI physical inputs) 59 int midi_output; // to master or from slave (-1 to take master MIDI physical outputs) 60 int mtu; // network Maximum Transmission Unit 61 int time_out; // in second, -1 means infinite 62 int encoder; // encoder type (one of JackNetEncoder) 63 int kbps; // KB per second for CELT or OPUS codec 64 int latency; // network latency in number of buffers 65 66 } jack_slave_t; 67 68 typedef struct { 69 70 int audio_input; // master audio physical outputs (-1 to take slave wanted audio inputs) 71 int audio_output; // master audio physical inputs (-1 to take slave wanted audio outputs) 72 int midi_input; // master MIDI physical outputs (-1 to take slave wanted MIDI inputs) 73 int midi_output; // master MIDI physical inputs (-1 to take slave wanted MIDI outputs) 74 jack_nframes_t buffer_size; // master buffer size 75 jack_nframes_t sample_rate; // master sample rate 76 char master_name[MASTER_NAME_SIZE]; // master machine name 77 int time_out; // in second, -1 means infinite 78 int partial_cycle; // if 'true', partial buffers will be used 79 80 } jack_master_t; 81 82 /** 83 * jack_net_slave_t is an opaque type. You may only access it using the 84 * API provided. 85 */ 86 typedef struct _jack_net_slave jack_net_slave_t; 87 88 /** 89 * Open a network connection with the master machine. 90 * 91 * @param ip the multicast address of the master 92 * @param port the connection port 93 * @param name the JACK client name 94 * @param request a connection request structure 95 * @param result a connection result structure 96 * 97 * @return Opaque net handle if successful or NULL in case of error. 98 */ 99 jack_net_slave_t* jack_net_slave_open(const char* ip, int port, const char* name, jack_slave_t* request, jack_master_t* result); 100 101 /** 102 * Close the network connection with the master machine. 103 * 104 * @param net the network connection to be closed 105 * 106 * @return 0 on success, otherwise a non-zero error code 107 */ 108 int jack_net_slave_close(jack_net_slave_t* net); 109 110 /** 111 * Prototype for Process callback. 112 * 113 * @param nframes buffer size 114 * @param audio_input number of audio inputs 115 * @param audio_input_buffer an array of audio input buffers (from master) 116 * @param midi_input number of MIDI inputs 117 * @param midi_input_buffer an array of MIDI input buffers (from master) 118 * @param audio_output number of audio outputs 119 * @param audio_output_buffer an array of audio output buffers (to master) 120 * @param midi_output number of MIDI outputs 121 * @param midi_output_buffer an array of MIDI output buffers (to master) 122 * @param arg pointer to a client supplied structure supplied by jack_set_net_process_callback() 123 * 124 * @return zero on success, non-zero on error 125 */ 126 typedef int (* JackNetSlaveProcessCallback) (jack_nframes_t buffer_size, 127 int audio_input, 128 float** audio_input_buffer, 129 int midi_input, 130 void** midi_input_buffer, 131 int audio_output, 132 float** audio_output_buffer, 133 int midi_output, 134 void** midi_output_buffer, 135 void* data); 136 137 /** 138 * Set network process callback. 139 * 140 * @param net the network connection 141 * @param net_callback the process callback 142 * @param arg pointer to a client supplied structure 143 * 144 * @return 0 on success, otherwise a non-zero error code 145 */ 146 int jack_set_net_slave_process_callback(jack_net_slave_t * net, JackNetSlaveProcessCallback net_callback, void *arg); 147 148 /** 149 * Start processing thread, the net_callback will start to be called. 150 * 151 * @param net the network connection 152 * 153 * @return 0 on success, otherwise a non-zero error code 154 */ 155 int jack_net_slave_activate(jack_net_slave_t* net); 156 157 /** 158 * Stop processing thread. 159 * 160 * @param net the network connection 161 * 162 * @return 0 on success, otherwise a non-zero error code 163 */ 164 int jack_net_slave_deactivate(jack_net_slave_t* net); 165 166 /** 167 * Test if slave is still active. 168 * 169 * @param net the network connection 170 * 171 * @return a boolean 172 */ 173 int jack_net_slave_is_active(jack_net_slave_t* net); 174 175 /** 176 * Prototype for BufferSize callback. 177 * 178 * @param nframes buffer size 179 * @param arg pointer to a client supplied structure supplied by jack_set_net_buffer_size_callback() 180 * 181 * @return zero on success, non-zero on error 182 */ 183 typedef int (*JackNetSlaveBufferSizeCallback)(jack_nframes_t nframes, void *arg); 184 185 /** 186 * Set network buffer size callback. 187 * 188 * @param net the network connection 189 * @param bufsize_callback the buffer size callback 190 * @param arg pointer to a client supplied structure 191 * 192 * @return 0 on success, otherwise a non-zero error code 193 */ 194 int jack_set_net_slave_buffer_size_callback(jack_net_slave_t *net, JackNetSlaveBufferSizeCallback bufsize_callback, void *arg); 195 196 /** 197 * Prototype for SampleRate callback. 198 * 199 * @param nframes sample rate 200 * @param arg pointer to a client supplied structure supplied by jack_set_net_sample_rate_callback() 201 * 202 * @return zero on success, non-zero on error 203 */ 204 typedef int (*JackNetSlaveSampleRateCallback)(jack_nframes_t nframes, void *arg); 205 206 /** 207 * Set network sample rate callback. 208 * 209 * @param net the network connection 210 * @param samplerate_callback the sample rate callback 211 * @param arg pointer to a client supplied structure 212 * 213 * @return 0 on success, otherwise a non-zero error code 214 */ 215 int jack_set_net_slave_sample_rate_callback(jack_net_slave_t *net, JackNetSlaveSampleRateCallback samplerate_callback, void *arg); 216 217 /** 218 * Prototype for server Shutdown callback (if not set, the client will just restart, waiting for an available master again). 219 * 220 * @param arg pointer to a client supplied structure supplied by jack_set_net_shutdown_callback() 221 */ 222 typedef void (*JackNetSlaveShutdownCallback)(void* arg); 223 224 /** 225 * Set network shutdown callback. 226 * 227 * @param net the network connection 228 * @param shutdown_callback the shutdown callback 229 * @param arg pointer to a client supplied structure 230 * 231 * @return 0 on success, otherwise a non-zero error code 232 */ 233 int jack_set_net_slave_shutdown_callback(jack_net_slave_t *net, JackNetSlaveShutdownCallback shutdown_callback, void *arg) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 234 235 /** 236 * Prototype for server Restart callback : this is the new preferable way to be notified when the master has disappeared. 237 * The client may want to retry connecting a certain number of time (which will be done using the time_out value given in jack_net_slave_open) 238 * by returning 0. Otherwise returning a non-zero error code will definively close the connection 239 * (and jack_net_slave_is_active will later on return false). 240 * If both Shutdown and Restart are supplied, Restart callback will be used. 241 * 242 * @param arg pointer to a client supplied structure supplied by jack_set_net_restart_callback() 243 * 244 * @return 0 on success, otherwise a non-zero error code 245 */ 246 typedef int (*JackNetSlaveRestartCallback)(void* arg); 247 248 /** 249 * Set network restart callback. 250 * 251 * @param net the network connection 252 * @param restart_callback the shutdown callback 253 * @param arg pointer to a client supplied structure 254 * 255 * @return 0 on success, otherwise a non-zero error code 256 */ 257 int jack_set_net_slave_restart_callback(jack_net_slave_t *net, JackNetSlaveRestartCallback restart_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT; 258 259 /** 260 * Prototype for server Error callback. 261 * 262 * @param error_code an error code (see "Possible error codes") 263 * @param arg pointer to a client supplied structure supplied by jack_set_net_error_callback() 264 */ 265 typedef void (*JackNetSlaveErrorCallback) (int error_code, void* arg); 266 267 /** 268 * Set error restart callback. 269 * 270 * @param net the network connection 271 * @param error_callback the error callback 272 * @param arg pointer to a client supplied structure 273 * 274 * @return 0 on success, otherwise a non-zero error code 275 */ 276 int jack_set_net_slave_error_callback(jack_net_slave_t *net, JackNetSlaveErrorCallback error_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT; 277 278 /** 279 * jack_net_master_t is an opaque type, you may only access it using the API provided. 280 */ 281 typedef struct _jack_net_master jack_net_master_t; 282 283 /** 284 * Open a network connection with the slave machine. 285 * 286 * @param ip the multicast address of the master 287 * @param port the connection port 288 * @param request a connection request structure 289 * @param result a connection result structure 290 * 291 * @return Opaque net handle if successful or NULL in case of error. 292 */ 293 jack_net_master_t* jack_net_master_open(const char* ip, int port, jack_master_t* request, jack_slave_t* result); 294 295 /** 296 * Close the network connection with the slave machine. 297 * 298 * @param net the network connection to be closed 299 * 300 * @return 0 on success, otherwise a non-zero error code 301 */ 302 int jack_net_master_close(jack_net_master_t* net); 303 304 /** 305 * Receive sync and data from the network (complete buffer). 306 * 307 * @param net the network connection 308 * @param audio_input number of audio inputs 309 * @param audio_input_buffer an array of audio input buffers 310 * @param midi_input number of MIDI inputs 311 * @param midi_input_buffer an array of MIDI input buffers 312 * 313 * @return zero on success, non-zero on error 314 */ 315 int jack_net_master_recv(jack_net_master_t* net, int audio_input, float** audio_input_buffer, int midi_input, void** midi_input_buffer); 316 317 /** 318 * Receive sync and data from the network (incomplete buffer). 319 * 320 * @param net the network connection 321 * @param audio_input number of audio inputs 322 * @param audio_input_buffer an array of audio input buffers 323 * @param midi_input number of MIDI inputs 324 * @param midi_input_buffer an array of MIDI input buffers 325 * @param frames the number of frames to receive 326 * 327 * @return zero on success, non-zero on error 328 */ 329 int jack_net_master_recv_slice(jack_net_master_t* net, int audio_input, float** audio_input_buffer, int midi_input, void** midi_input_buffer, int frames); 330 331 /** 332 * Send sync and data to the network (complete buffer). 333 * 334 * @param net the network connection 335 * @param audio_output number of audio outputs 336 * @param audio_output_buffer an array of audio output buffers 337 * @param midi_output number of MIDI outputs 338 * @param midi_output_buffer an array of MIDI output buffers 339 * 340 * @return zero on success, non-zero on error 341 */ 342 int jack_net_master_send(jack_net_master_t* net, int audio_output, float** audio_output_buffer, int midi_output, void** midi_output_buffer); 343 344 /** 345 * Send sync and data to the network (incomplete buffer). 346 * 347 * @param net the network connection 348 * @param audio_output number of audio outputs 349 * @param audio_output_buffer an array of audio output buffers 350 * @param midi_output number of MIDI outputs 351 * @param midi_output_buffer an array of MIDI output buffers 352 * @param frames the number of frames to send 353 * 354 * @return zero on success, non-zero on error 355 */ 356 int jack_net_master_send_slice(jack_net_master_t* net, int audio_output, float** audio_output_buffer, int midi_output, void** midi_output_buffer, int frames); 357 358 // Experimental Adapter API 359 360 /** 361 * jack_adapter_t is an opaque type, you may only access it using the API provided. 362 */ 363 typedef struct _jack_adapter jack_adapter_t; 364 365 /** 366 * Create an adapter. 367 * 368 * @param input number of audio inputs 369 * @param output of audio outputs 370 * @param host_buffer_size the host buffer size in frames 371 * @param host_sample_rate the host buffer sample rate 372 * @param adapted_buffer_size the adapted buffer size in frames 373 * @param adapted_sample_rate the adapted buffer sample rate 374 * 375 * @return 0 on success, otherwise a non-zero error code 376 */ 377 jack_adapter_t* jack_create_adapter(int input, int output, 378 jack_nframes_t host_buffer_size, 379 jack_nframes_t host_sample_rate, 380 jack_nframes_t adapted_buffer_size, 381 jack_nframes_t adapted_sample_rate); 382 383 /** 384 * Destroy an adapter. 385 * 386 * @param adapter the adapter to be destroyed 387 * 388 * @return 0 on success, otherwise a non-zero error code 389 */ 390 int jack_destroy_adapter(jack_adapter_t* adapter); 391 392 /** 393 * Flush internal state of an adapter. 394 * 395 * @param adapter the adapter to be flushed 396 * 397 * @return 0 on success, otherwise a non-zero error code 398 */ 399 void jack_flush_adapter(jack_adapter_t* adapter); 400 401 /** 402 * Push input to and pull output from adapter ringbuffer. 403 * 404 * @param adapter the adapter 405 * @param input an array of audio input buffers 406 * @param output an array of audio output buffers 407 * @param frames number of frames 408 * 409 * @return 0 on success, otherwise a non-zero error code 410 */ 411 int jack_adapter_push_and_pull(jack_adapter_t* adapter, float** input, float** output, unsigned int frames); 412 413 /** 414 * Pull input from and push output to adapter ringbuffer. 415 * 416 * @param adapter the adapter 417 * @param input an array of audio input buffers 418 * @param output an array of audio output buffers 419 * @param frames number of frames 420 * 421 * @return 0 on success, otherwise a non-zero error code 422 */ 423 int jack_adapter_pull_and_push(jack_adapter_t* adapter, float** input, float** output, unsigned int frames); 424 425 #ifdef __cplusplus 426 } 427 #endif 428 429 #endif /* __net_h__ */ 430