diff --git a/ChangeLog b/ChangeLog index 309b5337..121cb9ed 100644 --- a/ChangeLog +++ b/ChangeLog @@ -38,6 +38,7 @@ Valerio Pilo * Revert r4119 (RT notification in the server). JackAudioDriver::ProcessSync now skip backend write in case of graph process failure. * Fix incorrect error codes in alsa/usx2y.c and alsa/JackAlsaDriver.cpp. + * Synchronize public headers with JACK1. Update OSX project. 2011-02-09 Stephane Letz diff --git a/common/jack/midiport.h b/common/jack/midiport.h index e7e079a8..72780740 100644 --- a/common/jack/midiport.h +++ b/common/jack/midiport.h @@ -1,18 +1,18 @@ /* Copyright (C) 2004 Ian Esten - + 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. - + 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. - + You should have received a copy of the GNU Lesser General Public License - along with this program; if not, write to the Free Software + along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ @@ -24,11 +24,12 @@ #ifdef __cplusplus extern "C" { #endif - + +#include #include #include -#include - + + /** Type for raw event data contained in @ref jack_midi_event_t. */ typedef unsigned char jack_midi_data_t; @@ -43,7 +44,7 @@ typedef struct _jack_midi_event /** - * @defgroup MIDIAPI Reading and writing MIDI data + * @defgroup MIDIAPI Reading and writing MIDI data * @{ */ @@ -57,7 +58,7 @@ jack_midi_get_event_count(void* port_buffer) JACK_OPTIONAL_WEAK_EXPORT; /** Get a MIDI event from an event port buffer. - * + * * Jack MIDI is normalised, the MIDI event returned by this function is * guaranteed to be a complete MIDI event (the status byte will always be * present, and no realtime events will interspered with the event). @@ -74,7 +75,7 @@ jack_midi_event_get(jack_midi_event_t *event, /** Clear an event buffer. - * + * * This should be called at the beginning of each process cycle before calling * @ref jack_midi_event_reserve or @ref jack_midi_event_write. This * function may not be called on an input port's buffer. @@ -105,10 +106,10 @@ jack_midi_max_event_size(void* port_buffer) JACK_OPTIONAL_WEAK_EXPORT; * messages interspersed with other messages (realtime messages are fine * when they occur on their own, like other messages). * - * Events must be written in order, sorted by their sample offsets. - * JACK will not sort the events for you, and will refuse to store - * out-of-order events. - * + * Events must be written in order, sorted by their sample offsets. + * JACK will not sort the events for you, and will refuse to store + * out-of-order events. + * * @param port_buffer Buffer to write event to. * @param time Sample offset of event. * @param data_size Length of event's raw data in bytes. @@ -117,7 +118,7 @@ jack_midi_max_event_size(void* port_buffer) JACK_OPTIONAL_WEAK_EXPORT; */ jack_midi_data_t* jack_midi_event_reserve(void *port_buffer, - jack_nframes_t time, + jack_nframes_t time, size_t data_size) JACK_OPTIONAL_WEAK_EXPORT; @@ -125,18 +126,17 @@ jack_midi_event_reserve(void *port_buffer, * * This function is simply a wrapper for @ref jack_midi_event_reserve * which writes the event data into the space reserved in the buffer. - * The same restrictions on the MIDI data apply. - * - * Clients must not write more than - * @a data_size bytes into this buffer. Clients must write normalised - * MIDI data to the port - no running status and no (1-byte) realtime - * messages interspersed with other messages (realtime messages are fine - * when they occur on their own, like other messages). - * - * Events must be written in order, sorted by their sample offsets. - * JACK will not sort the events for you, and will refuse to store + * + * Clients must not write more than + * @a data_size bytes into this buffer. Clients must write normalised + * MIDI data to the port - no running status and no (1-byte) realtime + * messages interspersed with other messages (realtime messages are fine + * when they occur on their own, like other messages). + * + * Events must be written in order, sorted by their sample offsets. + * JACK will not sort the events for you, and will refuse to store * out-of-order events. - * + * * @param port_buffer Buffer to write event to. * @param time Sample offset of event. * @param data Message data to be written. diff --git a/common/jack/session.h b/common/jack/session.h index f44048c0..fd0469c6 100644 --- a/common/jack/session.h +++ b/common/jack/session.h @@ -2,21 +2,20 @@ Copyright (C) 2001 Paul Davis Copyright (C) 2004 Jack O'Quin Copyright (C) 2010 Torben Hohn - + 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. - + 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. - + You should have received a copy of the GNU Lesser General Public License - along with this program; if not, write to the Free Software + along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. - */ #ifndef __jack_session_h__ @@ -36,80 +35,114 @@ extern "C" { /** - * session event types. + * Session event type. * * if a client cant save templates, i might just do a normal save. * - * the rationale, why there is no quit without save, is that a client - * might refuse to quit when it has unsaved data. - * however some other clients might have already quit. - * this results in too much confusion, so we just dont support that. - * the session manager can check, if the saved state is different from a previous - * save, and just remove the saved stuff. - * - * (an inquiry function, whether a quit is ok, followed by a quit event - * would have a race) + * There is no "quit without saving" event because a client might refuse to + * quit when it has unsaved data, but other clients may have already quit. + * This results in too much confusion, so it is unsupported. */ enum JackSessionEventType { + /** + * Save the session completely. + * + * The client may save references to data outside the provided directory, + * but it must do so by creating a link inside the provided directory and + * referring to that in any save files. The client must not refer to data + * files outside the provided directory directly in save files, because + * this makes it impossible for the session manager to create a session + * archive for distribution or archival. + */ JackSessionSave = 1, + + /** + * Save the session completly, then quit. + * + * The rules for saving are exactly the same as for JackSessionSave. + */ JackSessionSaveAndQuit = 2, + + /** + * Save a session template. + * + * A session template is a "skeleton" of the session, but without any data. + * Clients must save a session that, when restored, will create the same + * ports as a full save would have. However, the actual data contained in + * the session may not be saved (e.g. a DAW would create the necessary + * tracks, but not save the actual recorded data). + */ JackSessionSaveTemplate = 3 }; typedef enum JackSessionEventType jack_session_event_type_t; +/** + * @ref jack_session_flags_t bits + */ enum JackSessionFlags { /** - * an error occured while saving. + * An error occured while saving. */ JackSessionSaveError = 0x01, /** - * this reply indicates that a client is part of a multiclient application. - * the command reply is left empty. but the session manager should still - * consider this client part of a session. it will come up due to invocation of another - * client. + * Client needs to be run in a terminal. */ - JackSessionChildClient = 0x02 + JackSessionNeedTerminal = 0x02 }; +/** + * Session flags. + */ typedef enum JackSessionFlags jack_session_flags_t; struct _jack_session_event { /** - * the actual type of this session event. + * The type of this session event. */ jack_session_event_type_t type; /** - * session_directory with trailing separator - * this is per client. so the client can do whatever it likes in here. + * Session directory path, with trailing separator. + * + * This directory is exclusive to the client; when saving the client may + * create any files it likes in this directory. */ const char *session_dir; /** - * client_uuid which must be specified to jack_client_open on session reload. - * client can specify it in the returned commandline as an option, or just save it - * with the state file. + * Client UUID which must be passed to jack_client_open on session load. + * + * The client can specify this in the returned command line, or save it + * in a state file within the session directory. */ const char *client_uuid; /** - * the command_line is the reply of the client. - * it specifies in a platform dependent way, how the client must be restarted upon session reload. + * Reply (set by client): the command line needed to restore the client. * - * probably it should contain ${SESSION_DIR} instead of the actual session dir. - * this would basically make the session dir moveable. + * This is a platform dependent command line. It must contain + * ${SESSION_DIR} instead of the actual session directory path. More + * generally, just as in session files, clients should not include any + * paths outside the session directory here as this makes + * archival/distribution impossible. * - * ownership of the memory is handed to jack. - * initially set to NULL by jack; + * This field is set to NULL by Jack when the event is delivered to the + * client. The client must set to allocated memory that is safe to + * free(). This memory will be freed by jack_session_event_free. */ char *command_line; /** - * flags to be set by the client. normally left 0. + * Reply (set by client): Session flags. */ jack_session_flags_t flags; + + /** + * Future flags. Set to zero for now. + */ + uint32_t future; }; typedef struct _jack_session_event jack_session_event_t; @@ -118,35 +151,42 @@ typedef struct _jack_session_event jack_session_event_t; * Prototype for the client supplied function that is called * whenever a session notification is sent via jack_session_notify(). * - * The session_id must be passed to jack_client_open on session reload (this can be - * done by specifying it somehow on the returned command line). + * Ownership of the memory of @a event is passed to the application. + * It must be freed using jack_session_event_free when its not used anymore. + * + * The client must promptly call jack_session_reply for this event. * - * @param event the event_structure. - * @param arg pointer to a client supplied structure + * @param event The event structure. + * @param arg Pointer to a client supplied structure. */ -typedef void (*JackSessionCallback)(jack_session_event_t *event, void *arg); +typedef void (*JackSessionCallback)(jack_session_event_t *event, + void *arg); /** - * Tell the JACK server to call @a save_callback the session handler wants - * to save. + * Tell the JACK server to call @a session_callback when a session event + * is to be delivered. + * + * setting more than one session_callback per process is probably a design + * error. if you have a multiclient application its more sensible to create + * a jack_client with only a session callback set. * * @return 0 on success, otherwise a non-zero error code */ -int jack_set_session_callback(jack_client_t *client, - JackSessionCallback session_callback, - void *arg) JACK_WEAK_EXPORT; +int jack_set_session_callback (jack_client_t *client, + JackSessionCallback session_callback, + void *arg) JACK_WEAK_EXPORT; /** - * reply to a session_event + * Reply to a session event. * - * this can either be called directly from the callback, or later from a different thread. - * so its possible to just stick the event pointer into a pipe and execute the save code - * from the gui thread. + * This can either be called directly from the callback, or later from a + * different thread. For example, it is possible to push the event through a + * queue and execute the save code from the GUI thread. * * @return 0 on success, otherwise a non-zero error code */ - -int jack_session_reply( jack_client_t *client, jack_session_event_t *event ) JACK_WEAK_EXPORT; +int jack_session_reply (jack_client_t *client, + jack_session_event_t *event) JACK_WEAK_EXPORT; /** @@ -154,74 +194,90 @@ int jack_session_reply( jack_client_t *client, jack_session_event_t *event ) JAC * this also frees the memory used by the command_line pointer. * if its non NULL. */ +void jack_session_event_free (jack_session_event_t *event) JACK_WEAK_EXPORT; -void jack_session_event_free (jack_session_event_t *event); -/*@}*/ +/** + * get the assigned uuid for client. + * safe to call from callback and all other threads. + * memory needs to be freed. + */ +char *jack_client_get_uuid (jack_client_t *client) JACK_WEAK_EXPORT; /** - * @defgroup JackSessionManagerAPI this API is intended for a sessionmanager. - * this API could be server specific. if we dont reach consensus here, - * we can just drop it. - * i know its a bit clumsy. - * but this api isnt required to be as stable as the client api. + * @} + */ + +/** + * @defgroup JackSessionManagerAPI API for a session manager. + * * @{ */ typedef struct { - const char *uuid; - const char *client_name; - const char *command; - jack_session_flags_t flags; + const char *uuid; + const char *client_name; + const char *command; + jack_session_flags_t flags; } jack_session_command_t; /** - * send a save or quit event, to all clients listening for session - * callbacks. the returned strings of the clients are accumulated and - * returned as an array of jack_session_command_t. - * its terminated by ret[i].uuid == NULL - * target == NULL means send to all interested clients. otherwise a clientname + * Send an event to all clients listening for session callbacks. + * + * The returned strings of the clients are accumulated and returned as an array + * of jack_session_command_t. its terminated by ret[i].uuid == NULL target == + * NULL means send to all interested clients. otherwise a clientname */ - -jack_session_command_t *jack_session_notify (jack_client_t* client, - const char *target, - jack_session_event_type_t type, - const char *path ) JACK_WEAK_EXPORT; +jack_session_command_t *jack_session_notify ( + jack_client_t* client, + const char *target, + jack_session_event_type_t type, + const char *path) JACK_WEAK_EXPORT; /** - * free the memory allocated by a session command. + * Free the memory allocated by a session command. */ - void jack_session_commands_free (jack_session_command_t *cmds) JACK_WEAK_EXPORT; /** - * get the sessionid for a client name. - * the sessionmanager needs this to reassociate a client_name to the session_id. + * Get the session ID for a client name. + * The session manager needs this to reassociate a client name to the session_id. */ - -char *jack_get_uuid_for_client_name( jack_client_t *client, const char *client_name ) JACK_WEAK_EXPORT; +char *jack_get_uuid_for_client_name (jack_client_t *client, + const char *client_name) JACK_WEAK_EXPORT; /** - * get the client name for a session_id. - * in order to snapshot the graph connections, the sessionmanager needs to map + * Get the client name for a session_id. + * + * In order to snapshot the graph connections, the session manager needs to map * session_ids to client names. */ - -char *jack_get_client_name_by_uuid( jack_client_t *client, const char *client_uuid ) JACK_WEAK_EXPORT; +char *jack_get_client_name_by_uuid (jack_client_t *client, + const char *client_uuid ) JACK_WEAK_EXPORT; /** - * reserve a client name and associate it to a uuid. - * when a client later call jack_client_open() and specifies the uuid, - * jackd will assign the reserved name. - * this allows a session manager to know in advance under which client name - * its managed clients will appear. + * Reserve a client name and associate it with a UUID. + * + * When a client later calls jack_client_open() and specifies the UUID, jackd + * will assign the reserved name. This allows a session manager to know in + * advance under which client name its managed clients will appear. * * @return 0 on success, otherwise a non-zero error code */ +int +jack_reserve_client_name (jack_client_t *client, + const char *name, + const char *uuid) JACK_WEAK_EXPORT; +/** + * Find out whether a client has set up a session callback. + * + * @return 0 when the client has no session callback, 1 when it has one. + * -1 on error. + */ int -jack_reserve_client_name( jack_client_t *client, const char *name, const char *uuid ) JACK_WEAK_EXPORT; +jack_client_has_session_callback (jack_client_t *client, const char *client_name) JACK_WEAK_EXPORT; #ifdef __cplusplus } diff --git a/common/jack/systemdeps.h b/common/jack/systemdeps.h index eadecd40..ee79ad3f 100644 --- a/common/jack/systemdeps.h +++ b/common/jack/systemdeps.h @@ -36,15 +36,19 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. typedef LONGLONG int64_t; typedef ULONGLONG uint64_t; #endif - #ifndef pthread_t - typedef HANDLE pthread_t; - #endif + /** + * to make jack API independent of different thread implementations, + * we define jack_native_thread_t to HANDLE here. + */ + typedef HANDLE jack_native_thread_t; #elif __MINGW32__ /* MINGW */ #include #include - #ifndef pthread_t - typedef HANDLE pthread_t; - #endif + /** + * to make jack API independent of different thread implementations, + * we define jack_native_thread_t to HANDLE here. + */ + typedef HANDLE jack_native_thread_t; #else /* other compilers ...*/ #include #include @@ -57,6 +61,13 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. #include #include #include + + /** + * to make jack API independent of different thread implementations, + * we define jack_native_thread_t to pthread_t here. + */ + typedef pthread_t jack_native_thread_t; + #endif /* __APPLE__ || __linux__ || __sun__ || sun */ #endif diff --git a/common/jack/thread.h b/common/jack/thread.h index 5d002afa..28c8cd10 100644 --- a/common/jack/thread.h +++ b/common/jack/thread.h @@ -28,6 +28,10 @@ extern "C" #include #include +/* use 512KB stack per thread - the default is way too high to be feasible + * with mlockall() on many systems */ +#define THREAD_STACK 524288 + /** @file thread.h * * Library functions to standardize thread creation for JACK and its @@ -66,7 +70,7 @@ int jack_client_max_real_time_priority (jack_client_t*) JACK_OPTIONAL_WEAK_EXPOR * @returns 0, if successful; EPERM, if the calling process lacks * required realtime privileges; otherwise some other error number. */ -int jack_acquire_real_time_scheduling (pthread_t thread, int priority) JACK_OPTIONAL_WEAK_EXPORT; +int jack_acquire_real_time_scheduling (jack_native_thread_t thread, int priority) JACK_OPTIONAL_WEAK_EXPORT; /** * Create a thread for JACK or one of its clients. The thread is @@ -85,7 +89,7 @@ int jack_acquire_real_time_scheduling (pthread_t thread, int priority) JACK_OPTI * @returns 0, if successful; otherwise some error number. */ int jack_client_create_thread (jack_client_t* client, - pthread_t *thread, + jack_native_thread_t *thread, int priority, int realtime, /* boolean */ void *(*start_routine)(void*), @@ -98,7 +102,7 @@ int jack_client_create_thread (jack_client_t* client, * * @returns 0, if successful; otherwise an error number. */ -int jack_drop_real_time_scheduling (pthread_t thread) JACK_OPTIONAL_WEAK_EXPORT; +int jack_drop_real_time_scheduling (jack_native_thread_t thread) JACK_OPTIONAL_WEAK_EXPORT; /** * Stop the thread, waiting for the thread handler to terminate. @@ -107,7 +111,7 @@ int jack_drop_real_time_scheduling (pthread_t thread) JACK_OPTIONAL_WEAK_EXPORT; * * @returns 0, if successful; otherwise an error number. */ -int jack_client_stop_thread(jack_client_t* client, pthread_t thread) JACK_OPTIONAL_WEAK_EXPORT; +int jack_client_stop_thread(jack_client_t* client, jack_native_thread_t thread) JACK_OPTIONAL_WEAK_EXPORT; /** * Cancel the thread then waits for the thread handler to terminate. @@ -116,7 +120,7 @@ int jack_client_stop_thread(jack_client_t* client, pthread_t thread) JACK_OPTION * * @returns 0, if successful; otherwise an error number. */ - int jack_client_kill_thread(jack_client_t* client, pthread_t thread) JACK_OPTIONAL_WEAK_EXPORT; + int jack_client_kill_thread(jack_client_t* client, jack_native_thread_t thread) JACK_OPTIONAL_WEAK_EXPORT; #ifndef WIN32 diff --git a/common/jack/types.h b/common/jack/types.h index f75b83fc..a7d06983 100644 --- a/common/jack/types.h +++ b/common/jack/types.h @@ -74,6 +74,205 @@ typedef uint32_t jack_port_id_t; typedef uint32_t jack_port_type_id_t; +/** + * @ref jack_options_t bits + */ +enum JackOptions { + + /** + * Null value to use when no option bits are needed. + */ + JackNullOption = 0x00, + + /** + * Do not automatically start the JACK server when it is not + * already running. This option is always selected if + * \$JACK_NO_START_SERVER is defined in the calling process + * environment. + */ + JackNoStartServer = 0x01, + + /** + * Use the exact client name requested. Otherwise, JACK + * automatically generates a unique one, if needed. + */ + JackUseExactName = 0x02, + + /** + * Open with optional (char *) server_name parameter. + */ + JackServerName = 0x04, + + /** + * Load internal client from optional (char *) + * load_name. Otherwise use the @a client_name. + */ + JackLoadName = 0x08, + + /** + * Pass optional (char *) load_init string to the + * jack_initialize() entry point of an internal client. + */ + JackLoadInit = 0x10, + + /** + * pass a SessionID Token this allows the sessionmanager to identify the client again. + */ + JackSessionID = 0x20 +}; + +/** Valid options for opening an external client. */ +#define JackOpenOptions (JackSessionID|JackServerName|JackNoStartServer|JackUseExactName) + +/** Valid options for loading an internal client. */ +#define JackLoadOptions (JackLoadInit|JackLoadName|JackUseExactName) + +/** + * Options for several JACK operations, formed by OR-ing together the + * relevant @ref JackOptions bits. + */ +typedef enum JackOptions jack_options_t; + +/** + * @ref jack_status_t bits + */ +enum JackStatus { + + /** + * Overall operation failed. + */ + JackFailure = 0x01, + + /** + * The operation contained an invalid or unsupported option. + */ + JackInvalidOption = 0x02, + + /** + * The desired client name was not unique. With the @ref + * JackUseExactName option this situation is fatal. Otherwise, + * the name was modified by appending a dash and a two-digit + * number in the range "-01" to "-99". The + * jack_get_client_name() function will return the exact string + * that was used. If the specified @a client_name plus these + * extra characters would be too long, the open fails instead. + */ + JackNameNotUnique = 0x04, + + /** + * The JACK server was started as a result of this operation. + * Otherwise, it was running already. In either case the caller + * is now connected to jackd, so there is no race condition. + * When the server shuts down, the client will find out. + */ + JackServerStarted = 0x08, + + /** + * Unable to connect to the JACK server. + */ + JackServerFailed = 0x10, + + /** + * Communication error with the JACK server. + */ + JackServerError = 0x20, + + /** + * Requested client does not exist. + */ + JackNoSuchClient = 0x40, + + /** + * Unable to load internal client + */ + JackLoadFailure = 0x80, + + /** + * Unable to initialize client + */ + JackInitFailure = 0x100, + + /** + * Unable to access shared memory + */ + JackShmFailure = 0x200, + + /** + * Client's protocol version does not match + */ + JackVersionError = 0x400, + + /** + * Backend error + */ + JackBackendError = 0x800, + + /** + * Client zombified failure + */ + JackClientZombie = 0x1000 +}; + +/** + * Status word returned from several JACK operations, formed by + * OR-ing together the relevant @ref JackStatus bits. + */ +typedef enum JackStatus jack_status_t; + +/** + * @ref jack_latency_callback_mode_t + */ +enum JackLatencyCallbackMode { + + /** + * Latency Callback for Capture Latency. + * Input Ports have their latency value setup. + * In the Callback the client needs to set the latency of the output ports + */ + JackCaptureLatency, + + /** + * Latency Callback for Playback Latency. + * Output Ports have their latency value setup. + * In the Callback the client needs to set the latency of the input ports + */ + JackPlaybackLatency + +}; + +/** + * Type of Latency Callback (Capture or Playback) + */ +typedef enum JackLatencyCallbackMode jack_latency_callback_mode_t; + +/** + * Prototype for the client supplied function that is called + * by the engine when port latencies need to be recalculated + * + * @param mode playback or capture latency + * @param arg pointer to a client supplied data + * + * @return zero on success, non-zero on error + */ +typedef void (*JackLatencyCallback)(jack_latency_callback_mode_t mode, void *arg); + +/** + * the new latency API operates on Ranges. + */ +struct _jack_latency_range +{ + /** + * minimum latency + */ + jack_nframes_t min; + /** + * maximum latency + */ + jack_nframes_t max; +}; + +typedef struct _jack_latency_range jack_latency_range_t; + /** * Prototype for the client supplied function that is called * by the engine anytime there is work to be done. @@ -164,9 +363,12 @@ typedef int (*JackSampleRateCallback)(jack_nframes_t nframes, void *arg); * Prototype for the client supplied function that is called * whenever a port is registered or unregistered. * - * @param arg pointer to a client supplied structure + * @param port the ID of the port + * @param arg pointer to a client supplied data + * @param register non-zero if the port is being registered, + * zero if the port is being unregistered */ -typedef void (*JackPortRegistrationCallback)(jack_port_id_t port, int, void *arg); +typedef void (*JackPortRegistrationCallback)(jack_port_id_t port, int register, void *arg); /** * Prototype for the client supplied function that is called @@ -177,7 +379,7 @@ typedef void (*JackPortRegistrationCallback)(jack_port_id_t port, int, void *arg * zero if the client is being unregistered * @param arg pointer to a client supplied structure */ -typedef void (*JackClientRegistrationCallback)(const char* name, int val, void *arg); +typedef void (*JackClientRegistrationCallback)(const char* name, int register, void *arg); /** * Prototype for the client supplied function that is called @@ -225,6 +427,21 @@ typedef void (*JackFreewheelCallback)(int starting, void *arg); */ typedef void (*JackShutdownCallback)(void *arg); +/** + * Prototype for the client supplied function that is called + * whenever jackd is shutdown. Note that after server shutdown, + * the client pointer is *not* deallocated by libjack, + * the application is responsible to properly use jack_client_close() + * to release client ressources. Warning: jack_client_close() cannot be + * safely used inside the shutdown callback and has to be called outside of + * the callback context. + + * @param code a status word, formed by OR-ing together the relevant @ref JackStatus bits. + * @param reason a string describing the shutdown reason (backend failure, server crash... etc...) + * @param arg pointer to a client supplied structure + */ +typedef void (*JackInfoShutdownCallback)(jack_status_t code, const char* reason, void *arg); + /** * Used for the type argument of jack_port_register() for default * audio ports and midi ports. @@ -298,151 +515,6 @@ enum JackPortFlags { }; -/** - * @ref jack_options_t bits - */ -enum JackOptions { - - /** - * Null value to use when no option bits are needed. - */ - JackNullOption = 0x00, - - /** - * Do not automatically start the JACK server when it is not - * already running. This option is always selected if - * \$JACK_NO_START_SERVER is defined in the calling process - * environment. - */ - JackNoStartServer = 0x01, - - /** - * Use the exact client name requested. Otherwise, JACK - * automatically generates a unique one, if needed. - */ - JackUseExactName = 0x02, - - /** - * Open with optional (char *) server_name parameter. - */ - JackServerName = 0x04, - - /** - * Load internal client from optional (char *) - * load_name. Otherwise use the @a client_name. - */ - JackLoadName = 0x08, - - /** - * Pass optional (char *) load_init string to the - * jack_initialize() entry point of an internal client. - */ - JackLoadInit = 0x10, - - /** - * pass a SessionID Token this allows the sessionmanager to identify the client again. - */ - JackSessionID = 0x20 -}; - -/** Valid options for opening an external client. */ -#define JackOpenOptions (JackSessionID|JackServerName|JackNoStartServer|JackUseExactName) - -/** Valid options for loading an internal client. */ -#define JackLoadOptions (JackLoadInit|JackLoadName|JackUseExactName) - -/** - * Options for several JACK operations, formed by OR-ing together the - * relevant @ref JackOptions bits. - */ -typedef enum JackOptions jack_options_t; - -/** - * @ref jack_status_t bits - */ -enum JackStatus { - - /** - * Overall operation failed. - */ - JackFailure = 0x01, - - /** - * The operation contained an invalid or unsupported option. - */ - JackInvalidOption = 0x02, - - /** - * The desired client name was not unique. With the @ref - * JackUseExactName option this situation is fatal. Otherwise, - * the name was modified by appending a dash and a two-digit - * number in the range "-01" to "-99". The - * jack_get_client_name() function will return the exact string - * that was used. If the specified @a client_name plus these - * extra characters would be too long, the open fails instead. - */ - JackNameNotUnique = 0x04, - - /** - * The JACK server was started as a result of this operation. - * Otherwise, it was running already. In either case the caller - * is now connected to jackd, so there is no race condition. - * When the server shuts down, the client will find out. - */ - JackServerStarted = 0x08, - - /** - * Unable to connect to the JACK server. - */ - JackServerFailed = 0x10, - - /** - * Communication error with the JACK server. - */ - JackServerError = 0x20, - - /** - * Requested client does not exist. - */ - JackNoSuchClient = 0x40, - - /** - * Unable to load internal client - */ - JackLoadFailure = 0x80, - - /** - * Unable to initialize client - */ - JackInitFailure = 0x100, - - /** - * Unable to access shared memory - */ - JackShmFailure = 0x200, - - /** - * Client's protocol version does not match - */ - JackVersionError = 0x400, - - /** - * Backend error - */ - JackBackendError = 0x800, - - /** - * Client zombified failure - */ - JackClientZombie = 0x1000 -}; - -/** - * Status word returned from several JACK operations, formed by - * OR-ing together the relevant @ref JackStatus bits. - */ -typedef enum JackStatus jack_status_t; - /** * Transport states. */ @@ -659,19 +731,5 @@ typedef struct { } jack_transport_info_t; -/** - * Prototype for the client supplied function that is called - * whenever jackd is shutdown. Note that after server shutdown, - * the client pointer is *not* deallocated by libjack, - * the application is responsible to properly use jack_client_close() - * to release client ressources. Warning: jack_client_close() cannot be - * safely used inside the shutdown callback and has to be called outside of - * the callback context. - - * @param code a status word, formed by OR-ing together the relevant @ref JackStatus bits. - * @param reason a string describing the shutdown reason (backend failure, server crash... etc...) - * @param arg pointer to a client supplied structure - */ -typedef void (*JackInfoShutdownCallback)(jack_status_t code, const char* reason, void *arg); #endif /* __jack_types_h__ */ diff --git a/common/jack/weakjack.h b/common/jack/weakjack.h index 11d2acaa..83f05ab2 100644 --- a/common/jack/weakjack.h +++ b/common/jack/weakjack.h @@ -1,18 +1,18 @@ /* Copyright (C) 2010 Paul Davis - + 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. - + 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. - + You should have received a copy of the GNU Lesser General Public License - along with this program; if not, write to the Free Software + along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ @@ -20,10 +20,63 @@ #ifndef __weakjack_h__ #define __weakjack_h__ +/** + * @defgroup WeakLinkage managing support for newer/older versions of JACK + * @{ One challenge faced by developers is that of taking advantage of new features introduced in new versions of [ JACK ] while still + * supporting older versions of the system. Normally, if an application uses a new feature in a library/API, it is unable to run on + * earlier versions of the library/API that do not support that feature. Such applications would either fail to launch or crash when + * an attempt to use the feature was made. This problem cane be solved using weakly-linked symbols. + * + * When a symbol in a framework is defined as weakly linked, the symbol does not have to be present at runtime for a process to + * continue running. The static linker identifies a weakly linked symbol as such in any code module that references the symbol. The + * dynamic linker uses this same information at runtime to determine whether a process can continue running. If a weakly linked symbol + * is not present in the framework, the code module can continue to run as long as it does not reference the symbol. However, if the + * symbol is present, the code can use it normally. + * + * (adapted from: http://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html) + * + * A concrete example will help. Suppose that someone uses a version + * of a JACK client we'll call "Jill". Jill was linked against a version + * of JACK that contains a newer part of the API (say, jack_set_latency_callback()) + * and would like to use it if it is available. + * + * When Jill is run on a system that has a suitably "new" version of + * JACK, this function will be available entirely normally. But if Jill + * is run on a system with an old version of JACK, the function isn't + * available. + * + * With normal symbol linkage, this would create a startup error whenever + * someone tries to run Jill with the "old" version of JACK. However, functions + * added to JACK after version 0.116.2 are all declared to have "weak" linkage + * which means that their abscence doesn't cause an error during program + * startup. Instead, Jill can test whether or not the symbol jack_set_latency_callback + * is null or not. If its null, it means that the JACK installed on this machine + * is too old to support this function. If its not null, then Jill can use it + * just like any other function in the API. For example: + * + * \code + * if (jack_set_latency_callback) { + * jack_set_latency_callback (jill_client, jill_latency_callback, arg); + * } + * \endcode + * + * However, there are clients that may want to use this approach to parts of the + * the JACK API that predate 0.116.2. For example, they might want to see if even + * really old basic parts of the API like jack_client_open() exist at runtime. + * + * Such clients should include before any other JACK header. + * This will make the \b entire JACK API be subject to weak linkage, so that any + * and all functions can be checked for existence at runtime. It is important + * to understand that very few clients need to do this - if you use this + * feature you should have a clear reason to do so. + * + * + */ + #ifndef JACK_OPTIONAL_WEAK_EXPORT /* JACK_OPTIONAL_WEAK_EXPORT needs to be a macro which - expands into a compiler directive. If non-null, the directive - must tell the compiler to arrange for weak linkage of + expands into a compiler directive. If non-null, the directive + must tell the compiler to arrange for weak linkage of the symbol it used with. For this to work fully may require linker arguments for the client as well. */ @@ -49,4 +102,6 @@ #endif #endif +/*@}*/ + #endif /* weakjack */ diff --git a/common/jack/weakmacros.h b/common/jack/weakmacros.h index b3207f6a..a65d1544 100644 --- a/common/jack/weakmacros.h +++ b/common/jack/weakmacros.h @@ -1,18 +1,18 @@ /* Copyright (C) 2010 Paul Davis - + 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. - + 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. - + You should have received a copy of the GNU Lesser General Public License - along with this program; if not, write to the Free Software + along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ @@ -23,27 +23,26 @@ /************************************************************* * NOTE: JACK_WEAK_EXPORT ***MUST*** be used on every function * added to the JACK API after the 0.116.2 release. - * - * Functions that predate this release are marked with + * + * Functions that predate this release are marked with * JACK_WEAK_OPTIONAL_EXPORT which can be defined at compile * time in a variety of ways. The default definition is empty, * so that these symbols get normal linkage. If you wish to - * use all JACK symbols with weak linkage, include + * use all JACK symbols with weak linkage, include * before jack.h. *************************************************************/ #ifndef JACK_WEAK_EXPORT #ifdef __GNUC__ /* JACK_WEAK_EXPORT needs to be a macro which - expands into a compiler directive. If non-null, the directive - must tell the compiler to arrange for weak linkage of + expands into a compiler directive. If non-null, the directive + must tell the compiler to arrange for weak linkage of the symbol it used with. For this to work full may require linker arguments in the client as well. */ #define JACK_WEAK_EXPORT __attribute__((weak)) #else -/* Add other things here for non-gcc platforms */ -#define JACK_WEAK_EXPORT +/* Add other things here for non-gcc platforms */ #endif #endif @@ -54,9 +53,8 @@ #ifndef JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT #ifdef __GNUC__ #define JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT __attribute__((__deprecated__)) -#else -/* Add other things here for non-gcc platforms */ -#define JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT +#else +/* Add other things here for non-gcc platforms */ #endif /* __GNUC__ */ #endif diff --git a/macosx/Jackdmp.xcodeproj/project.pbxproj b/macosx/Jackdmp.xcodeproj/project.pbxproj index 9746b522..d6d1fe02 100644 --- a/macosx/Jackdmp.xcodeproj/project.pbxproj +++ b/macosx/Jackdmp.xcodeproj/project.pbxproj @@ -7768,6 +7768,7 @@ GCC_OPTIMIZATION_LEVEL = 0; GCC_PREPROCESSOR_DEFINITIONS = ""; HEADER_SEARCH_PATHS = ( + /opt/local/include, ., ../posix, ../common/jack, @@ -7817,6 +7818,7 @@ GCC_MODEL_TUNING = G4; GCC_PREPROCESSOR_DEFINITIONS = ""; HEADER_SEARCH_PATHS = ( + /opt/local/include, ., ../posix, ../common/jack, @@ -12814,6 +12816,7 @@ GCC_OPTIMIZATION_LEVEL = 0; GCC_PREPROCESSOR_DEFINITIONS = ""; HEADER_SEARCH_PATHS = ( + /opt/local/include, ., ../posix, ../common/jack, @@ -12863,6 +12866,7 @@ GCC_MODEL_TUNING = G4; GCC_PREPROCESSOR_DEFINITIONS = ""; HEADER_SEARCH_PATHS = ( + /opt/local/include, ., ../posix, ../common, @@ -16397,6 +16401,7 @@ GCC_OPTIMIZATION_LEVEL = 0; GCC_PREPROCESSOR_DEFINITIONS = ""; HEADER_SEARCH_PATHS = ( + /opt/local/include, ., ../posix, ../common/jack, @@ -16445,6 +16450,7 @@ GCC_MODEL_TUNING = G4; GCC_PREPROCESSOR_DEFINITIONS = ""; HEADER_SEARCH_PATHS = ( + /opt/local/include, ., ../posix, ../common/jack, @@ -16544,6 +16550,7 @@ GCC_OPTIMIZATION_LEVEL = 0; GCC_PREPROCESSOR_DEFINITIONS = ""; HEADER_SEARCH_PATHS = ( + /opt/local/include, ., ../posix, ../common/jack, @@ -16592,6 +16599,7 @@ GCC_MODEL_TUNING = G4; GCC_PREPROCESSOR_DEFINITIONS = ""; HEADER_SEARCH_PATHS = ( + /opt/local/include, ., ../posix, ../common,