From 63ab0f236b202b2dbdc393eac0fe25c12b8dbffd Mon Sep 17 00:00:00 2001 From: Torben Hohn Date: Thu, 25 Feb 2010 15:21:28 +0100 Subject: [PATCH] move session API to jack/session.h changed to async. also removed the cookie stuff. and other unnecessary stuff. --- jack/jack.h | 24 ------- jack/session.h | 178 +++++++++++++++++++++++++++++++++++++++++++++++++ jack/types.h | 41 ++---------- 3 files changed, 182 insertions(+), 61 deletions(-) create mode 100644 jack/session.h diff --git a/jack/jack.h b/jack/jack.h index 09cea3c..1cd425e 100644 --- a/jack/jack.h +++ b/jack/jack.h @@ -406,17 +406,6 @@ int jack_set_graph_order_callback (jack_client_t *, */ int jack_set_xrun_callback (jack_client_t *, JackXRunCallback xrun_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT; -/** - * Tell the JACK server to call @a save_callback the session handler wants - * to save. - * - * @return 0 on success, otherwise a non-zero error code - */ - -int jack_set_session_callback(jack_client_t *client, - JackSessionCallback session_save_callback, - void *arg) JACK_WEAK_EXPORT; - /*@}*/ /** @@ -1013,19 +1002,6 @@ void jack_set_info_function (void (*func)(const char *)) JACK_OPTIONAL_WEAK_EXPO */ void jack_free(void* ptr) JACK_OPTIONAL_WEAK_EXPORT; -/** - * 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[0]='\0' - * 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_t code, - const char *path ) JACK_WEAK_EXPORT; - /** * get the jack client name for a uuid */ diff --git a/jack/session.h b/jack/session.h new file mode 100644 index 0000000..a8e0a6e --- /dev/null +++ b/jack/session.h @@ -0,0 +1,178 @@ +/* + 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 + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + +*/ + +#ifndef __jack_session_h__ +#define __jack_session_h__ + +#ifdef __cplusplus +extern "C" { +#endif + +#include + +/** + * @defgroup SessionClientFunctions Session API for clients. + * @{ + */ + + +/** + * session event types. + * + * 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) + */ +enum JackSessionEventType { + JackSessionSave = 1, + JackSessionSaveAndQuit = 2, + JackSessionSaveTemplate = 3 +}; + +typedef enum JackSessionEvent jack_session_event_type_t; + +struct _jack_session_event { + /** + * the actual 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. + */ + 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. + */ + 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. + * + * probably it should contain ${SESSION_DIR} instead of the actual session dir. + * this would basically make the session dir moveable. + * + * ownership of the memory is handed to jack. + * initially set to NULL by jack; + */ + char *command_line; +}; + +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). + * + * @param event the event_structure. + * @param arg pointer to a client supplied structure + */ +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. + * + * @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; + +/** + * 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. + * + * @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; + + +/*@}*/ + + +/** + * @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. + * @{ + */ + +typedef struct { + char uuid[16]; + char client_name[33]; + char command[256]; +} 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[0]='\0' + * 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; + +/** + * get the sessionid for a client name. + * the sessionmanager 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; + +/** + * get the client name for a session_id. + * in order to snapshot the graph connections, the sessionmanager needs to map + * session_ids to client names. + */ + +char *jack_get_client_name_for_uuid( jack_client_t *client, const char *client_uuid ) JACK_WEAK_EXPORT; + +#ifdef __cplusplus +} +#endif +#endif diff --git a/jack/types.h b/jack/types.h index 90fab23..91d2523 100644 --- a/jack/types.h +++ b/jack/types.h @@ -114,15 +114,15 @@ enum JackOptions { * jack_initialize() entry point of an internal client. */ JackLoadInit = 0x10, + /** - * pass a UUID Token, this will unlock and assign an assigned name - * to the client. + * pass a SessionID Token this allows the sessionmanager to identify the client again. */ - JackSessionUUID = 0x20 + JackSessionID = 0x20 }; /** Valid options for opening an external client. */ -#define JackOpenOptions (JackSessionUUID|JackServerName|JackNoStartServer|JackUseExactName) +#define JackOpenOptions (JackSessionID|JackServerName|JackNoStartServer|JackUseExactName) /** Valid options for loading an internal client. */ #define JackLoadOptions (JackLoadInit|JackLoadName|JackUseExactName) @@ -219,13 +219,6 @@ enum JackStatus { */ typedef enum JackStatus jack_status_t; -enum JackSessionEvent { - JackSessionSave = 1, - JackSessionQuit = 2 -}; - -typedef enum JackSessionEvent jack_session_event_t; - /** * Prototype for the client supplied function that is called * by the engine anytime there is work to be done. @@ -376,27 +369,6 @@ typedef void (*JackShutdownCallback)(void *arg); */ typedef void (*JackInfoShutdownCallback)(jack_status_t code, const char* reason, void *arg); -/** - * Prototype for the client supplied function that is called - * whenever a session notification is sent via jack_session_notify(). - * For a save event the client is required to save its state. - * It must save it into session_dir, and any created files or directories - * must be contained in @a session_dir and start with @a uuid. - * The prefix also acts as uuid, which the client needs to specify - * to jack_client_open() upon session reload. - * - * The return value is a commandline, which will restore the state. - * - * The UUID must be passed to jack_client_open on session reload (this can be - * done by specifying it somehow on the returned command line). - * - * @param event type of the Event (Save or Quit) - * @param session_dir session directory, with trailing separator. - * @param uuid UUID for this client instance. - * @param arg pointer to a client supplied structure - */ -typedef char *(*JackSessionCallback)(jack_session_event_t event, const char* session_dir, const char* uuid, void *arg); - /** * Used for the type argument of jack_port_register() for default * audio and midi ports. @@ -469,10 +441,5 @@ enum JackPortFlags { JackPortIsTerminal = 0x10 }; -typedef struct { - char uuid[16]; - char client_name[33]; - char command[256]; -} jack_session_command_t; #endif /* __jack_types_h__ */