NSM: Add clarification to the API document.
This commit is contained in:
Jonathan Moore Liles
parent
5c6e9f8d37
commit
d7cf8955b8
|
|
@ -6,12 +6,13 @@
|
|||
<title>Non Session Management API</title>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<div id=cover>
|
||||
<h1>Non Session Management API</h1>
|
||||
<h3></h3>
|
||||
<address>
|
||||
Jonathan Moore Liles <a href="mailto:male@tuxfamily.org"><male@tuxfamily.org></a><br>
|
||||
August 1, 2010<br>
|
||||
<br>
|
||||
Version 1.2
|
||||
</address><img src="icon.png" alt="logo"><hr></div>
|
||||
<div id=body>
|
||||
|
|
@ -188,6 +189,9 @@ Note that if the application intends to register JACK clients, <tt>application_n
|
|||
<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>
|
||||
</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>
|
||||
<caption>
|
||||
<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>
|
||||
</table></div>
|
||||
<p>
|
||||
<tt>path_to_instance_specific_project</tt> is a path name assigned to the client for storing its project data.
|
||||
</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>
|
||||
If a project exists at the path, the client <b>MUST</b> immediately open it.
|
||||
</p>
|
||||
|
|
@ -375,7 +383,7 @@ Or
|
|||
<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>
|
||||
<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>
|
||||
<div class="fig example"><table width=100%><tr><td><pre>
|
||||
/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>
|
||||
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>
|
||||
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>
|
||||
/nsm/client/gui_is_hidden
|
||||
</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>
|
||||
</table></div></center>
|
||||
<dl>
|
||||
<dt><em>/nsm/server/add s:path_to_executable</em></dt>
|
||||
<dt><em>/nsm/server/add s:executable_name</em></dt>
|
||||
</dl>
|
||||
<p>
|
||||
Adds a client to the current session.
|
||||
|
|
@ -527,7 +538,7 @@ Adds a client to the current session.
|
|||
Saves the current session.
|
||||
</p>
|
||||
<dl>
|
||||
<dt><em>/nsm/server/load s:project_name</em></dt>
|
||||
<dt><em>/nsm/server/open s:project_name</em></dt>
|
||||
</dl>
|
||||
<p>
|
||||
Saves the current session and loads a new session.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,6 @@
|
|||
|
||||
! title Non Session Management API
|
||||
! author Jonathan Moore Liles #(email,male@tuxfamily.org)
|
||||
! date August 1, 2010
|
||||
! revision Version 1.2
|
||||
! extra #(image,logo,icon.png)
|
||||
|
||||
|
|
@ -173,10 +172,19 @@
|
|||
breifly while awaiting the `announce` reply and
|
||||
subsequent `open` message.
|
||||
|
||||
|
||||
`capabilities` *MUST* be a string containing a colon separated list
|
||||
of the special capabilities the client
|
||||
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
|
||||
[[ Name, Description
|
||||
[[ 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
|
||||
|
||||
`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 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
|
||||
to the name when opening an existing project, as NSM will only
|
||||
provide the instance specific part of the path.
|
||||
|
|
@ -389,7 +397,11 @@
|
|||
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.
|
||||
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
|
||||
|
||||
|
|
@ -428,6 +440,9 @@
|
|||
it's announce message to indicate the initial visibility state of
|
||||
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_shown
|
||||
|
|
@ -529,7 +544,7 @@
|
|||
[[ ERR_NO_SESSION, No session is open
|
||||
[[ 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.
|
||||
|
||||
|
|
@ -537,7 +552,7 @@
|
|||
|
||||
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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue