diff --git a/configure.ac b/configure.ac index 86faa7b..42f9f82 100644 --- a/configure.ac +++ b/configure.ac @@ -62,7 +62,7 @@ dnl changes are made dnl --- JACK_MAJOR_VERSION=0 JACK_MINOR_VERSION=120 -JACK_MICRO_VERSION=1 +JACK_MICRO_VERSION=2 dnl --- dnl HOWTO: updating the jack protocol version diff --git a/jack/session.h b/jack/session.h index c7feffc..ae4f1ec 100644 --- a/jack/session.h +++ b/jack/session.h @@ -14,9 +14,8 @@ 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,79 +35,112 @@ 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, + /** - * client needs to be run in a terminal. + * Client needs to be run in a terminal. */ 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. * - * 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. * - * memory will be freed along with jack_session_event_free() - * 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. will be set to zero for now. + * Future flags. Set to zero for now. */ uint32_t future; }; @@ -119,17 +151,16 @@ 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(). * - * 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. + * 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 is also required to call jack_session_reply for this event. - * there is no timeout yet. and the only way to get back to a sane state - * would be to kill this client. + * 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 session_callback when a session event @@ -141,21 +172,21 @@ typedef void (*JackSessionCallback)(jack_session_event_t *event, void *arg); * * @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; /** @@ -163,7 +194,6 @@ 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; @@ -175,77 +205,76 @@ void jack_session_event_free (jack_session_event_t *event) JACK_WEAK_EXPORT; 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; +jack_reserve_client_name (jack_client_t *client, + const char *name, + const char *uuid) JACK_WEAK_EXPORT; /** - * find out whether a client has setup a session callback. + * 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. + * -1 on error. */ int jack_client_has_session_callback (jack_client_t *client, const char *client_name) JACK_WEAK_EXPORT;