1 /* 2 Copyright (C) 2001 Paul Davis 3 Copyright (C) 2004 Jack O'Quin 4 Copyright (C) 2010 Torben Hohn 5 6 This program is free software; you can redistribute it and/or modify 7 it under the terms of the GNU Lesser General Public License as published by 8 the Free Software Foundation; either version 2.1 of the License, or 9 (at your option) any later version. 10 11 This program is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 GNU Lesser General Public License for more details. 15 16 You should have received a copy of the GNU Lesser General Public License 17 along with this program; if not, write to the Free Software 18 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 19 */ 20 21 #ifndef __jack_session_h__ 22 #define __jack_session_h__ 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 #include <jack/types.h> 29 #include <jack/weakmacros.h> 30 31 /** 32 * @defgroup SessionClientFunctions Session API for clients. 33 * 34 * @deprecated Use of JACK-Session is currently deprecated and unsupported. 35 * JACK developers recommend the use of NSM instead. 36 * See https://github.com/linuxaudio/new-session-manager 37 * @{ 38 */ 39 40 41 /** 42 * Session event type. 43 * 44 * If a client can't save templates, i might just do a normal save. 45 * 46 * There is no "quit without saving" event because a client might refuse to 47 * quit when it has unsaved data, but other clients may have already quit. 48 * This results in too much confusion, so it is unsupported. 49 */ 50 enum JackSessionEventType { 51 /** 52 * Save the session completely. 53 * 54 * The client may save references to data outside the provided directory, 55 * but it must do so by creating a link inside the provided directory and 56 * referring to that in any save files. The client must not refer to data 57 * files outside the provided directory directly in save files, because 58 * this makes it impossible for the session manager to create a session 59 * archive for distribution or archival. 60 */ 61 JackSessionSave = 1, 62 63 /** 64 * Save the session completely, then quit. 65 * 66 * The rules for saving are exactly the same as for JackSessionSave. 67 */ 68 JackSessionSaveAndQuit = 2, 69 70 /** 71 * Save a session template. 72 * 73 * A session template is a "skeleton" of the session, but without any data. 74 * Clients must save a session that, when restored, will create the same 75 * ports as a full save would have. However, the actual data contained in 76 * the session may not be saved (e.g. a DAW would create the necessary 77 * tracks, but not save the actual recorded data). 78 */ 79 JackSessionSaveTemplate = 3 80 }; 81 82 typedef enum JackSessionEventType jack_session_event_type_t; 83 84 /** 85 * @ref jack_session_flags_t bits 86 */ 87 enum JackSessionFlags { 88 /** 89 * An error occurred while saving. 90 */ 91 JackSessionSaveError = 0x01, 92 93 /** 94 * Client needs to be run in a terminal. 95 */ 96 JackSessionNeedTerminal = 0x02 97 }; 98 99 /** 100 * Session flags. 101 */ 102 typedef enum JackSessionFlags jack_session_flags_t; 103 104 struct _jack_session_event { 105 /** 106 * The type of this session event. 107 */ 108 jack_session_event_type_t type; 109 110 /** 111 * Session directory path, with trailing separator. 112 * 113 * This directory is exclusive to the client; when saving the client may 114 * create any files it likes in this directory. 115 */ 116 const char *session_dir; 117 118 /** 119 * Client UUID which must be passed to jack_client_open on session load. 120 * 121 * The client can specify this in the returned command line, or save it 122 * in a state file within the session directory. 123 */ 124 const char *client_uuid; 125 126 /** 127 * Reply (set by client): the command line needed to restore the client. 128 * 129 * This is a platform dependent command line. It must contain 130 * ${SESSION_DIR} instead of the actual session directory path. More 131 * generally, just as in session files, clients should not include any 132 * paths outside the session directory here as this makes 133 * archival/distribution impossible. 134 * 135 * This field is set to NULL by Jack when the event is delivered to the 136 * client. The client must set to allocated memory that is safe to 137 * free(). This memory will be freed by jack_session_event_free. 138 */ 139 char *command_line; 140 141 /** 142 * Reply (set by client): Session flags. 143 */ 144 jack_session_flags_t flags; 145 146 /** 147 * Future flags. Set to zero for now. 148 */ 149 uint32_t future; 150 }; 151 152 typedef struct _jack_session_event jack_session_event_t; 153 154 /** 155 * Prototype for the client supplied function that is called 156 * whenever a session notification is sent via jack_session_notify(). 157 * 158 * Ownership of the memory of @a event is passed to the application. 159 * It must be freed using jack_session_event_free when it's not used anymore. 160 * 161 * The client must promptly call jack_session_reply for this event. 162 * 163 * @deprecated Use of JACK-Session is currently deprecated and unsupported. 164 * JACK developers recommend the use of NSM instead. 165 * See https://github.com/linuxaudio/new-session-manager 166 * 167 * @param event The event structure. 168 * @param arg Pointer to a client supplied structure. 169 */ 170 typedef void (*JackSessionCallback)(jack_session_event_t *event, 171 void *arg); 172 173 /** 174 * Tell the JACK server to call @a session_callback when a session event 175 * is to be delivered. 176 * 177 * setting more than one session_callback per process is probably a design 178 * error. if you have a multiclient application its more sensible to create 179 * a jack_client with only a session callback set. 180 * 181 * @deprecated Use of JACK-Session is currently deprecated and unsupported. 182 * JACK developers recommend the use of NSM instead. 183 * See https://github.com/linuxaudio/new-session-manager 184 * 185 * @return 0 on success, otherwise a non-zero error code 186 */ 187 int jack_set_session_callback (jack_client_t *client, 188 JackSessionCallback session_callback, 189 void *arg) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 190 191 /** 192 * Reply to a session event. 193 * 194 * This can either be called directly from the callback, or later from a 195 * different thread. For example, it is possible to push the event through a 196 * queue and execute the save code from the GUI thread. 197 * 198 * @deprecated Use of JACK-Session is currently deprecated and unsupported. 199 * JACK developers recommend the use of NSM instead. 200 * See https://github.com/linuxaudio/new-session-manager 201 * 202 * @return 0 on success, otherwise a non-zero error code 203 */ 204 int jack_session_reply (jack_client_t *client, 205 jack_session_event_t *event) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 206 207 208 /** 209 * Free memory used by a jack_session_event_t. 210 * 211 * This also frees the memory used by the command_line pointer, if its non NULL. 212 * 213 * @deprecated Use of JACK-Session is currently deprecated and unsupported. 214 * JACK developers recommend the use of NSM instead. 215 * See https://github.com/linuxaudio/new-session-manager 216 */ 217 void jack_session_event_free (jack_session_event_t *event) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 218 219 220 /** 221 * Get the assigned uuid for client. 222 * Safe to call from callback and all other threads. 223 * 224 * The caller is responsible for calling jack_free(3) on any non-NULL 225 * returned value. 226 */ 227 char *jack_client_get_uuid (jack_client_t *client) JACK_WEAK_EXPORT; 228 229 /** 230 * @} 231 */ 232 233 /** 234 * @defgroup JackSessionManagerAPI API for a session manager. 235 * 236 * @{ 237 */ 238 239 typedef struct { 240 const char *uuid; 241 const char *client_name; 242 const char *command; 243 jack_session_flags_t flags; 244 } jack_session_command_t; 245 246 /** 247 * Send an event to all clients listening for session callbacks. 248 * 249 * The returned strings of the clients are accumulated and returned as an array 250 * of jack_session_command_t. its terminated by ret[i].uuid == NULL target == 251 * NULL means send to all interested clients. otherwise a clientname 252 */ 253 jack_session_command_t *jack_session_notify ( 254 jack_client_t* client, 255 const char *target, 256 jack_session_event_type_t type, 257 const char *path) JACK_WEAK_EXPORT; 258 259 /** 260 * Free the memory allocated by a session command. 261 * 262 * @deprecated Use of JACK-Session is currently deprecated and unsupported. 263 * JACK developers recommend the use of NSM instead. 264 * See https://github.com/linuxaudio/new-session-manager 265 */ 266 void jack_session_commands_free (jack_session_command_t *cmds) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 267 268 /** 269 * Reserve a client name and associate it with a UUID. 270 * 271 * When a client later calls jack_client_open() and specifies the UUID, jackd 272 * will assign the reserved name. This allows a session manager to know in 273 * advance under which client name its managed clients will appear. 274 * 275 * @return 0 on success, otherwise a non-zero error code 276 */ 277 int 278 jack_reserve_client_name (jack_client_t *client, 279 const char *name, 280 const char *uuid) JACK_WEAK_EXPORT; 281 282 /** 283 * Find out whether a client has set up a session callback. 284 * 285 * @deprecated Use of JACK-Session is currently deprecated and unsupported. 286 * JACK developers recommend the use of NSM instead. 287 * See https://github.com/linuxaudio/new-session-manager 288 * 289 * @return 0 when the client has no session callback, 1 when it has one. 290 * -1 on error. 291 */ 292 int 293 jack_client_has_session_callback (jack_client_t *client, const char *client_name) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 294 295 /** 296 * @} 297 */ 298 299 #ifdef __cplusplus 300 } 301 #endif 302 #endif 303