Commit 779832a1 authored by sletz's avatar sletz
Browse files

Synchronize public headers with JACK1. Update OSX project.

git-svn-id: http://subversion.jackaudio.org/jack/jack2/trunk/jackmp@4144 0c269be4-1314-0410-8aa9-9f06e86f4224
parent 92c5da66
......@@ -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 <letz@grame.fr>
......
/*
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 <jack/weakmacros.h>
#include <jack/types.h>
#include <stdlib.h>
#include <jack/weakmacros.h>
/** 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.
......
......@@ -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
}
......
......@@ -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 <stdint.h>
#include <sys/types.h>
#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 <inttypes.h>
#include <pthread.h>
......@@ -57,6 +61,13 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
#include <inttypes.h>
#include <pthread.h>
#include <sys/types.h>
/**
* 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
......@@ -28,6 +28,10 @@ extern "C"
#include <jack/systemdeps.h>
#include <jack/weakmacros.h>
/* 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
......
......@@ -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 <em>(char *) server_name</em> parameter.
*/
JackServerName = 0x04,
/**
* Load internal client from optional <em>(char *)
* load_name</em>. Otherwise use the @a client_name.
*/
JackLoadName = 0x08,
/**
* Pass optional <em>(char *) load_init</em> 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 {
/**