jack/types.h

   1 /*
   2     Copyright (C) 2001 Paul Davis
   3     Copyright (C) 2004 Jack O'Quin
   4
   5     This program is free software; you can redistribute it and/or modify
   6     it under the terms of the GNU Lesser General Public License as published by
   7     the Free Software Foundation; either version 2.1 of the License, or
   8     (at your option) any later version.
   9
  10     This program is distributed in the hope that it will be useful,
  11     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13     GNU Lesser General Public License for more details.
  14
  15     You should have received a copy of the GNU Lesser General Public License
  16     along with this program; if not, write to the Free Software
  17     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  18
  19 */
  20
  21 #ifndef __jack_types_h__
  22 #define __jack_types_h__
  23
  24 #include <inttypes.h>
  25
  26 typedef int32_t jack_shmsize_t;
  27
  28 /**
  29  * Type used to represent sample frame counts.
  30  */
  31 typedef uint32_t             jack_nframes_t;
  32
  33 /**
  34  * Maximum value that can be stored in jack_nframes_t
  35  */
  36 #define JACK_MAX_FRAMES (4294967295U)   /* This should be UINT32_MAX, but
  37                                            C++ has a problem with that. */
  38
  39 /**
  40  * Type used to represent the value of free running
  41  * monotonic clock with units of microseconds.
  42  */
  43 typedef uint64_t jack_time_t;
  44
  45 /**
  46  *  Maximum size of @a load_init string passed to an internal client
  47  *  jack_initialize() function via jack_internal_client_load().
  48  */
  49 #define JACK_LOAD_INIT_LIMIT 1024
  50
  51 /**
  52  *  jack_intclient_t is an opaque type representing a loaded internal
  53  *  client.  You may only access it using the API provided in @ref
  54  *  intclient.h "<jack/intclient.h>".
  55  */
  56 typedef uint64_t jack_intclient_t;
  57
  58 /**
  59  *  jack_port_t is an opaque type.  You may only access it using the
  60  *  API provided.
  61  */
  62 typedef struct _jack_port    jack_port_t;
  63
  64 /**
  65  *  jack_client_t is an opaque type.  You may only access it using the
  66  *  API provided.
  67  */
  68 typedef struct _jack_client  jack_client_t;
  69
  70 /**
  71  *  Ports have unique ids. A port registration callback is the only
  72  *  place you ever need to know their value.
  73  */
  74 typedef uint32_t             jack_port_id_t;
  75
  76
  77 /**
  78  *  @ref jack_options_t bits
  79  */
  80 enum JackOptions {
  81
  82      /**
  83       * Null value to use when no option bits are needed.
  84       */
  85      JackNullOption = 0x00,
  86
  87      /**
  88       * Do not automatically start the JACK server when it is not
  89       * already running.  This option is always selected if
  90       * \$JACK_NO_START_SERVER is defined in the calling process
  91       * environment.
  92       */
  93      JackNoStartServer = 0x01,
  94
  95      /**
  96       * Use the exact client name requested.  Otherwise, JACK
  97       * automatically generates a unique one, if needed.
  98       */
  99      JackUseExactName = 0x02,
 100
 101      /**
 102       * Open with optional <em>(char *) server_name</em> parameter.
 103       */
 104      JackServerName = 0x04,
 105
 106      /**
 107       * Load internal client from optional <em>(char *)
 108       * load_name</em>.  Otherwise use the @a client_name.
 109       */
 110      JackLoadName = 0x08,
 111
 112      /**
 113       * Pass optional <em>(char *) load_init</em> string to the
 114       * jack_initialize() entry point of an internal client.
 115       */
 116      JackLoadInit = 0x10
 117 };
 118
 119 /** Valid options for opening an external client. */
 120 #define JackOpenOptions (JackServerName|JackNoStartServer|JackUseExactName)
 121
 122 /** Valid options for loading an internal client. */
 123 #define JackLoadOptions (JackLoadInit|JackLoadName|JackUseExactName)
 124
 125 /**
 126  *  Options for several JACK operations, formed by OR-ing together the
 127  *  relevant @ref JackOptions bits.
 128  */
 129 typedef enum JackOptions jack_options_t;
 130
 131 /**
 132  *  @ref jack_status_t bits
 133  */
 134 enum JackStatus {
 135
 136      /**
 137       * Overall operation failed.
 138       */
 139      JackFailure = 0x01,
 140
 141      /**
 142       * The operation contained an invalid or unsupported option.
 143       */
 144      JackInvalidOption = 0x02,
 145
 146      /**
 147       * The desired client name was not unique.  With the @ref
 148       * JackUseExactName option this situation is fatal.  Otherwise,
 149       * the name was modified by appending a dash and a two-digit
 150       * number in the range "-01" to "-99".  The
 151       * jack_get_client_name() function will return the exact string
 152       * that was used.  If the specified @a client_name plus these
 153       * extra characters would be too long, the open fails instead.
 154       */
 155      JackNameNotUnique = 0x04,
 156
 157      /**
 158       * The JACK server was started as a result of this operation.
 159       * Otherwise, it was running already.  In either case the caller
 160       * is now connected to jackd, so there is no race condition.
 161       * When the server shuts down, the client will find out.
 162       */
 163      JackServerStarted = 0x08,
 164
 165      /**
 166       * Unable to connect to the JACK server.
 167       */
 168      JackServerFailed = 0x10,
 169
 170      /**
 171       * Communication error with the JACK server.
 172       */
 173      JackServerError = 0x20,
 174
 175      /**
 176       * Requested client does not exist.
 177       */
 178      JackNoSuchClient = 0x40,
 179
 180      /**
 181       * Unable to load internal client
 182       */
 183      JackLoadFailure = 0x80,
 184
 185      /**
 186       * Unable to initialize client
 187       */
 188      JackInitFailure = 0x100,
 189
 190      /**
 191       * Unable to access shared memory
 192       */
 193      JackShmFailure = 0x200,
 194
 195      /**
 196       * Client's protocol version does not match
 197       */
 198      JackVersionError = 0x400,
 199
 200      /*
 201       * BackendError
 202       */
 203      JackBackendError = 0x800,
 204
 205      /*
 206       * Client is being shutdown against its will
 207       */
 208      JackClientZombie = 0x1000
 209 };
 210
 211 /**
 212  *  Status word returned from several JACK operations, formed by
 213  *  OR-ing together the relevant @ref JackStatus bits.
 214  */
 215 typedef enum JackStatus jack_status_t;
 216
 217 /**
 218  * Prototype for the client supplied function that is called
 219  * by the engine anytime there is work to be done.
 220  *
 221  * @pre nframes == jack_get_buffer_size()
 222  * @pre nframes == pow(2,x)
 223  *
 224  * @param nframes number of frames to process
 225  * @param arg pointer to a client supplied data
 226  *
 227  * @return zero on success, non-zero on error
 228  */
 229 typedef int  (*JackProcessCallback)(jack_nframes_t nframes, void *arg);
 230
 231 /**
 232  * Prototype for the client supplied function that is called
 233  * once after the creation of the thread in which other
 234  * callbacks will be made. Special thread characteristics
 235  * can be set from this callback, for example. This is a
 236  * highly specialized callback and most clients will not
 237  * and should not use it.
 238  *
 239  * @param arg pointer to a client supplied structure
 240  *
 241  * @return void
 242  */
 243 typedef void  (*JackThreadInitCallback)(void *arg);
 244
 245 /**
 246  * Prototype for the client supplied function that is called
 247  * whenever the processing graph is reordered.
 248  *
 249  * @param arg pointer to a client supplied data
 250  *
 251  * @return zero on success, non-zero on error
 252  */
 253 typedef int  (*JackGraphOrderCallback)(void *arg);
 254
 255 /**
 256  * Prototype for the client-supplied function that is called whenever
 257  * an xrun has occured.
 258  *
 259  * @see jack_get_xrun_delayed_usecs()
 260  *
 261  * @param arg pointer to a client supplied data
 262  *
 263  * @return zero on success, non-zero on error
 264  */
 265 typedef int  (*JackXRunCallback)(void *arg);
 266
 267 /**
 268  * Prototype for the @a bufsize_callback that is invoked whenever the
 269  * JACK engine buffer size changes.  Although this function is called
 270  * in the JACK process thread, the normal process cycle is suspended
 271  * during its operation, causing a gap in the audio flow.  So, the @a
 272  * bufsize_callback can allocate storage, touch memory not previously
 273  * referenced, and perform other operations that are not realtime
 274  * safe.
 275  *
 276  * @param nframes buffer size
 277  * @param arg pointer supplied by jack_set_buffer_size_callback().
 278  *
 279  * @return zero on success, non-zero on error
 280  */
 281 typedef int  (*JackBufferSizeCallback)(jack_nframes_t nframes, void *arg);
 282
 283 /**
 284  * Prototype for the client supplied function that is called
 285  * when the engine sample rate changes.
 286  *
 287  * @param nframes new engine sample rate
 288  * @param arg pointer to a client supplied data
 289  *
 290  * @return zero on success, non-zero on error
 291  */
 292 typedef int  (*JackSampleRateCallback)(jack_nframes_t nframes, void *arg);
 293
 294 /**
 295  * Prototype for the client supplied function that is called
 296  * whenever a port is registered or unregistered.
 297  *
 298  * @param port the ID of the port
 299  * @param arg pointer to a client supplied data
 300  * @param register non-zero if the port is being registered,
 301  *                     zero if the port is being unregistered
 302  */
 303 typedef void (*JackPortRegistrationCallback)(jack_port_id_t port, int register, void *arg);
 304
 305 /**
 306  * Prototype for the client supplied function that is called
 307  * whenever a client is registered or unregistered.
 308  *
 309  * @param name a null-terminated string containing the client name
 310  * @param register non-zero if the client is being registered,
 311  *                     zero if the client is being unregistered
 312  * @param arg pointer to a client supplied data
 313  */
 314 typedef void (*JackClientRegistrationCallback)(const char* name, int register, void *arg);
 315
 316 /**
 317  * Prototype for the client supplied function that is called
 318  * whenever a client is registered or unregistered.
 319  *
 320  * @param a one of two ports connected or disconnected
 321  * @param b one of two ports connected or disconnected
 322  * @param connect non-zero if ports were connected
 323  *                    zero if ports were disconnected
 324  * @param arg pointer to a client supplied data
 325  */
 326 typedef void (*JackPortConnectCallback)(jack_port_id_t a, jack_port_id_t b, int connect, void* arg);
 327
 328 /**
 329  * Prototype for the client supplied function that is called
 330  * whenever jackd starts or stops freewheeling.
 331  *
 332  * @param starting non-zero if we start starting to freewheel, zero otherwise
 333  * @param arg pointer to a client supplied structure
 334  */
 335 typedef void (*JackFreewheelCallback)(int starting, void *arg);
 336
 337 typedef void *(*JackThreadCallback)(void* arg);
 338
 339 /**
 340  * Prototype for the client supplied function that is called
 341  * whenever jackd is shutdown. Note that after server shutdown,
 342  * the client pointer is *not* deallocated by libjack,
 343  * the application is responsible to properly use jack_client_close()
 344  * to release client ressources. Warning: jack_client_close() cannot be
 345  * safely used inside the shutdown callback and has to be called outside of
 346  * the callback context.
 347  *
 348  * @param arg pointer to a client supplied structure
 349  */
 350 typedef void (*JackShutdownCallback)(void *arg);
 351
 352 /**
 353  * Prototype for the client supplied function that is called
 354  * whenever jackd is shutdown. Note that after server shutdown,
 355  * the client pointer is *not* deallocated by libjack,
 356  * the application is responsible to properly use jack_client_close()
 357  * to release client ressources. Warning: jack_client_close() cannot be
 358  * safely used inside the shutdown callback and has to be called outside of
 359  * the callback context.
 360
 361  * @param code a shuntdown code
 362  * @param reason a string discribing the shuntdown reason (backend failure, server crash... etc...)
 363  * @param arg pointer to a client supplied structure
 364  */
 365 typedef void (*JackInfoShutdownCallback)(jack_status_t code, const char* reason, void *arg);
 366
 367 /**
 368  * Used for the type argument of jack_port_register() for default
 369  * audio and midi ports.
 370  */
 371 #define JACK_DEFAULT_AUDIO_TYPE "32 bit float mono audio"
 372 #define JACK_DEFAULT_MIDI_TYPE "8 bit raw midi"
 373
 374 /**
 375  * For convenience, use this typedef if you want to be able to change
 376  * between float and double. You may want to typedef sample_t to
 377  * jack_default_audio_sample_t in your application.
 378  */
 379 typedef float jack_default_audio_sample_t;
 380
 381 /**
 382  *  A port has a set of flags that are formed by AND-ing together the
 383  *  desired values from the list below. The flags "JackPortIsInput" and
 384  *  "JackPortIsOutput" are mutually exclusive and it is an error to use
 385  *  them both.
 386  */
 387 enum JackPortFlags {
 388
 389      /**
 390       * if JackPortIsInput is set, then the port can receive
 391       * data.
 392       */
 393      JackPortIsInput = 0x1,
 394
 395      /**
 396       * if JackPortIsOutput is set, then data can be read from
 397       * the port.
 398       */
 399      JackPortIsOutput = 0x2,
 400
 401      /**
 402       * if JackPortIsPhysical is set, then the port corresponds
 403       * to some kind of physical I/O connector.
 404       */
 405      JackPortIsPhysical = 0x4,
 406
 407      /**
 408       * if JackPortCanMonitor is set, then a call to
 409       * jack_port_request_monitor() makes sense.
 410       *
 411       * Precisely what this means is dependent on the client. A typical
 412       * result of it being called with TRUE as the second argument is
 413       * that data that would be available from an output port (with
 414       * JackPortIsPhysical set) is sent to a physical output connector
 415       * as well, so that it can be heard/seen/whatever.
 416       *
 417       * Clients that do not control physical interfaces
 418       * should never create ports with this bit set.
 419       */
 420      JackPortCanMonitor = 0x8,
 421
 422      /**
 423       * JackPortIsTerminal means:
 424       *
 425       * for an input port: the data received by the port
 426       *                    will not be passed on or made
 427       *                    available at any other port
 428       *
 429       * for an output port: the data available at the port
 430       *                    does not originate from any other port
 431       *
 432       * Audio synthesizers, I/O hardware interface clients, HDR
 433       * systems are examples of clients that would set this flag for
 434       * their ports.
 435       */
 436      JackPortIsTerminal = 0x10
 437 };
 438
 439
 440 #endif /* __jack_types_h__ */