net.h 12.9 KB
Newer Older
1
/*
sletz's avatar
sletz committed
2
  Copyright (C) 2009-2010 Grame
sletz's avatar
sletz committed
3

4
5
6
7
  This program 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.
sletz's avatar
sletz committed
8

9
10
11
12
  This program 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.
sletz's avatar
sletz committed
13

14
  You should have received a copy of the GNU Lesser General Public License
sletz's avatar
sletz committed
15
  along with this program; if not, write to the Free Software
16
17
18
19
20
21
22
23
24
25
26
27
28
29
  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

*/

#ifndef __net_h__
#define __net_h__

#ifdef __cplusplus
extern "C"
{
#endif

#include <jack/systemdeps.h>
#include <jack/types.h>
30
#include <jack/weakmacros.h>
31

32
33
34
35
#define DEFAULT_MULTICAST_IP    "225.3.19.154"
#define DEFAULT_PORT            19000
#define DEFAULT_MTU             1500
#define MASTER_NAME_SIZE        256
36

Stephane Letz's avatar
Stephane Letz committed
37
38
#define NO_ERROR             0
#define SOCKET_ERROR        -1
39
40
#define SYNC_PACKET_ERROR   -2
#define DATA_PACKET_ERROR   -3
41

42
43
#define RESTART_CB_API 1

44
45
enum JackNetEncoder {

46
47
48
    JackFloatEncoder = 0,   // samples are transmitted as float
    JackIntEncoder = 1,     // samples are transmitted as 16 bits integer
    JackCeltEncoder = 2,    // samples are transmitted using CELT codec (http://www.celt-codec.org/)
Robin Gareus's avatar
Robin Gareus committed
49
    JackOpusEncoder = 3,    // samples are transmitted using OPUS codec (http://www.opus-codec.org/)
50
};
sletz's avatar
sletz committed
51

52
typedef struct {
sletz's avatar
sletz committed
53

sletz's avatar
sletz committed
54
55
56
57
    int audio_input;    // from master or to slave (-1 to take master audio physical inputs)
    int audio_output;   // to master or from slave (-1 to take master audio physical outputs)
    int midi_input;     // from master or to slave (-1 to take master MIDI physical inputs)
    int midi_output;    // to master or from slave (-1 to take master MIDI physical outputs)
sletz's avatar
sletz committed
58
    int mtu;            // network Maximum Transmission Unit
59
    int time_out;       // in second, -1 means infinite
60
    int encoder;        // encoder type (one of JackNetEncoder)
61
    int kbps;           // KB per second for CELT encoder
62
    int latency;        // network latency
63
64
65
66

} jack_slave_t;

typedef struct {
sletz's avatar
sletz committed
67

sletz's avatar
sletz committed
68
69
70
71
    int audio_input;                    // master audio physical outputs (-1 to take slave wanted audio inputs)
    int audio_output;                   // master audio physical inputs (-1 to take slave wanted audio outputs)
    int midi_input;                     // master MIDI physical outputs (-1 to take slave wanted MIDI inputs)
    int midi_output;                    // master MIDI physical inputs (-1 to take slave wanted MIDI outputs)
72
73
    jack_nframes_t buffer_size;         // master buffer size
    jack_nframes_t sample_rate;         // master sample rate
74
    char master_name[MASTER_NAME_SIZE]; // master machine name
75
    int time_out;                       // in second, -1 means infinite
76
77
78
79

} jack_master_t;

/**
sletz's avatar
sletz committed
80
 *  jack_net_slave_t is an opaque type. You may only access it using the
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 *  API provided.
 */
typedef struct _jack_net_slave jack_net_slave_t;

 /**
 * Open a network connection with the master machine.
 * @param ip the multicast address of the master
 * @param port the connection port
 * @param request a connection request structure
 * @param result a connection result structure
 *
 * @return Opaque net handle if successful or NULL in case of error.
 */
jack_net_slave_t* jack_net_slave_open(const char* ip, int port, const char* name, jack_slave_t* request, jack_master_t* result);

/**
 * Close the network connection with the master machine.
 * @param net the network connection to be closed
 *
 * @return 0 on success, otherwise a non-zero error code
 */
int jack_net_slave_close(jack_net_slave_t* net);

/**
 * Prototype for Process callback.
 * @param nframes buffer size
sletz's avatar
sletz committed
107
 * @param audio_input number of audio inputs
sletz's avatar
sletz committed
108
 * @param audio_input_buffer an array of audio input buffers (from master)
109
 * @param midi_input number of MIDI inputs
sletz's avatar
sletz committed
110
 * @param midi_input_buffer an array of MIDI input buffers (from master)
111
 * @param audio_output number of audio outputs
sletz's avatar
sletz committed
112
 * @param audio_output_buffer an array of audio output buffers (to master)
113
 * @param midi_output number of MIDI outputs
sletz's avatar
sletz committed
114
 * @param midi_output_buffer an array of MIDI output buffers (to master)
115
 * @param arg pointer to a client supplied structure supplied by jack_set_net_process_callback()
116
117
118
119
 *
 * @return zero on success, non-zero on error
 */
typedef int (* JackNetSlaveProcessCallback) (jack_nframes_t buffer_size,
sletz's avatar
sletz committed
120
121
                                            int audio_input,
                                            float** audio_input_buffer,
122
123
124
                                            int midi_input,
                                            void** midi_input_buffer,
                                            int audio_output,
sletz's avatar
sletz committed
125
126
127
                                            float** audio_output_buffer,
                                            int midi_output,
                                            void** midi_output_buffer,
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
                                            void* data);

/**
 * Set network process callback.
 * @param net the network connection
 * @param net_callback the process callback
 * @param arg pointer to a client supplied structure
 *
 * @return 0 on success, otherwise a non-zero error code
 */
int jack_set_net_slave_process_callback(jack_net_slave_t * net, JackNetSlaveProcessCallback net_callback, void *arg);

/**
 * Start processing thread, the net_callback will start to be called.
 * @param net the network connection
 *
 * @return 0 on success, otherwise a non-zero error code
 */
int jack_net_slave_activate(jack_net_slave_t* net);

/**
 * Stop processing thread.
 * @param net the network connection
 *
 * @return 0 on success, otherwise a non-zero error code
 */
int jack_net_slave_deactivate(jack_net_slave_t* net);

156
157
158
159
160
161
162
163
/**
 * Test if slave is still active.
 * @param net the network connection
 *
 * @return a boolean 
 */
int jack_net_slave_is_active(jack_net_slave_t* net);

164
165
166
/**
 * Prototype for BufferSize callback.
 * @param nframes buffer size
167
 * @param arg pointer to a client supplied structure supplied by jack_set_net_buffer_size_callback()
168
169
170
171
172
173
 *
 * @return zero on success, non-zero on error
 */
typedef int (*JackNetSlaveBufferSizeCallback)(jack_nframes_t nframes, void *arg);

/**
sletz's avatar
sletz committed
174
 * Prototype for SampleRate callback.
175
 * @param nframes sample rate
176
 * @param arg pointer to a client supplied structure supplied by jack_set_net_sample_rate_callback()
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
 *
 * @return zero on success, non-zero on error
 */
typedef int (*JackNetSlaveSampleRateCallback)(jack_nframes_t nframes, void *arg);

/**
 * Set network buffer size callback.
 * @param net the network connection
 * @param bufsize_callback the buffer size callback
 * @param arg pointer to a client supplied structure
 *
 * @return 0 on success, otherwise a non-zero error code
 */
int jack_set_net_slave_buffer_size_callback(jack_net_slave_t *net, JackNetSlaveBufferSizeCallback bufsize_callback, void *arg);

/**
 * Set network sample rate callback.
 * @param net the network connection
 * @param samplerate_callback the sample rate callback
 * @param arg pointer to a client supplied structure
 *
 * @return 0 on success, otherwise a non-zero error code
 */
int jack_set_net_slave_sample_rate_callback(jack_net_slave_t *net, JackNetSlaveSampleRateCallback samplerate_callback, void *arg);

/**
sletz's avatar
sletz committed
203
 * Prototype for server Shutdown callback (if not set, the client will just restart, waiting for an available master again).
204
 * @param arg pointer to a client supplied structure supplied by jack_set_net_shutdown_callback()
205
206
207
208
209
210
211
212
213
214
215
 */
typedef void (*JackNetSlaveShutdownCallback)(void* data);

/**
 * Set network shutdown callback.
 * @param net the network connection
 * @param shutdown_callback the shutdown callback
 * @param arg pointer to a client supplied structure
 *
 * @return 0 on success, otherwise a non-zero error code
 */
216
217
218
219
220
int jack_set_net_slave_shutdown_callback(jack_net_slave_t *net, JackNetSlaveShutdownCallback shutdown_callback, void *arg) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;

/**
 * Prototype for server Restart callback : this is the new preferable way to be notified when the master has disappeared. 
 * 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) 
221
222
 * by returning 0. Otherwise returning a non-zero error code will definively close the connection 
 * (and jack_net_slave_is_active will later on return false).
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
 * If both Shutdown and Restart are supplied, Restart callback will be used.
 * @param arg pointer to a client supplied structure supplied by jack_set_net_restart_callback()
 *
 * @return 0 on success, otherwise a non-zero error code
 */
typedef int (*JackNetSlaveRestartCallback)(void* data);

/**
 * Set network restart callback.
 * @param net the network connection
 * @param restart_callback the shutdown callback
 * @param arg pointer to a client supplied structure
 *
 * @return 0 on success, otherwise a non-zero error code
 */
int jack_set_net_slave_restart_callback(jack_net_slave_t *net, JackNetSlaveRestartCallback restart_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT;
239
240

/**
241
 *  jack_net_master_t is an opaque type, you may only access it using the API provided.
242
243
 */
typedef struct _jack_net_master jack_net_master_t;
sletz's avatar
sletz committed
244

245
246
247
248
249
250
251
252
253
254
255
256
 /**
 * Open a network connection with the slave machine.
 * @param ip the multicast address of the master
 * @param port the connection port
 * @param request a connection request structure
 * @param result a connection result structure
 *
 * @return Opaque net handle if successful or NULL in case of error.
 */
jack_net_master_t* jack_net_master_open(const char* ip, int port, const char* name, jack_master_t* request, jack_slave_t* result);

/**
sletz's avatar
sletz committed
257
 * Close the network connection with the slave machine.
258
259
260
261
262
 * @param net the network connection to be closed
 *
 * @return 0 on success, otherwise a non-zero error code
 */
int jack_net_master_close(jack_net_master_t* net);
sletz's avatar
sletz committed
263

264
/**
sletz's avatar
sletz committed
265
 * Receive sync and data from the network.
266
267
268
269
270
271
272
 * @param net the network connection
 * @param audio_input number of audio inputs
 * @param audio_input_buffer an array of audio input buffers
 * @param midi_input number of MIDI inputs
 * @param midi_input_buffer an array of MIDI input buffers
 *
 * @return zero on success, non-zero on error
sletz's avatar
sletz committed
273
 */
274
275
276
int jack_net_master_recv(jack_net_master_t* net, int audio_input, float** audio_input_buffer, int midi_input, void** midi_input_buffer);

/**
277
 * Send sync and data to the network.
278
 * @param net the network connection
sletz's avatar
sletz committed
279
 * @param audio_output number of audio outputs
280
281
282
283
284
 * @param audio_output_buffer an array of audio output buffers
 * @param midi_output number of MIDI ouputs
 * @param midi_output_buffer an array of MIDI output buffers
 *
 * @return zero on success, non-zero on error
sletz's avatar
sletz committed
285
 */
286
287
288
289
290
int jack_net_master_send(jack_net_master_t* net, int audio_output, float** audio_output_buffer, int midi_output, void** midi_output_buffer);

// Experimental Adapter API

/**
291
 *  jack_adapter_t is an opaque type, you may only access it using the API provided.
292
293
294
295
296
 */
typedef struct _jack_adapter jack_adapter_t;

/**
 * Create an adapter.
sletz's avatar
sletz committed
297
298
299
300
301
302
 * @param input number of audio inputs
 * @param output of audio outputs
 * @param host_buffer_size the host buffer size in frames
 * @param host_sample_rate the host buffer sample rate
 * @param adapted_buffer_size the adapted buffer size in frames
 * @param adapted_sample_rate the adapted buffer sample rate
303
304
 *
 * @return 0 on success, otherwise a non-zero error code
sletz's avatar
sletz committed
305
 */
sletz's avatar
sletz committed
306
jack_adapter_t* jack_create_adapter(int input, int output,
sletz's avatar
sletz committed
307
                                    jack_nframes_t host_buffer_size,
sletz's avatar
sletz committed
308
309
310
                                    jack_nframes_t host_sample_rate,
                                    jack_nframes_t adapted_buffer_size,
                                    jack_nframes_t adapted_sample_rate);
311
312
313

/**
 * Destroy an adapter.
sletz's avatar
sletz committed
314
 * @param adapter the adapter to be destroyed
315
316
 *
 * @return 0 on success, otherwise a non-zero error code
sletz's avatar
sletz committed
317
 */
318
319
int jack_destroy_adapter(jack_adapter_t* adapter);

sletz's avatar
sletz committed
320
321
322
323
324
/**
 * Flush internal state of an adapter.
 * @param adapter the adapter to be flushed
 *
 * @return 0 on success, otherwise a non-zero error code
sletz's avatar
sletz committed
325
 */
sletz's avatar
sletz committed
326
327
void jack_flush_adapter(jack_adapter_t* adapter);

328
/**
329
 * Push input to and pull output from adapter ringbuffer.
sletz's avatar
sletz committed
330
331
332
333
 * @param adapter the adapter
 * @param input an array of audio input buffers
 * @param output an array of audio ouput buffers
 * @param frames number of frames
334
335
 *
 * @return 0 on success, otherwise a non-zero error code
sletz's avatar
sletz committed
336
 */
sletz's avatar
sletz committed
337
int jack_adapter_push_and_pull(jack_adapter_t* adapter, float** input, float** output, unsigned int frames);
338
339

/**
340
 * Pull input to and push output from adapter ringbuffer.
sletz's avatar
sletz committed
341
342
343
344
 * @param adapter the adapter
 * @param input an array of audio input buffers
 * @param output an array of audio ouput buffers
 * @param frames number of frames
sletz's avatar
sletz committed
345
 *
346
347
 * @return 0 on success, otherwise a non-zero error code
 */
sletz's avatar
sletz committed
348
int jack_adapter_pull_and_push(jack_adapter_t* adapter, float** input, float** output, unsigned int frames);
349
350
351
352
353
354

#ifdef __cplusplus
}
#endif

#endif /* __net_h__ */