This file is indexed.

/usr/include/jack/session.h is in libjack-dev 1:0.121.0+svn4538-3ubuntu1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
/*
    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 <jack/types.h>
#include <jack/weakmacros.h>

/**
 * @defgroup SessionClientFunctions Session API for clients.
 * @{
 */


/**
 * Session event type.
 *
 * if a client cant save templates, i might just do a normal save.
 *
 * 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.
     */
    JackSessionSaveError = 0x01,

    /**
     * Client needs to be run in a terminal.
     */
    JackSessionNeedTerminal = 0x02
};

/**
 * Session flags.
 */
typedef enum JackSessionFlags jack_session_flags_t;

struct _jack_session_event {
    /**
     * The type of this session event.
     */
    jack_session_event_type_t type;

    /**
     * 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 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;

    /**
     * Reply (set by client): the command line needed to restore the client.
     *
     * 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.
     *
     * 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;

    /**
     * Reply (set by client): Session flags.
     */
    jack_session_flags_t flags;

    /**
     * Future flags. Set to zero for now.
     */
    uint32_t future;
};

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.
 *
 * The client must promptly call jack_session_reply for this event.
 *
 * @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 session_callback when a session event
 * is to be delivered.
 *
 * setting more than one session_callback per process is probably a design
 * error. if you have a multiclient application its more sensible to create
 * a jack_client with only a session callback set. 
 *
 * @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.  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;


/**
 * free memory used by a jack_session_event_t
 * 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;


/**
 * get the assigned uuid for client.
 * safe to call from callback and all other threads.
 * memory needs to be freed.
 */

char *jack_client_get_uuid (jack_client_t *client) JACK_WEAK_EXPORT;

/**
 * @}
 */

/**
 * @defgroup JackSessionManagerAPI API for a session manager.
 *
 * @{
 */

typedef struct  {
	const char           *uuid;
	const char           *client_name;
	const char           *command;
	jack_session_flags_t  flags;
} jack_session_command_t;

/**
 * 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;

/**
 * Free the memory allocated by a session command.
 */
void jack_session_commands_free (jack_session_command_t *cmds) JACK_WEAK_EXPORT;

/**
 * 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;

/**
 * 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;

/**
 * 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;

/**
 * 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.
 */
int
jack_client_has_session_callback (jack_client_t *client, const char *client_name) JACK_WEAK_EXPORT;

/**
 * @}
 */

#ifdef __cplusplus
}
#endif
#endif