mirrors
/
non
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

NSM: Add clarification to the API document.

This commit is contained in:
Jonathan Moore Liles 2013-04-06 13:02:29 -07:00
parent 5c6e9f8d37
commit d7cf8955b8
2 changed files with 36 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
session-manager/doc/API.html
View File

@ -6,12 +6,13 @@
<title>Non Session Management API</title> <title>Non Session Management API</title>
</head> </head>
<body> <body>
<div id=cover> <div id=cover>
<h1>Non Session Management API</h1> <h1>Non Session Management API</h1>
<h3></h3> <h3></h3>
<address> <address>
Jonathan Moore Liles <a href="mailto:male@tuxfamily.org">&lt;male@tuxfamily.org&gt;</a><br> Jonathan Moore Liles <a href="mailto:male@tuxfamily.org">&lt;male@tuxfamily.org&gt;</a><br>
August 1, 2010<br> <br>
Version 1.2 Version 1.2
</address><img src="icon.png" alt="logo"><hr></div> </address><img src="icon.png" alt="logo"><hr></div>
<div id=body> <div id=body>
@ -188,6 +189,9 @@ Note that if the application intends to register JACK clients, <tt>application_n
<p> <p>
<tt>capabilities</tt> <b>MUST</b> be a string containing a colon separated list of the special capabilities the client possesses. e.g. <tt>:dirty:switch:progress:</tt> <tt>capabilities</tt> <b>MUST</b> be a string containing a colon separated list of the special capabilities the client possesses. e.g. <tt>:dirty:switch:progress:</tt>
</p> </p>
<p>
<tt>executable_name</tt> <b>MUST</b> be the executable name that the program was launched with. For C programs, this is simply the value of <tt>argv[0]</tt>. Note that hardcoding the name of the program here is not the same as using, as the user may have launched the program from a script with a different name using exec, or have created a symlink to the program. Getting the correct value in scripting languages like Python can be more challenging.
</p>
<center><div class="fig table"><table id="Fig.1.1" border=1> <center><div class="fig table"><table id="Fig.1.1" border=1>
<caption> <caption>
<strong>Fig. 1.1.</strong> Available Client Capabilities <strong>Fig. 1.1.</strong> Available Client Capabilities
@ -278,7 +282,11 @@ There is no message for this. Clients will receive the Unix SIGTERM signal and <
</pre></td></tr> </pre></td></tr>
</table></div> </table></div>
<p> <p>
<tt>path_to_instance_specific_project</tt> is a path name assigned to the client for storing its project data.
</p>
<p> <p>
The client may append to the path, creating a sub-directory, e.g. '/song.foo' or simply append the client's native file extension (e.g. '.non' or '.XML'). The same transformation <b>MUST</b> be applied to the name when opening an existing project, as NSM will only provide the instance specific part of the path.
</p>
<p> <p>
If a project exists at the path, the client <b>MUST</b> immediately open it. If a project exists at the path, the client <b>MUST</b> immediately open it.
</p> </p>
@ -375,7 +383,7 @@ Or
<h3 id="n:1.2.3.">1.2.3. Server to Client Informational Messages</h3> <h3 id="n:1.2.3.">1.2.3. Server to Client Informational Messages</h3>
<h4 id="n:1.2.3.1.">1.2.3.1. Session is Loaded</h4> <h4 id="n:1.2.3.1.">1.2.3.1. Session is Loaded</h4>
<p> <p>
Accepting this message is optional. The intent is to signal to clients which may have some interdependence (say, peer to peer OSC connections) that the session is fully loaded and all their peers are available. Accepting this message is optional. The intent is to signal to clients which may have some interdependence (say, peer to peer OSC connections) that the session is fully loaded and all their peers are available. Most clients will not need to act on this message. This message has no meaning when a session is being built or run--only when it is initially loaded. Clients who intend to act on this message <b>MUST</b> not do so by delaying initialization waiting for it.
</p> </p>
<div class="fig example"><table width=100%><tr><td><pre> <div class="fig example"><table width=100%><tr><td><pre>
/nsm/client/session_is_loaded /nsm/client/session_is_loaded
@ -407,6 +415,9 @@ These are optional messages which a client can send to the NSM server to inform
<p> <p>
If the client has specified the <tt>optional-gui</tt> capability, then it <b>MUST</b> send this message whenever the state of visibility of the optional GUI has changed. It also <b>MUST</b> send this message after it's announce message to indicate the initial visibility state of the optional GUI. If the client has specified the <tt>optional-gui</tt> capability, then it <b>MUST</b> send this message whenever the state of visibility of the optional GUI has changed. It also <b>MUST</b> send this message after it's announce message to indicate the initial visibility state of the optional GUI.
</p> </p>
<p>
It is the responsibility of the client to remember the visibility state of its GUI across session loads.
</p>
<div class="fig example"><table width=100%><tr><td><pre> <div class="fig example"><table width=100%><tr><td><pre>
/nsm/client/gui_is_hidden /nsm/client/gui_is_hidden
</pre></td></tr> </pre></td></tr>
@ -515,7 +526,7 @@ The possible errors are:
<tr><td>ERR_UNSAVED_CHANGES</td><td>Unsaved changes would be lost</td></tr> <tr><td>ERR_UNSAVED_CHANGES</td><td>Unsaved changes would be lost</td></tr>
</table></div></center> </table></div></center>
<dl> <dl>
<dt><em>/nsm/server/add s:path_to_executable</em></dt> <dt><em>/nsm/server/add s:executable_name</em></dt>
</dl> </dl>
<p> <p>
Adds a client to the current session. Adds a client to the current session.
@ -527,7 +538,7 @@ Adds a client to the current session.
Saves the current session. Saves the current session.
</p> </p>
<dl> <dl>
<dt><em>/nsm/server/load s:project_name</em></dt> <dt><em>/nsm/server/open s:project_name</em></dt>
</dl> </dl>
<p> <p>
Saves the current session and loads a new session. Saves the current session and loads a new session.

