jackaudio
/
jack1
mirror of https://github.com/jackaudio/jack1
1
0
Fork 0
Code Releases 19 Activity
Browse Source

updated comments for session.h from drobilla - no functional changes at all. docs have been updated at jackaudio.org 

git-svn-id: svn+ssh://jackaudio.org/trunk/jack@4142 0c269be4-1314-0410-8aa9-9f06e86f4224
tags/0.120.2
paul 14 years ago
parent
c22f9aecbb
commit
f8c1e777a3
2 changed files with 116 additions and 87 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +1
    -1
      configure.ac
  2. +115
    -86
      jack/session.h

+ 1
- 1
configure.ac View File

@@ -62,7 +62,7 @@ dnl changes are made
dnl ---
JACK_MAJOR_VERSION=0
JACK_MINOR_VERSION=120
JACK_MICRO_VERSION=1
JACK_MICRO_VERSION=2

dnl ---
dnl HOWTO: updating the jack protocol version


+ 115
- 86
jack/session.h View File

@@ -14,9 +14,8 @@
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
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__
@@ -36,79 +35,112 @@ extern "C" {


/**
* session event types.
* Session event type.
*
* 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)
* 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.
* An error occured while saving.
*/
JackSessionSaveError = 0x01,

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

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

struct _jack_session_event {
/**
* the actual type of this session event.
* The 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.
* 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 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.
* 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;

/**
* 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.
* Reply (set by client): the command line needed to restore the client.
*
* it should contain ${SESSION_DIR} instead of the actual session dir.
* this would basically make the session dir moveable.
* 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.
*
* memory will be freed along with jack_session_event_free()
* initially set to NULL by jack;
* 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;

/**
* flags to be set by the client. normally left 0.
* Reply (set by client): Session flags.
*/
jack_session_flags_t flags;

/**
* future flags. will be set to zero for now.
* Future flags. Set to zero for now.
*/
uint32_t future;
};
@@ -119,17 +151,16 @@ 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.
* 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 is also required to call jack_session_reply for this event.
* there is no timeout yet. and the only way to get back to a sane state
* would be to kill this client.
* The client must promptly call jack_session_reply for this event.
*
* @param event the event_structure.
* @param arg pointer to a client supplied structure
* @param event The event structure.
* @param arg Pointer to a client supplied structure.
*/
typedef void (*JackSessionCallback)(jack_session_event_t *event, void *arg);
typedef void (*JackSessionCallback)(jack_session_event_t *event,
void *arg);

/**
* Tell the JACK server to call @a session_callback when a session event
@@ -141,21 +172,21 @@ typedef void (*JackSessionCallback)(jack_session_event_t *event, void *arg);
*
* @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;
int jack_set_session_callback (jack_client_t *client,
JackSessionCallback session_callback,
void *arg) JACK_WEAK_EXPORT;

/**
* reply to a session_event
* 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.
* 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;
int jack_session_reply (jack_client_t *client,
jack_session_event_t *event) JACK_WEAK_EXPORT;


/**
@@ -163,7 +194,6 @@ int jack_session_reply( jack_client_t *client, jack_session_event_t *event ) JAC
* 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;


@@ -175,77 +205,76 @@ void jack_session_event_free (jack_session_event_t *event) JACK_WEAK_EXPORT;

char *jack_client_get_uuid (jack_client_t *client) 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.
* @defgroup JackSessionManagerAPI API for a session manager.
*
* @{
*/

typedef struct {
const char *uuid;
const char *client_name;
const char *command;
jack_session_flags_t flags;
const char *uuid;
const char *client_name;
const char *command;
jack_session_flags_t flags;
} 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 == NULL
* target == NULL means send to all interested clients. otherwise a clientname
* 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;
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.
* Free the memory allocated by a session command.
*/

void jack_session_commands_free (jack_session_command_t *cmds) JACK_WEAK_EXPORT;

/**
* get the sessionid for a client name.
* the sessionmanager needs this to reassociate a client_name to the session_id.
* 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;
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
* 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;
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 to a uuid.
* when a client later call 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.
* 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;
jack_reserve_client_name (jack_client_t *client,
const char *name,
const char *uuid) JACK_WEAK_EXPORT;

/**
* find out whether a client has setup a session callback.
* 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.
* -1 on error.
*/
int
jack_client_has_session_callback (jack_client_t *client, const char *client_name) JACK_WEAK_EXPORT;


Write Preview
Loading…
Cancel
Save