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 module jack.c.session;
22 public import jack.c.systemdeps;
23 public import jack.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 enum JackSessionEventType {
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 = 3
73 };
74 
75 alias jack_session_event_type_t = JackSessionEventType;
76 
77 /**
78  * @ref jack_session_flags_t bits
79  */
80 enum JackSessionFlags {
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 = 0x02
90 };
91 
92 /**
93  * Session flags.
94  */
95 alias jack_session_flags_t = JackSessionFlags;
96 
97 struct jack_session_event_t {
98     /**
99      * The type of this session event.
100      */
101     jack_session_event_type_t type;
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_t flags;
138 
139     /**
140      * Future flags. Set to zero for now.
141      */
142     uint32_t future;
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 alias JackSessionCallback = void function(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 int jack_set_session_callback (jack_client_t       *client,
171                                JackSessionCallback  session_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 int jack_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 void jack_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 struct jack_session_command_t {
215 	const(char)          *uuid;
216 	const(char)          *client_name;
217 	const(char)          *command;
218 	jack_session_flags_t  flags;
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_t  type,
232 	const(char)               *path) /* JACK_WEAK_EXPORT */;
233 
234 /**
235  * Free the memory allocated by a session command.
236  */
237 void jack_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 int
272 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 int
283 jack_client_has_session_callback (jack_client_t *client, const(char) *client_name) /* JACK_WEAK_EXPORT */;
284 
285 }