27
session-manager/doc/API.mu
View File

@ -1,7 +1,6 @@
! title Non Session Management API ! title Non Session Management API
! author Jonathan Moore Liles #(email,male@tuxfamily.org) ! author Jonathan Moore Liles #(email,male@tuxfamily.org)
! date August 1, 2010
! revision Version 1.2 ! revision Version 1.2
! extra #(image,logo,icon.png) ! extra #(image,logo,icon.png)
@ -173,10 +172,19 @@
breifly while awaiting the `announce` reply and breifly while awaiting the `announce` reply and
subsequent `open` message. subsequent `open` message.
`capabilities` *MUST* be a string containing a colon separated list `capabilities` *MUST* be a string containing a colon separated list
of the special capabilities the client of the special capabilities the client
possesses. e.g. `:dirty:switch:progress:` possesses. e.g. `:dirty:switch:progress:`
`executable\_name` *MUST* be the executable name that the program
was launched with. For C programs, this is simply the value of
`argv[0]`. Note that hardcoding the name of the program here is not
the same as using, as the user may have launched the program from a
script with a different name using exec, or have created a symlink
to the program. Getting the correct value in scripting languages
like Python can be more challenging.
// Available Client Capabilities // Available Client Capabilities
[[ Name, Description [[ Name, Description
[[ switch, client is capable of responding to multiple `open` messages without restarting [[ switch, client is capable of responding to multiple `open` messages without restarting
@ -261,11 +269,11 @@
> /nsm/client/open s:path_to_instance_specific_project s:display_name s:client_id > /nsm/client/open s:path_to_instance_specific_project s:display_name s:client_id
`path\_to\_instance_specific\_project` is a path name assigned to `path\_to\_instance\_specific\_project` is a path name assigned to
the client for storing its project data. the client for storing its project data.
The client may append to the path, creating a sub-directory, The client may append to the path, creating a sub-directory,
e.g. '/song.foo' or simply append the client's native file extension e.g. '\/song.foo' or simply append the client's native file extension
(e.g. '.non' or '.XML'). The same transformation *MUST* be applied (e.g. '.non' or '.XML'). The same transformation *MUST* be applied
to the name when opening an existing project, as NSM will only to the name when opening an existing project, as NSM will only
provide the instance specific part of the path. provide the instance specific part of the path.
@ -389,7 +397,11 @@
Accepting this message is optional. The intent is to signal to Accepting this message is optional. The intent is to signal to
clients which may have some interdependence (say, peer to peer OSC clients which may have some interdependence (say, peer to peer OSC
connections) that the session is fully loaded and all their peers connections) that the session is fully loaded and all their peers
are available. are available. Most clients will not need to act on this
message. This message has no meaning when a session is being built
or run--only when it is initially loaded. Clients who intend to act
on this message *MUST* not do so by delaying initialization waiting
for it.
> /nsm/client/session_is_loaded > /nsm/client/session_is_loaded
@ -428,6 +440,9 @@
it's announce message to indicate the initial visibility state of it's announce message to indicate the initial visibility state of
the optional GUI. the optional GUI.
It is the responsibility of the client to remember the visibility
state of its GUI across session loads.
> /nsm/client/gui_is_hidden > /nsm/client/gui_is_hidden
> /nsm/client/gui_is_shown > /nsm/client/gui_is_shown
@ -529,7 +544,7 @@
[[ ERR_NO_SESSION, No session is open [[ ERR_NO_SESSION, No session is open
[[ ERR_UNSAVED_CHANGES, Unsaved changes would be lost [[ ERR_UNSAVED_CHANGES, Unsaved changes would be lost
= /nsm/server/add s:path_to_executable = /nsm/server/add s:executable_name
Adds a client to the current session. Adds a client to the current session.
@ -537,7 +552,7 @@
Saves the current session. Saves the current session.
= /nsm/server/load s:project_name = /nsm/server/open s:project_name
Saves the current session and loads a new session. Saves the current session and loads a new session.