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 modulejack.c.session;
22 publicimportjack.c.systemdeps;
23 publicimportjack.c.types;
24 25 extern (C)
26 {
27 28 /**
29 * @defgroup SessionClientFunctions Session API for clients.
30 * @{
31 */32 33 34 /**
35 * Session event type.
36 *
37 * If a client cant save templates, i might just do a normal save.
38 *
39 * There is no "quit without saving" event because a client might refuse to
40 * quit when it has unsaved data, but other clients may have already quit.
41 * This results in too much confusion, so it is unsupported.
42 */43 enumJackSessionEventType {
44 /**
45 * Save the session completely.
46 *
47 * The client may save references to data outside the provided directory,
48 * but it must do so by creating a link inside the provided directory and
49 * referring to that in any save files. The client must not refer to data
50 * files outside the provided directory directly in save files, because
51 * this makes it impossible for the session manager to create a session
52 * archive for distribution or archival.
53 */54 JackSessionSave = 1,
55 56 /**
57 * Save the session completly, then quit.
58 *
59 * The rules for saving are exactly the same as for JackSessionSave.
60 */61 JackSessionSaveAndQuit = 2,
62 63 /**
64 * Save a session template.
65 *
66 * A session template is a "skeleton" of the session, but without any data.
67 * Clients must save a session that, when restored, will create the same
68 * ports as a full save would have. However, the actual data contained in
69 * the session may not be saved (e.g. a DAW would create the necessary
70 * tracks, but not save the actual recorded data).
71 */72 JackSessionSaveTemplate = 373 };
74 75 aliasjack_session_event_type_t = JackSessionEventType;
76 77 /**
78 * @ref jack_session_flags_t bits
79 */80 enumJackSessionFlags {
81 /**
82 * An error occured while saving.
83 */84 JackSessionSaveError = 0x01,
85 86 /**
87 * Client needs to be run in a terminal.
88 */89 JackSessionNeedTerminal = 0x0290 };
91 92 /**
93 * Session flags.
94 */95 aliasjack_session_flags_t = JackSessionFlags;
96 97 structjack_session_event_t {
98 /**
99 * The type of this session event.
100 */101 jack_session_event_type_ttype;
102 103 /**
104 * Session directory path, with trailing separator.
105 *
106 * This directory is exclusive to the client; when saving the client may
107 * create any files it likes in this directory.
108 */109 const(char) *session_dir;
110 111 /**
112 * Client UUID which must be passed to jack_client_open on session load.
113 *
114 * The client can specify this in the returned command line, or save it
115 * in a state file within the session directory.
116 */117 const(char) *client_uuid;
118 119 /**
120 * Reply (set by client): the command line needed to restore the client.
121 *
122 * This is a platform dependent command line. It must contain
123 * ${SESSION_DIR} instead of the actual session directory path. More
124 * generally, just as in session files, clients should not include any
125 * paths outside the session directory here as this makes
126 * archival/distribution impossible.
127 *
128 * This field is set to NULL by Jack when the event is delivered to the
129 * client. The client must set to allocated memory that is safe to
130 * free(). This memory will be freed by jack_session_event_free.
131 */132 char *command_line;
133 134 /**
135 * Reply (set by client): Session flags.
136 */137 jack_session_flags_tflags;
138 139 /**
140 * Future flags. Set to zero for now.
141 */142 uint32_tfuture;
143 };
144 145 /**
146 * Prototype for the client supplied function that is called
147 * whenever a session notification is sent via jack_session_notify().
148 *
149 * Ownership of the memory of @a event is passed to the application.
150 * It must be freed using jack_session_event_free when its not used anymore.
151 *
152 * The client must promptly call jack_session_reply for this event.
153 *
154 * @param event The event structure.
155 * @param arg Pointer to a client supplied structure.
156 */157 aliasJackSessionCallback = voidfunction(jack_session_event_t *event,
158 void *arg);
159 160 /**
161 * Tell the JACK server to call @a session_callback when a session event
162 * is to be delivered.
163 *
164 * setting more than one session_callback per process is probably a design
165 * error. if you have a multiclient application its more sensible to create
166 * a jack_client with only a session callback set.
167 *
168 * @return 0 on success, otherwise a non-zero error code
169 */170 intjack_set_session_callback (jack_client_t *client,
171 JackSessionCallbacksession_callback,
172 void *arg) /* JACK_WEAK_EXPORT */;
173 174 /**
175 * Reply to a session event.
176 *
177 * This can either be called directly from the callback, or later from a
178 * different thread. For example, it is possible to push the event through a
179 * queue and execute the save code from the GUI thread.
180 *
181 * @return 0 on success, otherwise a non-zero error code
182 */183 intjack_session_reply (jack_client_t *client,
184 jack_session_event_t *event) /* JACK_WEAK_EXPORT */;
185 186 187 /**
188 * Free memory used by a jack_session_event_t.
189 *
190 * This also frees the memory used by the command_line pointer, if its non NULL.
191 */192 voidjack_session_event_free (jack_session_event_t *event) /* JACK_WEAK_EXPORT */;
193 194 195 /**
196 * Get the assigned uuid for client.
197 * Safe to call from callback and all other threads.
198 *
199 * The caller is responsible for calling jack_free(3) on any non-NULL
200 * returned value.
201 */202 char *jack_client_get_uuid (jack_client_t *client) /* JACK_WEAK_EXPORT */;
203 204 /**
205 * @}
206 */207 208 /**
209 * @defgroup JackSessionManagerAPI API for a session manager.
210 *
211 * @{
212 */213 214 structjack_session_command_t {
215 const(char) *uuid;
216 const(char) *client_name;
217 const(char) *command;
218 jack_session_flags_tflags;
219 };
220 221 /**
222 * Send an event to all clients listening for session callbacks.
223 *
224 * The returned strings of the clients are accumulated and returned as an array
225 * of jack_session_command_t. its terminated by ret[i].uuid == NULL target ==
226 * NULL means send to all interested clients. otherwise a clientname
227 */228 jack_session_command_t *jack_session_notify (
229 jack_client_t* client,
230 const(char) *target,
231 jack_session_event_type_ttype,
232 const(char) *path) /* JACK_WEAK_EXPORT */;
233 234 /**
235 * Free the memory allocated by a session command.
236 */237 voidjack_session_commands_free (jack_session_command_t *cmds) /* JACK_WEAK_EXPORT */;
238 239 /**
240 * Get the session ID for a client name.
241 *
242 * The session manager needs this to reassociate a client name to the session_id.
243 *
244 * The caller is responsible for calling jack_free(3) on any non-NULL
245 * returned value.
246 */247 char *jack_get_uuid_for_client_name (jack_client_t *client,
248 const(char) *client_name) /* JACK_WEAK_EXPORT */;
249 250 /**
251 * Get the client name for a session_id.
252 *
253 * In order to snapshot the graph connections, the session manager needs to map
254 * session_ids to client names.
255 *
256 * The caller is responsible for calling jack_free(3) on any non-NULL
257 * returned value.
258 */259 char *jack_get_client_name_by_uuid (jack_client_t *client,
260 const(char) *client_uuid ) /* JACK_WEAK_EXPORT */;
261 262 /**
263 * Reserve a client name and associate it with a UUID.
264 *
265 * When a client later calls jack_client_open() and specifies the UUID, jackd
266 * will assign the reserved name. This allows a session manager to know in
267 * advance under which client name its managed clients will appear.
268 *
269 * @return 0 on success, otherwise a non-zero error code
270 */271 int272 jack_reserve_client_name (jack_client_t *client,
273 const(char) *name,
274 const(char) *uuid) /* JACK_WEAK_EXPORT */;
275 276 /**
277 * Find out whether a client has set up a session callback.
278 *
279 * @return 0 when the client has no session callback, 1 when it has one.
280 * -1 on error.
281 */282 int283 jack_client_has_session_callback (jack_client_t *client, const(char) *client_name) /* JACK_WEAK_EXPORT */;
284 285 }