2006-10-05 11:01:25 +03:00
|
|
|
|
This is lash-manual.info, produced by makeinfo version 4.8 from
|
|
|
|
|
lash-manual.texi.
|
|
|
|
|
|
|
|
|
|
This is the LASH Audio Session Handler Reference Manual, Edition
|
|
|
|
|
0.5.1, March 2006 for LASH version 0.5.1.
|
|
|
|
|
|
|
|
|
|
Copyright (C) 2002, 2003 Robert Ham (rah@bash.sh) Copyright (C)
|
|
|
|
|
2005, 2006 Dave Robillard (drobilla@connect.carleton.ca)
|
|
|
|
|
|
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
|
|
|
under the terms of the GNU Free Documentation License, Version 1.2 or
|
|
|
|
|
any later version published by the Free Software Foundation; with no
|
|
|
|
|
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
|
|
|
|
copy of the license is included in the section entitled "GNU Free
|
|
|
|
|
Documentation License".
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: lash-manual.info, Node: Top, Next: Introduction, Up: (dir)
|
|
|
|
|
|
|
|
|
|
This is the LASH Audio Session Handler Reference Manual, edition
|
|
|
|
|
0.5.1, March 2006 for LASH version 0.5.1.
|
|
|
|
|
|
|
|
|
|
`http://www.nongnu.org/lash'
|
|
|
|
|
|
|
|
|
|
* Menu:
|
|
|
|
|
|
|
|
|
|
* Introduction:: What LASH is all about
|
|
|
|
|
* Copying LASH:: How you can copy and distribute the LASH source code
|
|
|
|
|
* Installation:: How to get LASH onto your computer
|
|
|
|
|
* Server:: How to use the LASH server, `lashd'
|
|
|
|
|
* Server interface:: How to use the simple LASH server interface, `lash_control'
|
|
|
|
|
* Client reference:: How to program LASH clients using `liblash'
|
|
|
|
|
|
|
|
|
|
Appendicies
|
|
|
|
|
* GNU Free Documentation License:: How you can copy and distribute this document.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: lash-manual.info, Node: Introduction, Next: Copying LASH, Prev: Top, Up: Top
|
|
|
|
|
|
|
|
|
|
1 Introduction
|
|
|
|
|
**************
|
|
|
|
|
|
|
|
|
|
LASH stands for LASH Audio Session Handler. It is a session management
|
|
|
|
|
system for audio applications on GNU/Linux. It understands the JACK
|
|
|
|
|
low latency audio API and the ALSA MIDI sequencer interface. The system
|
|
|
|
|
is comprised of a server program, `lashd', an application library,
|
|
|
|
|
`liblash', and a control program - either the command-line
|
|
|
|
|
`lash_control' or the GTK `lash_panel'. The server and clients
|
|
|
|
|
communicate over TCP sockets. There are three kinds of clients: normal
|
|
|
|
|
clients (audio applications), user interfaces for the server, and
|
|
|
|
|
connection patchbays.
|
|
|
|
|
|
|
|
|
|
1.1 Nomenclature
|
|
|
|
|
================
|
|
|
|
|
|
|
|
|
|
In order to describe the system, we should introduce some terminology.
|
|
|
|
|
First of all, the "server" is the `lashd' server program, an
|
|
|
|
|
omni-present marshaller and database for storing arbitrary application
|
|
|
|
|
data. The "library" is the `liblash' shared library. It contains all
|
|
|
|
|
the functions that an application uses to communicate with the server
|
|
|
|
|
and take part in the system. Such an application is called a "client".
|
|
|
|
|
|
|
|
|
|
The server deals with things in terms of collections of clients,
|
|
|
|
|
called "projects". A project has a unique string name, a current
|
|
|
|
|
directory and a list of clients that are in that project. The server
|
|
|
|
|
can have one client that is a "server interface" that allows the user
|
|
|
|
|
to control the server. There are two server interface included with
|
|
|
|
|
the system, the `lash_control' command-line interface, and the
|
|
|
|
|
`lash_panel' GTK interface.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: lash-manual.info, Node: Copying LASH, Next: Installation, Prev: Introduction, Up: Top
|
|
|
|
|
|
|
|
|
|
2 Copying LASH
|
|
|
|
|
**************
|
|
|
|
|
|
|
|
|
|
LASH is distributed under the GNU General Public License. A copy of
|
|
|
|
|
the license text is provided in the file `COPYING' along with the
|
|
|
|
|
software source code, or you can get a copy by writing to the Free
|
|
|
|
|
Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
|
|
|
|
|
02110-1301 USA.
|
|
|
|
|
|
|
|
|
|
In plain english, the GPL basically restricts you from restricting
|
|
|
|
|
other people's use of the LASH source code (ie, all of LASH), and any
|
|
|
|
|
additions you make to the code, including linking with the LASH
|
|
|
|
|
library. If you use code from this software, your software must be
|
|
|
|
|
relased under the GPL. If you modify this software and release it,
|
|
|
|
|
your modifications must be released under the GPL. If you release
|
|
|
|
|
software linked against the LASH library, your software must be
|
|
|
|
|
released under the GPL.
|
|
|
|
|
|
|
|
|
|
Note that this in no way restricts those people who want to release
|
|
|
|
|
non-free LASH clients. LASH operates using a well defined protocol
|
|
|
|
|
over TCP sockets. The high-level protocol is described within this
|
|
|
|
|
document and the lower-level bit-wise protocol can be garnered from the
|
|
|
|
|
source itself.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: lash-manual.info, Node: Installation, Next: Server, Prev: Copying LASH, Up: Top
|
|
|
|
|
|
|
|
|
|
3 Installation
|
|
|
|
|
**************
|
|
|
|
|
|
|
|
|
|
This chapter describes how to get LASH installed on your system.
|
|
|
|
|
|
|
|
|
|
3.1 Dependencies
|
|
|
|
|
================
|
|
|
|
|
|
|
|
|
|
LASH depends on the ALSA library, the JACK library, a unique ID library
|
|
|
|
|
called libuuid and the XML library libxml2. You need these installed
|
|
|
|
|
before attempting to install LASH.
|
|
|
|
|
|
|
|
|
|
ALSA is available from `http://www.alsa-project.org/'.
|
|
|
|
|
|
|
|
|
|
JACK is available from `http://jackit.sf.net/'.
|
|
|
|
|
|
|
|
|
|
The libuuid library is included with the ubiquitous e2fsprogs
|
|
|
|
|
package, but if this is not installed on your system, it is available
|
|
|
|
|
from `http://e2fsprogs.sf.net/'. The libxml2 library is available from
|
|
|
|
|
`http://www.xmlsoft.org/'.
|
|
|
|
|
|
|
|
|
|
The LASH Control client depends on the GNU Readline library,
|
|
|
|
|
available from `ftp://ftp.gnu.org/pub/gnu/readline/'.
|
|
|
|
|
|
|
|
|
|
The LASH GTK Test Client, LASH Save Button, and LASH Panel all
|
|
|
|
|
depend on the GTK+ 2 toolkit, available from
|
|
|
|
|
`ftp://ftp.gtk.org/pub/gtk/v2.0/'. The LASH Synth client has an
|
|
|
|
|
optional GUI which also uses the GTK+ 2 toolkit.
|
|
|
|
|
|
|
|
|
|
3.2 Installation
|
|
|
|
|
================
|
|
|
|
|
|
|
|
|
|
First off, you need to download the package. It is available from the
|
|
|
|
|
LASH webpage, `http://www.nongnu.org/lash'. After you have downloaded
|
|
|
|
|
it, unpack the tarball into a directory using `tar -xzf
|
|
|
|
|
/where/ever/you/put/lash-0.5.1.tar.gz' and change into the source
|
|
|
|
|
directory with `cd lash-0.5.1'.
|
|
|
|
|
|
|
|
|
|
The package uses the GNU autotools for configuration and makefile
|
|
|
|
|
creation. In order to install the package, you must complete three
|
|
|
|
|
steps: configuration; building; and installing.
|
|
|
|
|
|
|
|
|
|
3.2.1 Configuration
|
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
|
|
To configure the package, there is a shell script named `configure' in
|
|
|
|
|
the top source directory. It is a standard GNU autoconf configure
|
|
|
|
|
script, and so accepts the standard GNU configuration options (such as
|
|
|
|
|
`--prefix', `--datadir', etc.) To run it type `./configure' and add
|
|
|
|
|
any options. The non-standard options that the script recognises are
|
|
|
|
|
described below. Running the script with the `--help' option will also
|
|
|
|
|
provide a quick summary of the recognised options.
|
|
|
|
|
|
|
|
|
|
3.2.1.1 Configure script options
|
|
|
|
|
................................
|
|
|
|
|
|
|
|
|
|
`--disable-gtk2 Prevents the configure script from'
|
|
|
|
|
checking for the presence of the GTK+ 2 toolkit and disables the
|
|
|
|
|
building of any code that relies on it.
|
|
|
|
|
|
|
|
|
|
`--enable-debug Causes the library, server and clients to be built'
|
|
|
|
|
with debugging output. This is not very useful and only
|
|
|
|
|
recommended for developers working on the LASH code itself.
|
|
|
|
|
|
|
|
|
|
`--with-default-dir=DIR Specifies the default directory, relative'
|
|
|
|
|
to \$HOME under which the server will create new project
|
|
|
|
|
directories. Without this option, the value defaults to
|
|
|
|
|
`audio-projects'.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3.2.2 Building
|
|
|
|
|
--------------
|
|
|
|
|
|
|
|
|
|
To build the package, simply type `make' in the top source directory.
|
|
|
|
|
This will build the server, the library and the clients that are
|
|
|
|
|
compatible with the resources found by the configure script.
|
|
|
|
|
|
|
|
|
|
3.2.3 Installing
|
|
|
|
|
----------------
|
|
|
|
|
|
|
|
|
|
To install the package, type `make install' in the top source
|
|
|
|
|
directory. By default the package installation prefix is `/usr/local'
|
|
|
|
|
but the `--prefix' option to the configure script will change this.
|
|
|
|
|
The `lashd' server and the clients that were built are installed in
|
|
|
|
|
`PREFIX/bin'. The `liblash' client library is installed in
|
|
|
|
|
`PREFIX/lib'. The C header files for the client library are installed
|
|
|
|
|
under `PREFIX/include'. This manual is installed under `PREFIX/info'.
|
|
|
|
|
|
|
|
|
|
With `make install', the package is installed with debugging symbols
|
|
|
|
|
in the object files. To save space, you can install with `make
|
|
|
|
|
install-strip' to install the object files without debugging symbols.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: lash-manual.info, Node: Server, Next: Server interface, Prev: Installation, Up: Top
|
|
|
|
|
|
|
|
|
|
4 Server
|
|
|
|
|
********
|
|
|
|
|
|
|
|
|
|
The LASH server is called `lashd'.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: lash-manual.info, Node: Server interface, Next: Client reference, Prev: Server, Up: Top
|
|
|
|
|
|
|
|
|
|
5 Server interface
|
|
|
|
|
******************
|
|
|
|
|
|
|
|
|
|
For a command line interface, run the command `lashd_control'. There
|
|
|
|
|
is a `help' command.
|
|
|
|
|
|
|
|
|
|
For a graphical interface, run the command `lash_panel'. It should
|
|
|
|
|
be relatively self-explanatory.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: lash-manual.info, Node: Client reference, Next: Operational overview, Prev: Server interface, Up: Top
|
|
|
|
|
|
|
|
|
|
6 Client reference
|
|
|
|
|
******************
|
|
|
|
|
|
|
|
|
|
This chapter provides a programming guide and library reference for
|
|
|
|
|
programmers of LASH clients.
|
|
|
|
|
|
|
|
|
|
* Menu:
|
|
|
|
|
|
|
|
|
|
* Operational overview:: An overview of how servers and clients operate
|
|
|
|
|
* Types and functions:: A detailed description of types and function that LASH clients can use
|
|
|
|
|
* Event protocol:: A detailed description of the protocol used for client/server communication
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: lash-manual.info, Node: Operational overview, Next: Types and functions, Prev: Client reference, Up: Client reference
|
|
|
|
|
|
|
|
|
|
6.1 Operational overview
|
|
|
|
|
========================
|
|
|
|
|
|
|
|
|
|
In this section we give an overview of how the LASH system operates,
|
|
|
|
|
describing the server and client objects and operations that make it
|
|
|
|
|
work. The `lashd' server must be running in order for clients to
|
|
|
|
|
participate in the system; clients cannot interoperate soley between
|
|
|
|
|
themselves. The server maintains a list of connected clients and a list
|
|
|
|
|
of projects with which these clients are associated.
|
|
|
|
|
|
|
|
|
|
The server and clients exchange events and configs over their
|
|
|
|
|
connections. There is one, and only one, bi-directional connection
|
|
|
|
|
between a client and the server. The transport for this connection is
|
|
|
|
|
currently TCP.
|
|
|
|
|
|
|
|
|
|
An "event" is a very simple object having two relevant properties: a
|
|
|
|
|
type and an optional arbitrary character string. The type defines what
|
|
|
|
|
the event means to the recipient, and the string allows additional
|
|
|
|
|
information to be included with it. For example, if a client wishes
|
|
|
|
|
the server to save the current project, it sends a `LASH_Save' event to
|
|
|
|
|
the server. While saving the project, the server may wish to tell a
|
|
|
|
|
client to save its data in a certain directory. To so, it sends a
|
|
|
|
|
`LASH_Save_File' event to the client with a string containing the name
|
|
|
|
|
of a directory into which the client should save its data files.
|
|
|
|
|
|
|
|
|
|
Clients can save data on the server if they wish. To do this, the
|
|
|
|
|
client declares that it wants to save data on the server when it
|
|
|
|
|
initialises the server connection and then later sends one or more
|
|
|
|
|
"config"s to the server. A config is also a very simple object. It
|
|
|
|
|
has a client-unique character string key, and a value of arbitrary size
|
|
|
|
|
and type (well, almost arbitrary; its size must be able to be described
|
|
|
|
|
by a `uint32_t' integer due to byte-order conversions done when sending
|
|
|
|
|
data over the network.)
|
|
|
|
|
|
|
|
|
|
6.1.1 Session example
|
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
|
|
In this section we will examine a typical session in some detail,
|
|
|
|
|
describing the server and client operations that take place. In the
|
|
|
|
|
session, the server is started, a number of clients connect, the session
|
|
|
|
|
is saved and then restored.
|
|
|
|
|
|
|
|
|
|
6.1.1.1 Starting up the server
|
|
|
|
|
..............................
|
|
|
|
|
|
|
|
|
|
Before all else, the user starts the server. It starts up and begins
|
|
|
|
|
listening for connections from clients. It doesn't do much else.
|
|
|
|
|
|
|
|
|
|
To keep track of what is happening with LASH, the user can run the
|
|
|
|
|
`lash_panel' program (though this is not necessary, and it can be
|
|
|
|
|
started later at any time).
|
|
|
|
|
|
2006-10-17 11:01:23 +03:00
|
|
|
|
Unless the environment variable `LASH_NO_START_SERVER' is set any
|
|
|
|
|
LASH client will automatically start the server if one isn't already running.
|
|
|
|
|
Doing this you can simply run applications normally (e.g. from a terminal or
|
|
|
|
|
your Applications menu) and have LASH automatically work without having to
|
|
|
|
|
remember to start the server manually.
|
2006-10-05 11:01:25 +03:00
|
|
|
|
|
2006-10-17 11:01:23 +03:00
|
|
|
|
Starting the server can also be disabled by specifying the
|
2006-10-05 11:01:25 +03:00
|
|
|
|
`--lash-no-start-server' option on the client's command line.
|
|
|
|
|
|
|
|
|
|
If you're using a Bourne compatible shell like `bash' (if you don't
|
2006-10-17 11:01:23 +03:00
|
|
|
|
know, you probably are) you can disable auto-start with the following
|
2006-10-05 11:01:25 +03:00
|
|
|
|
command:
|
|
|
|
|
|
2006-10-17 11:01:23 +03:00
|
|
|
|
`export LASH_NO_START_SERVER=1'
|
|
|
|
|
|
|
|
|
|
Some applications may also choose themselves whether to start the
|
|
|
|
|
server (or have a configurable option).
|
|
|
|
|
|
|
|
|
|
Disabling the automatic start is not recommended to gain the abilities LASH
|
|
|
|
|
intends to provide. With auto launching enabled you don't need to worry about
|
|
|
|
|
LASH until you actually want to save a session.
|
2006-10-05 11:01:25 +03:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
6.1.1.2 A client connection
|
|
|
|
|
...........................
|
|
|
|
|
|
|
|
|
|
The user then starts a JACK client program. It opens a connection to
|
|
|
|
|
the server and provides it with all information that the server will
|
|
|
|
|
need to run the application again. This information includes: the
|
|
|
|
|
current directory that the user was in when they ran the program, the
|
|
|
|
|
command line that started the application and the _class_ of the client
|
|
|
|
|
(a character string that the client application provides the
|
|
|
|
|
initialisation routine that will never change over all initialisations.)
|
|
|
|
|
|
|
|
|
|
With this information is included a set of flags that describe the
|
|
|
|
|
client to the server. This particular client saves data to files and
|
|
|
|
|
wants the server to tell it where to save files when the project is
|
|
|
|
|
saved, so it has the `LASH_Config_File' flag set.
|
|
|
|
|
|
|
|
|
|
The client library starts two threads for communication with the
|
|
|
|
|
server, one for sending data and the other for recieving. It also
|
|
|
|
|
sends, along with the client supplied data, a number of parameters that
|
|
|
|
|
were extracted from the client's command line options before it checked
|
|
|
|
|
them. This optionally includes the name of the project that the client
|
|
|
|
|
should initially be associated with and a 128-bit, world-unique
|
|
|
|
|
identifier for this particular client instance (the "LASH ID".)
|
|
|
|
|
|
|
|
|
|
Server-side, the server wakes up to the fact that a new connection
|
|
|
|
|
has arrived and immediately adds it to a list of open connections and
|
|
|
|
|
then goes back to waiting. When the client sends the requisite
|
|
|
|
|
information, the server looks at it and decides what to do with the
|
|
|
|
|
client. This client has not requested a specific project to which it
|
|
|
|
|
should be connected. However, there are no existing projects so the
|
|
|
|
|
server creates a new project with the name `project-1' in the directory
|
|
|
|
|
`/home/USER/audio-projects/project-1' (assuming the user didn't specify
|
|
|
|
|
a different default directory when running configure.) It also
|
|
|
|
|
generates a new LASH ID for the client. It then adds the client to the
|
|
|
|
|
new project and goes back to listening.
|
|
|
|
|
|
|
|
|
|
If the user has the `lash_panel' client running, the new project
|
|
|
|
|
will appear as a tab with the title `project-1', and the new client
|
|
|
|
|
will appear in the client list for that project.
|
|
|
|
|
|
|
|
|
|
The client then connects up to the JACK server and, after having done
|
|
|
|
|
this, sends a `LASH_Jack_Client_Name' event to the server with the name
|
|
|
|
|
that it registered to JACK with as the string. This notifies the
|
|
|
|
|
server that it is a JACK client and needs its JACK port connections
|
|
|
|
|
saved and restored. The server will now pay attention to any activity
|
|
|
|
|
regarding the client (ie, port creation and destruction and port
|
|
|
|
|
connection and disconnection.)
|
|
|
|
|
|
|
|
|
|
6.1.1.3 Another client
|
|
|
|
|
......................
|
|
|
|
|
|
|
|
|
|
The user then starts a second client that uses the ALSA sequencer
|
|
|
|
|
interface and wishes to save data on the server. It connects to the
|
|
|
|
|
server with a different class to the JACK client and with the
|
|
|
|
|
`LASH_Config_Data_Set' flag set.
|
|
|
|
|
|
|
|
|
|
The server sees that this client also didn't specify a project, and
|
|
|
|
|
so adds it to the first available project; the same one as the previous
|
|
|
|
|
project, `project-1'. It also sees that the client wants to store data
|
|
|
|
|
on the server, and so it creates a directory within the project
|
|
|
|
|
directory for this data to be stored in and creates a database-style
|
|
|
|
|
object to manage the client's data.
|
|
|
|
|
|
|
|
|
|
If the user has the `lash_panel' client running, both clients will
|
|
|
|
|
now be visible in the clients list for `project-1'.
|
|
|
|
|
|
|
|
|
|
The client then connects to the ALSA sequencer and sends its client
|
|
|
|
|
ID to the server in the first character of the string of a
|
|
|
|
|
`LASH_Alsa_Client_Name' event. The server regards this similarly to
|
|
|
|
|
the other client's JACK client name.
|
|
|
|
|
|
|
|
|
|
6.1.1.4 Saving the project
|
|
|
|
|
..........................
|
|
|
|
|
|
|
|
|
|
After the user has done some work in the two clients, they want to save
|
|
|
|
|
their work. They click the Save button in `lash_panel' (or use the
|
|
|
|
|
`save' command in `lash_control'), and a `LASH_Save' event is sent to
|
|
|
|
|
the server. The server recieves this and then iterates through each
|
|
|
|
|
client in the project and checks its flags. The JACK client saves data
|
|
|
|
|
by itself (it has the `LASH_Config_File' flag set,) so the server
|
|
|
|
|
creates a directory under the project directory for it to save in and
|
|
|
|
|
then sends a `LASH_Save_File' event to the client with a string
|
|
|
|
|
containing the name of the directory it made. The client recieves the
|
|
|
|
|
event and saves its data into the specified directory.
|
|
|
|
|
|
|
|
|
|
Next, the server examines the ALSA client. It wishes to save data
|
|
|
|
|
on the server, so the server sends a `LASH_Save_Data_Set' to the client.
|
|
|
|
|
With all of the clients iterated through, it now saves all the
|
|
|
|
|
information it needs to be able to restore them; their working
|
|
|
|
|
directory, command line options, etc. In order to do this, it asks the
|
|
|
|
|
JACK server to find the connections for the JACK client, and asks the
|
|
|
|
|
ALSA sequencer to find the connections for the ALSA client. It uses
|
|
|
|
|
the client name and ID that both clients sent to the server after
|
|
|
|
|
opening their connections to the respective systems. All of this
|
|
|
|
|
information is stored in a file under the project's directory. When
|
|
|
|
|
this is done, the server goes back to listening for events and configs.
|
|
|
|
|
|
|
|
|
|
The client, meanwhile, has recieved the `LASH_Save_Data_Set' event
|
|
|
|
|
and sends back a number of configs to the server. When it has sent all
|
|
|
|
|
the data it wishes to be saved, it sends back a `LASH_Save_Data_Set'
|
|
|
|
|
event. The server passes all of the configs to the object managing the
|
|
|
|
|
data store for the ALSA client. When the server recieves the
|
|
|
|
|
`LASH_Save_Data_Set' event from the client, it tells the data store to
|
|
|
|
|
write the data to disk. The save is now complete.
|
|
|
|
|
|
|
|
|
|
6.1.1.5 Client resumption
|
|
|
|
|
.........................
|
|
|
|
|
|
|
|
|
|
Unfortunately for the user, the ALSA client crashes. The server detects
|
|
|
|
|
that the client has disconnected, and puts the client on a list of lost
|
|
|
|
|
clients for the project. The user then starts another copy of the
|
|
|
|
|
client, which connects to the server in the same way it did before.
|
|
|
|
|
This time, however, the server checks through the list of lost clients
|
|
|
|
|
and finds that the class of the new client matches the class of the
|
|
|
|
|
lost client and so it resumes the lost client using the new one. It
|
|
|
|
|
gives it the 128-bit ID of the lost client, adds it to the project, and
|
|
|
|
|
then sends a `LASH_Restore_Data_Set' event to the client. The client
|
|
|
|
|
then cleans itself up, ready to recieve the data set. The server sends
|
|
|
|
|
the client the configs, and then another `LASH_Restore_Data_Set' event.
|
|
|
|
|
The client recieves this data and its state has been restored that of
|
|
|
|
|
the client that crashed.
|
|
|
|
|
|
|
|
|
|
The user can stop this behaviour by specifying the
|
|
|
|
|
`--lash-no-autoresume' option on the client's command line.
|
|
|
|
|
|
|
|
|
|
6.1.1.6 Restoring the project
|
|
|
|
|
.............................
|
|
|
|
|
|
|
|
|
|
The user has to go off and do other things, and so they close down the
|
|
|
|
|
clients and the server. Some time later, the user comes back and wants
|
|
|
|
|
to start working again so first, as always, they start up the server.
|
|
|
|
|
They then start the `lash_panel' program. Using the File->Open menu
|
|
|
|
|
item, the user selects the directory (not file!) where they saved the
|
|
|
|
|
project (by default `~/audio-projects/project-1', but you can save to a
|
|
|
|
|
more descriptive name). The lash_panel client sends a `LASH_Restore'
|
|
|
|
|
event to the server with the specified directory as the string. The
|
|
|
|
|
server opens the file that it saved before, and reads in all the
|
|
|
|
|
information about the project and its clients. It creates a new
|
|
|
|
|
project with this information. The clients are created as lost
|
|
|
|
|
clients, however.
|
|
|
|
|
|
|
|
|
|
The server then iterates through each client and starts a new copy of
|
|
|
|
|
it using the information provided when the original client connected.
|
|
|
|
|
It also adds some command line options that are extracted by the client
|
|
|
|
|
library. These specify the LASH ID of the client, the project name
|
|
|
|
|
that it should be connecting to and the server's hostname and port. It
|
|
|
|
|
then goes back to waiting.
|
|
|
|
|
|
|
|
|
|
The new JACK client then connects to the server as normal. When the
|
|
|
|
|
server recieves it connection, it checks the client against the
|
|
|
|
|
project's list of lost clients. This time, however, it has its ID
|
|
|
|
|
specified, so the server will only resume a client with a matching ID.
|
|
|
|
|
Lo and behold, such a client exists. The server resumes the old JACK
|
|
|
|
|
client, telling it to load its state from the files in the project
|
|
|
|
|
directory that the client previously stored. It does so with a
|
|
|
|
|
`LASH_Restore_File' event with the string as the directory name. The
|
|
|
|
|
ALSA client does exactly the same, except having its data restored
|
|
|
|
|
through `LASH_Restore_Data_Set' as described above.
|
|
|
|
|
|
|
|
|
|
Only one thing remains for the clients to be fully restored: the
|
|
|
|
|
JACK and ALSA sequencer connections. This happens when the clients
|
|
|
|
|
send their `LASH_Jack_Client_Name' and `LASH_Alsa_Client_ID' events.
|
|
|
|
|
The connections are stored with the LASH ID rather than the JACK client
|
|
|
|
|
name or ALSA client ID. When the client registers its name or ID, the
|
|
|
|
|
connections are converted from the LASH ID to the JACK client name or
|
|
|
|
|
ALSA client ID, and the connections are restored. It also pays
|
|
|
|
|
attention to connections to other clients within the same project,
|
|
|
|
|
converting between JACK client names, ALSA client IDs and LASH IDs as
|
|
|
|
|
appropriate.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: lash-manual.info, Node: Types and functions, Next: Event protocol, Prev: Operational overview, Up: Client reference
|
|
|
|
|
|
|
|
|
|
6.2 Types and functions
|
|
|
|
|
=======================
|
|
|
|
|
|
|
|
|
|
6.2.1 Server interaction
|
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
|
|
-- Function: lash_client_t * lash_init (lash_args_t * ARGS, const char
|
|
|
|
|
* CLIENT_CLASS, int CLIENT_FLAGS, lash_protocol_t PROTOCOL)
|
|
|
|
|
Open a connection to the server. Returns `NULL' on failure.
|
|
|
|
|
|
|
|
|
|
The ARGS argument must be obtained using `lash_extract_args'.
|
|
|
|
|
|
|
|
|
|
The CLIENT_CLASS argument must be a string that will never change
|
|
|
|
|
over invocations of the program. If using GNU automake, the best
|
|
|
|
|
way to do this is to use the `PACKAGE_NAME' macro that is
|
|
|
|
|
automatically defined.
|
|
|
|
|
|
|
|
|
|
The CLIENT_FLAGS argument should be 0 or bitwise-OR'd values from
|
|
|
|
|
this list:
|
|
|
|
|
|
|
|
|
|
`LASH_Config_Data_Set'
|
|
|
|
|
The client wishes to save its data use the LASH config
|
|
|
|
|
system. See *Note Configs:: and *Note Event protocol::.
|
|
|
|
|
|
|
|
|
|
`LASH_Config_File'
|
|
|
|
|
The client saves its data to a file. *Note Event protocol::.
|
|
|
|
|
|
|
|
|
|
`LASH_Server_Interface'
|
|
|
|
|
The client is a server interface. *Note Server interfaces::.
|
|
|
|
|
|
|
|
|
|
`LASH_No_Autoresume'
|
|
|
|
|
This flag is set by the `--lash-no-autoresume' command line
|
|
|
|
|
option and should not normally be set by clients themselves.
|
|
|
|
|
|
|
|
|
|
`LASH_Terminal'
|
|
|
|
|
The client is dependant on being run in a terminal.
|
|
|
|
|
|
|
|
|
|
`LASH_No_Start_Server'
|
|
|
|
|
Do not attempt to start LASH server. This flag can be set by
|
|
|
|
|
the `--lash-no-start-server' command line option.
|
|
|
|
|
|
|
|
|
|
The PROTOCOL argument should be the version of the high-level
|
|
|
|
|
protocol that the client implements See *Note Protocol
|
|
|
|
|
versioning:: for information on how to contruct a `lash_protocol_t'
|
|
|
|
|
variable.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
-- Function: lash_args_t * lash_extract_args (int * ARGC, char ***
|
|
|
|
|
ARGV)
|
|
|
|
|
Extract LASH-specific arguments from argc/argv for use in
|
|
|
|
|
`lash_init'. This should be done before the client checks the
|
|
|
|
|
arguments, obviously. Returned object must be cleaned up with
|
|
|
|
|
lash_args_destroy.
|
|
|
|
|
|
|
|
|
|
-- Function: const char * lash_get_server_name (lash_client_t * CLIENT)
|
|
|
|
|
Get the hostname of the server.
|
|
|
|
|
|
|
|
|
|
-- Function: unsigned int lash_get_pending_event_count (lash_client_t
|
|
|
|
|
* CLIENT)
|
|
|
|
|
Get the number of pending events.
|
|
|
|
|
|
|
|
|
|
-- Function: lash_event_t * lash_get_event (lash_client_t * CLIENT)
|
|
|
|
|
Retrieve an event. The event must be freed using
|
|
|
|
|
`lash_event_destroy'. Returns `NULL' if there are no events
|
|
|
|
|
pending.
|
|
|
|
|
|
|
|
|
|
-- Function: unsigned int lash_get_pending_config_count (lash_client_t
|
|
|
|
|
* CLIENT)
|
|
|
|
|
Get the number of pending configs.
|
|
|
|
|
|
|
|
|
|
-- Function: lash_config_t * lash_get_config (lash_client_t * CLIENT)
|
|
|
|
|
Retrieve a config. The config must be freed using
|
|
|
|
|
`lash_config_destroy'. Returns `NULL' if there are no configs
|
|
|
|
|
pending.
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_send_event (lash_client_t * CLIENT,
|
|
|
|
|
lash_event_t * EVENT)
|
|
|
|
|
Send an event to the server. The event must be created using
|
|
|
|
|
`lash_event_new' or `lash_event_new_with_type'. The library takes
|
|
|
|
|
over ownership of the memory and it should not be freed by the
|
|
|
|
|
client.
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_send_config (lash_client_t * CLIENT,
|
|
|
|
|
lash_config_t * CONFIG)
|
|
|
|
|
Send some configuration data to the server. The config must be
|
|
|
|
|
created using `lash_config_new', `lash_config_new_with_key' or
|
|
|
|
|
`lash_config_dup'. The library takes over ownership of the memory
|
|
|
|
|
(including the key, etc) and it should not be freed by the client.
|
|
|
|
|
|
|
|
|
|
-- Macro: lash_enabled (client)
|
|
|
|
|
Check whether the lash_client_t pointer CLIENT is not `NULL', and
|
|
|
|
|
if it isn't, that the server is still connected.
|
|
|
|
|
|
|
|
|
|
-- Function: int lash_server_connected (lash_client_t * CLIENT)
|
|
|
|
|
Check whether the server is connected. Returns 1 if the server is
|
|
|
|
|
still connected or 0 if it isn't
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_jack_client_name (lash_client_t * CLIENT, const
|
|
|
|
|
char * NAME)
|
|
|
|
|
Tell the server the client's JACK client name. This is a
|
|
|
|
|
convenience function that just sends a LASH_Jack_Client_Name event
|
|
|
|
|
to the server. *Note Normal LASH_Jack_Client_Name::.
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_alsa_client_id (lash_client_t * CLIENT,
|
|
|
|
|
unsigned char ID);
|
|
|
|
|
Tell the server the client's ALSA client ID. This just is a
|
|
|
|
|
convenience function that just sends a LASH_Alsa_Client_ID event
|
|
|
|
|
to the server. *Note Normal LASH_Alsa_Client_ID::.
|
|
|
|
|
|
|
|
|
|
6.2.2 Protocol versioning
|
|
|
|
|
-------------------------
|
|
|
|
|
|
|
|
|
|
The event protocol (*Note Event protocol::,) is versioned with a major
|
|
|
|
|
and minor component. The `lash_protocol_t' type represents a version
|
|
|
|
|
number in a 32-bit unsigned integer split 16:16. A protocol is
|
|
|
|
|
comptible with the server's protocol if the major numbers are the same
|
|
|
|
|
and the minor number is less than, or equal to, the server's minor
|
|
|
|
|
number (ie, 1.0 is compatible with a server using 1.0, 1.1 is
|
|
|
|
|
compatible with a server using 1.3, but neither 2.0 or 1.6 are
|
|
|
|
|
compatible with a server using 1.4. The minor component may be dropped
|
|
|
|
|
in the future.
|
|
|
|
|
|
|
|
|
|
-- Macro: LASH_PROTOCOL (major, minor)
|
|
|
|
|
Contruct a protocol version with a major component MAJOR and a
|
|
|
|
|
minor component MINOR.
|
|
|
|
|
|
|
|
|
|
-- Macro: LASH_PROTOCOL_GET_MAJOR (protocol)
|
|
|
|
|
Obtain the major component of a `lash_protocol_t' protocol version.
|
|
|
|
|
|
|
|
|
|
-- Macro: LASH_PROTOCOL_GET_MINOR (protocol)
|
|
|
|
|
Obtain the minor component of a `lash_protocol_t' protocol version.
|
|
|
|
|
|
|
|
|
|
-- Function: const char * lash_protocol_string (lash_protocol_t
|
|
|
|
|
PROTOCOL)
|
|
|
|
|
Obtain a string representation of the protocol version PROTOCOL.
|
|
|
|
|
String representations are of the form "MAJOR.MINOR".
|
|
|
|
|
|
|
|
|
|
6.2.3 Events
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
|
|
-- Function: lash_event_t * lash_event_new (VOID)
|
|
|
|
|
|
|
|
|
|
-- Function: lash_event_t * lash_event_new_with_type (enum
|
|
|
|
|
LASH_Event_Type TYPE)
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_event_destroy (lash_event_t * EVENT)
|
|
|
|
|
|
|
|
|
|
-- Function: enum LASH_Event_Type lash_event_get_type (const
|
|
|
|
|
lash_event_t * EVENT)
|
|
|
|
|
|
|
|
|
|
-- Function: const char * lash_event_get_string (const lash_event_t *
|
|
|
|
|
EVENT)
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_event_set_type (lash_event_t * EVENT, enum
|
|
|
|
|
LASH_Event_Type TYPE)
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_event_set_string (lash_event_t * EVENT, const
|
|
|
|
|
char * STRING);
|
|
|
|
|
|
|
|
|
|
6.2.3.1 Server interface events
|
|
|
|
|
...............................
|
|
|
|
|
|
|
|
|
|
All events have a LASH ID and project name property. They are only
|
|
|
|
|
relevant to server interfaces, however, which need to refer to clients
|
|
|
|
|
other than themselves and to projects (server interfaces are never
|
|
|
|
|
assigned to a project.)
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_event_get_client_id (const lash_event_t *
|
|
|
|
|
EVENT, uuid_t ID)
|
|
|
|
|
The event's client ID property will be copied into ID.
|
|
|
|
|
|
|
|
|
|
-- Function: const char * lash_event_get_string (const lash_event_t *
|
|
|
|
|
EVENT)
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_event_set_client_id (lash_event_t * EVENT, enum
|
|
|
|
|
uuid_t ID)
|
|
|
|
|
|
|
|
|
|
-- Function: const char * lash_event_get_project (const lash_event_t *
|
|
|
|
|
EVENT)
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_event_set_project (lash_event_t * EVENT, const
|
|
|
|
|
char * PROJECT_NAME);
|
|
|
|
|
|
|
|
|
|
6.2.4 Configs
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
-- Function: lash_config_t * lash_config_new (VOID)
|
|
|
|
|
|
|
|
|
|
-- Function: lash_config_t * lash_config_dup (const lash_config_t *
|
|
|
|
|
CONFIG)
|
|
|
|
|
|
|
|
|
|
-- Function: lash_config_t * lash_config_new_with_key (const char *
|
|
|
|
|
KEY)
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_config_destroy (lash_config_t * CONFIG)
|
|
|
|
|
|
|
|
|
|
-- Function: const char * lash_config_get_key (const lash_config_t *
|
|
|
|
|
CONFIG)
|
|
|
|
|
|
|
|
|
|
-- Function: const void * lash_config_get_value (const lash_config_t *
|
|
|
|
|
CONFIG)
|
|
|
|
|
|
|
|
|
|
-- Function: size_t lash_config_get_value_size (const lash_config_t *
|
|
|
|
|
CONFIG)
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_config_set_key (lash_config_t * CONFIG, const
|
|
|
|
|
char * KEY)
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_config_set_value (lash_config_t * CONFIG, const
|
|
|
|
|
void * VALUE, size_t VALUE_SIZE)
|
|
|
|
|
|
|
|
|
|
6.2.4.1 Semi-typed configs
|
|
|
|
|
..........................
|
|
|
|
|
|
|
|
|
|
With these functions, no type checking is done; you can do
|
|
|
|
|
`lash_config_get_value_int' on a config that was set with
|
|
|
|
|
`lash_config_set_value_float'. The integer values are converted to and
|
|
|
|
|
from network byte order as appropriate.
|
|
|
|
|
|
|
|
|
|
-- Function: uint32_t lash_config_get_value_int (const lash_config_t *
|
|
|
|
|
CONFIG)
|
|
|
|
|
|
|
|
|
|
-- Function: float lash_config_get_value_float (const lash_config_t *
|
|
|
|
|
CONFIG)
|
|
|
|
|
|
|
|
|
|
-- Function: double lash_config_get_value_double (const lash_config_t
|
|
|
|
|
* CONFIG)
|
|
|
|
|
|
|
|
|
|
-- Function: const char * lash_config_get_value_string (const
|
|
|
|
|
lash_config_t * CONFIG)
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_config_set_value_int (lash_config_t * CONFIG,
|
|
|
|
|
uint32_t VALUE)
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_config_set_value_float (lash_config_t * CONFIG,
|
|
|
|
|
float VALUE)
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_config_set_value_double (lash_config_t *
|
|
|
|
|
CONFIG, double VALUE)
|
|
|
|
|
|
|
|
|
|
-- Function: void lash_config_set_value_string (lash_config_t *
|
|
|
|
|
CONFIG, const char * VALUE)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: lash-manual.info, Node: Event protocol, Next: Normal clients, Prev: Types and functions, Up: Client reference
|
|
|
|
|
|
|
|
|
|
6.3 Event protocol
|
|
|
|
|
==================
|
|
|
|
|
|
|
|
|
|
This section describes version 2.0 of the event protocol.
|
|
|
|
|
|
|
|
|
|
* Menu:
|
|
|
|
|
|
|
|
|
|
* Normal clients:: The protocol for normal LASH clients
|
|
|
|
|
* Server interfaces:: The protocol for server interfaces
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: lash-manual.info, Node: Normal clients, Next: Server interfaces, Prev: Event protocol, Up: Event protocol
|
|
|
|
|
|
|
|
|
|
6.3.1 Normal clients
|
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
|
|
This section deals with normal clients (as opposed to *Note Server
|
|
|
|
|
interfaces::.)
|
|
|
|
|
|
|
|
|
|
`LASH_Client_Name'
|
|
|
|
|
|
|
|
|
|
_To server, non-`NULL' string_
|
|
|
|
|
Set the client's user-visible name.
|
|
|
|
|
|
|
|
|
|
_To server, `NULL' string_
|
|
|
|
|
Request the client's user-visible name.
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
This will only be sent in response to a `LASH_Client_Name'
|
|
|
|
|
with a `NULL' string. The string will be `NULL' if the
|
|
|
|
|
client has not set a user-visible name, and the name itself
|
|
|
|
|
if it has.
|
|
|
|
|
|
|
|
|
|
`LASH_Jack_Client_Name'
|
|
|
|
|
|
|
|
|
|
_To server, non-`NULL' string_
|
|
|
|
|
Tell the server what name the client is connected to JACK
|
|
|
|
|
with. Clients should only ever send one non-`NULL'
|
|
|
|
|
`LASH_Jack_Client_Name' event. Note that you _must_ send
|
|
|
|
|
this event _after_ calling `jack_activate()'; otherwise, the
|
|
|
|
|
server will not be able to connect the client's ports.
|
|
|
|
|
|
|
|
|
|
_To server, `NULL' string_
|
|
|
|
|
Request the client name that the server thinks the client is
|
|
|
|
|
connected to JACK with.
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
This will only be sent in response to a
|
|
|
|
|
`LASH_Jack_Client_Name' with a `NULL' string. The string
|
|
|
|
|
will be `NULL' if the client has not set a JACK client name,
|
|
|
|
|
and the client name itself if it has.
|
|
|
|
|
|
|
|
|
|
`LASH_Alsa_Client_ID'
|
|
|
|
|
To communicate ALSA client IDs within events, use the first
|
|
|
|
|
character of a two character string of the form `{ ID, '\0' }' as
|
|
|
|
|
the event string. A convenience function, `lash_alsa_client_id',
|
|
|
|
|
exists to do this for you (see *Note lash_alsa_client_id::.)
|
|
|
|
|
|
|
|
|
|
_To server, non-`NULL' string_
|
|
|
|
|
Tell the server what ID the client is connected to ALSA with.
|
|
|
|
|
Clients should only ever send one non-`NULL'
|
|
|
|
|
`LASH_Alsa_Client_ID' event.
|
|
|
|
|
|
|
|
|
|
_To server, `NULL' string_
|
|
|
|
|
Request the client ID that the server thinks the client is
|
|
|
|
|
connected to ALSA with.
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
This will only be sent in response to a `LASH_Alsa_Client_ID'
|
|
|
|
|
with a `NULL' string. The string will be `NULL' if the
|
|
|
|
|
client has not set an ALSA client ID, and a string containing
|
|
|
|
|
the ALSA client ID as described above if it has.
|
|
|
|
|
|
|
|
|
|
`LASH_Save_File'
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
Tell the client to save all its data to files within a
|
|
|
|
|
specific directory. The event string will never be `NULL'
|
|
|
|
|
and will contain the name of the directory in which the
|
|
|
|
|
client should save its data. Clients must always send a
|
|
|
|
|
`LASH_Save_File' event back to the server when they have
|
|
|
|
|
finished saving their data. The client should not rely on
|
|
|
|
|
the directory existing after it has sent its `LASH_Save_File'
|
|
|
|
|
event back. It is valid behaviour for a client to save no
|
|
|
|
|
files within the directory. Files should always be
|
|
|
|
|
overwritten (ie, using the "w" flag with `fopen()',)
|
|
|
|
|
preferably without user confirmation if you care for their
|
|
|
|
|
sanity.
|
|
|
|
|
|
|
|
|
|
_From client_
|
|
|
|
|
Tell the server that the client has finished saving its data
|
|
|
|
|
within the directory it was told to. The string is ignored.
|
|
|
|
|
|
|
|
|
|
`LASH_Restore_File'
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
Tell the client to load all its data from files within a
|
|
|
|
|
specific directory. The event string will never be `NULL'
|
|
|
|
|
and will contain the name of the directory from which the
|
|
|
|
|
client should load its data. Clients must always send a
|
|
|
|
|
`LASH_Restore_File' event back to the server when they have
|
|
|
|
|
finished restoring their data. The client should not rely on
|
|
|
|
|
the directory existing after it has sent its
|
|
|
|
|
`LASH_Restore_File' event back.
|
|
|
|
|
|
|
|
|
|
_From client_
|
|
|
|
|
Tell the server that the client has finished restoring its
|
|
|
|
|
data from within the directory it was told to. The string is
|
|
|
|
|
ignored.
|
|
|
|
|
|
|
|
|
|
`LASH_Save_Data_Set'
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
Tell the client to send all its configuration data to the
|
|
|
|
|
server with a number of configs. The client must always send
|
|
|
|
|
a `LASH_Save_Data_Set' event back to the server when it has
|
|
|
|
|
finished sending its configs. The event string will always
|
|
|
|
|
be `NULL'.
|
|
|
|
|
|
|
|
|
|
_From client_
|
|
|
|
|
Tell the server that the client has finished sending its
|
|
|
|
|
configs to the server. The event string is ignored.
|
|
|
|
|
|
|
|
|
|
`LASH_Restore_Data_Set'
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
Tell the client to immediately expect a stream of configs
|
|
|
|
|
from the server. This event will only be sent if there are
|
|
|
|
|
one or more configs to be sent. The event string will always
|
|
|
|
|
be `NULL'. The client must always send a
|
|
|
|
|
`LASH_Restore_Data_Set' back to the server when it has
|
|
|
|
|
recieved all of its configs.
|
|
|
|
|
|
|
|
|
|
_From client_
|
|
|
|
|
Tell the server that the client has finished recieving its
|
|
|
|
|
configs from the server. The event string is ignored.
|
|
|
|
|
|
|
|
|
|
`LASH_Save'
|
|
|
|
|
|
|
|
|
|
_From client_
|
|
|
|
|
Tell the server to save the project that the client is
|
|
|
|
|
attached to.
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
Never occurs.
|
|
|
|
|
|
|
|
|
|
`LASH_Quit'
|
|
|
|
|
|
|
|
|
|
_From client_
|
|
|
|
|
Tell the server to close all clients in the project that the
|
|
|
|
|
client is attached to.
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
The client should immediately quit without saving. No more
|
|
|
|
|
events will be sent by the server and the client's connection
|
|
|
|
|
will be terminated.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: lash-manual.info, Node: Server interfaces, Next: GNU Free Documentation License, Prev: Normal clients, Up: Event protocol
|
|
|
|
|
|
|
|
|
|
6.3.2 Server interfaces
|
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
|
|
Server interfaces are treated very differently to normal interfaces.
|
|
|
|
|
Events from and to server interfaces are, for the most part, in order
|
|
|
|
|
to describe and manipulate existing projects and clients. For this
|
|
|
|
|
reason, the `lash_event_t' type has `project' and `client_id'
|
|
|
|
|
properties which facilitate this. *Note Server interface events::.
|
|
|
|
|
The `project' property contains the name of the project.
|
|
|
|
|
|
|
|
|
|
A server interface should start up with the default assumption that
|
|
|
|
|
there are no projects. Upon connection, the server will send
|
|
|
|
|
appropriate events (`LASH_Project_Add', `LASH_Client_Add',
|
|
|
|
|
`LASH_Client_Name', etc) that describe the current state of the system.
|
|
|
|
|
From then on, events will be sent to keep the interface up to date
|
|
|
|
|
with the server's state.
|
|
|
|
|
|
|
|
|
|
`LASH_Project_Add'
|
|
|
|
|
|
|
|
|
|
_From interface_
|
|
|
|
|
Restore a project from an existing directory. The event
|
|
|
|
|
string should contain the directory's name.
|
|
|
|
|
`project'
|
|
|
|
|
Ignored.
|
|
|
|
|
|
|
|
|
|
`client_id'
|
|
|
|
|
Ignored.
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
A new project has been added. The event string will contain
|
|
|
|
|
the project's name.
|
|
|
|
|
`project'
|
|
|
|
|
`NULL'
|
|
|
|
|
|
|
|
|
|
`client_id'
|
|
|
|
|
Undefined.
|
|
|
|
|
|
|
|
|
|
`LASH_Project_Remove'
|
|
|
|
|
|
|
|
|
|
_From interface_
|
|
|
|
|
Close an open project. All of the project's clients will be
|
|
|
|
|
told to quit and the project will be removed from the
|
|
|
|
|
server's project list.
|
|
|
|
|
`project'
|
|
|
|
|
The project to remove.
|
|
|
|
|
|
|
|
|
|
`client_id'
|
|
|
|
|
Ignored.
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
A project has been removed.
|
|
|
|
|
`project'
|
|
|
|
|
The project that has been removed.
|
|
|
|
|
|
|
|
|
|
`client_id'
|
|
|
|
|
Undefined.
|
|
|
|
|
|
|
|
|
|
`LASH_Project_Dir'
|
|
|
|
|
|
|
|
|
|
_From interface, non-`NULL' string_
|
|
|
|
|
Move a project to a different directory. The directory name
|
|
|
|
|
should be contained in the event's string.
|
|
|
|
|
`project'
|
|
|
|
|
The project to move.
|
|
|
|
|
|
|
|
|
|
`client_id'
|
|
|
|
|
Undefined.
|
|
|
|
|
|
|
|
|
|
_From interface, `NULL' string_
|
|
|
|
|
Request a project's directory.
|
|
|
|
|
`project'
|
|
|
|
|
The project whose directory is being requested.
|
|
|
|
|
|
|
|
|
|
`client_id'
|
|
|
|
|
Undefined.
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
A declaration of the project's directory; either because it
|
|
|
|
|
has been requested or because the project has been moved.
|
|
|
|
|
The directory name is contained in the event's string.
|
|
|
|
|
`project'
|
|
|
|
|
The project whose directory is being declared.
|
|
|
|
|
|
|
|
|
|
`client ID'
|
|
|
|
|
Undefined.
|
|
|
|
|
|
|
|
|
|
`LASH_Project_Name'
|
|
|
|
|
|
|
|
|
|
_From interface_
|
|
|
|
|
Change a project's name. The new project name should be
|
|
|
|
|
contained in the event's string.
|
|
|
|
|
`project'
|
|
|
|
|
The project name to change.
|
|
|
|
|
|
|
|
|
|
`client_id'
|
|
|
|
|
Undefined.
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
A project's name has changed. The new project name is
|
|
|
|
|
contained in the event's string.
|
|
|
|
|
`project'
|
|
|
|
|
The project name that has changed.
|
|
|
|
|
|
|
|
|
|
`client ID'
|
|
|
|
|
Undefined.
|
|
|
|
|
|
|
|
|
|
`LASH_Client_Add'
|
|
|
|
|
|
|
|
|
|
_From interface_
|
|
|
|
|
Should not occur
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
A new client has been added.
|
|
|
|
|
`project'
|
|
|
|
|
The project that the new client has been added to.
|
|
|
|
|
|
|
|
|
|
`client ID'
|
|
|
|
|
The new client's ID.
|
|
|
|
|
|
|
|
|
|
`LASH_Client_Name'
|
|
|
|
|
|
|
|
|
|
_From interface, non-`NULL' string_
|
|
|
|
|
Should not occur.
|
|
|
|
|
|
|
|
|
|
_From interface, `NULL' string_
|
|
|
|
|
Request a client's name.
|
|
|
|
|
`project'
|
|
|
|
|
The client's project.
|
|
|
|
|
|
|
|
|
|
`client ID'
|
|
|
|
|
The client's ID.
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
A declaration of a client's name; either because it has been
|
|
|
|
|
requested or because the client set the name. The name is
|
|
|
|
|
contained in the event's string.
|
|
|
|
|
`project'
|
|
|
|
|
The client's project.
|
|
|
|
|
|
|
|
|
|
`client ID'
|
|
|
|
|
The client's ID.
|
|
|
|
|
|
|
|
|
|
`LASH_Jack_Client_Name'
|
|
|
|
|
|
|
|
|
|
_From interface, non-`NULL' string_
|
|
|
|
|
Should not occur.
|
|
|
|
|
|
|
|
|
|
_From interface, `NULL' string_
|
|
|
|
|
Request a client's JACK client name.
|
|
|
|
|
`project'
|
|
|
|
|
The client's project.
|
|
|
|
|
|
|
|
|
|
`client ID'
|
|
|
|
|
The client's ID.
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
A declaration of a client's JACK client name; either because
|
|
|
|
|
it has been requested or because the client set the name.
|
|
|
|
|
The client name is contained in the event's string.
|
|
|
|
|
`project'
|
|
|
|
|
The client's project.
|
|
|
|
|
|
|
|
|
|
`client ID'
|
|
|
|
|
The client's ID.
|
|
|
|
|
|
|
|
|
|
`LASH_Alsa_Client_ID'
|
|
|
|
|
|
|
|
|
|
_From interface, non-`NULL' string_
|
|
|
|
|
Should not occur.
|
|
|
|
|
|
|
|
|
|
_From interface, `NULL' string_
|
|
|
|
|
Request a client's ALSA client ID.
|
|
|
|
|
`project'
|
|
|
|
|
The client's project.
|
|
|
|
|
|
|
|
|
|
`client ID'
|
|
|
|
|
The client's LASH ID.
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
A declaration of a client's ALSA client ID; either because it
|
|
|
|
|
has been requested or because the client set the ID. The
|
|
|
|
|
ALSA client ID is contained in the event's string, as
|
|
|
|
|
desribed in *Note Normal LASH_Alsa_Client_ID::.
|
|
|
|
|
`project'
|
|
|
|
|
The client's project.
|
|
|
|
|
|
|
|
|
|
`client ID'
|
|
|
|
|
The client's LASH ID.
|
|
|
|
|
|
|
|
|
|
`LASH_Percentage'
|
|
|
|
|
This event exists to provide user feedback on the status of save
|
|
|
|
|
operations and perhaps other operations in future. The server will
|
|
|
|
|
first send a percentage of 0, then successive percentages up to and
|
|
|
|
|
including 100. When the operation is complete, the server will
|
|
|
|
|
send a percentage of 0 again.
|
|
|
|
|
|
|
|
|
|
_From interface_
|
|
|
|
|
Should not occur.
|
|
|
|
|
|
|
|
|
|
_From server_
|
|
|
|
|
The percentage of completion of the current operation. The
|
|
|
|
|
percentage is sent as a string, derived from `sprintf'ing an
|
|
|
|
|
`int'.
|
|
|
|
|
`project'
|
|
|
|
|
The project whose operation is being described.
|
|
|
|
|
|
|
|
|
|
`client ID'
|
|
|
|
|
Undefined.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: lash-manual.info, Node: GNU Free Documentation License, Prev: Server interfaces, Up: Top
|
|
|
|
|
|
|
|
|
|
Appendix A Copying restrictions
|
|
|
|
|
*******************************
|
|
|
|
|
|
|
|
|
|
A.1 GNU Free Documentation License
|
|
|
|
|
==================================
|
|
|
|
|
|
|
|
|
|
Version 1.2, November 2002
|
|
|
|
|
|
|
|
|
|
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
|
|
|
|
|
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
|
|
|
|
|
|
|
|
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
|
|
|
of this license document, but changing it is not allowed.
|
|
|
|
|
|
|
|
|
|
0. PREAMBLE
|
|
|
|
|
|
|
|
|
|
The purpose of this License is to make a manual, textbook, or other
|
|
|
|
|
functional and useful document "free" in the sense of freedom: to
|
|
|
|
|
assure everyone the effective freedom to copy and redistribute it,
|
|
|
|
|
with or without modifying it, either commercially or
|
|
|
|
|
noncommercially. Secondarily, this License preserves for the
|
|
|
|
|
author and publisher a way to get credit for their work, while not
|
|
|
|
|
being considered responsible for modifications made by others.
|
|
|
|
|
|
|
|
|
|
This License is a kind of "copyleft", which means that derivative
|
|
|
|
|
works of the document must themselves be free in the same sense.
|
|
|
|
|
It complements the GNU General Public License, which is a copyleft
|
|
|
|
|
license designed for free software.
|
|
|
|
|
|
|
|
|
|
We have designed this License in order to use it for manuals for
|
|
|
|
|
free software, because free software needs free documentation: a
|
|
|
|
|
free program should come with manuals providing the same freedoms
|
|
|
|
|
that the software does. But this License is not limited to
|
|
|
|
|
software manuals; it can be used for any textual work, regardless
|
|
|
|
|
of subject matter or whether it is published as a printed book.
|
|
|
|
|
We recommend this License principally for works whose purpose is
|
|
|
|
|
instruction or reference.
|
|
|
|
|
|
|
|
|
|
1. APPLICABILITY AND DEFINITIONS
|
|
|
|
|
|
|
|
|
|
This License applies to any manual or other work, in any medium,
|
|
|
|
|
that contains a notice placed by the copyright holder saying it
|
|
|
|
|
can be distributed under the terms of this License. Such a notice
|
|
|
|
|
grants a world-wide, royalty-free license, unlimited in duration,
|
|
|
|
|
to use that work under the conditions stated herein. The
|
|
|
|
|
"Document", below, refers to any such manual or work. Any member
|
|
|
|
|
of the public is a licensee, and is addressed as "you". You
|
|
|
|
|
accept the license if you copy, modify or distribute the work in a
|
|
|
|
|
way requiring permission under copyright law.
|
|
|
|
|
|
|
|
|
|
A "Modified Version" of the Document means any work containing the
|
|
|
|
|
Document or a portion of it, either copied verbatim, or with
|
|
|
|
|
modifications and/or translated into another language.
|
|
|
|
|
|
|
|
|
|
A "Secondary Section" is a named appendix or a front-matter section
|
|
|
|
|
of the Document that deals exclusively with the relationship of the
|
|
|
|
|
publishers or authors of the Document to the Document's overall
|
|
|
|
|
subject (or to related matters) and contains nothing that could
|
|
|
|
|
fall directly within that overall subject. (Thus, if the Document
|
|
|
|
|
is in part a textbook of mathematics, a Secondary Section may not
|
|
|
|
|
explain any mathematics.) The relationship could be a matter of
|
|
|
|
|
historical connection with the subject or with related matters, or
|
|
|
|
|
of legal, commercial, philosophical, ethical or political position
|
|
|
|
|
regarding them.
|
|
|
|
|
|
|
|
|
|
The "Invariant Sections" are certain Secondary Sections whose
|
|
|
|
|
titles are designated, as being those of Invariant Sections, in
|
|
|
|
|
the notice that says that the Document is released under this
|
|
|
|
|
License. If a section does not fit the above definition of
|
|
|
|
|
Secondary then it is not allowed to be designated as Invariant.
|
|
|
|
|
The Document may contain zero Invariant Sections. If the Document
|
|
|
|
|
does not identify any Invariant Sections then there are none.
|
|
|
|
|
|
|
|
|
|
The "Cover Texts" are certain short passages of text that are
|
|
|
|
|
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
|
|
|
|
|
that says that the Document is released under this License. A
|
|
|
|
|
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
|
|
|
|
|
be at most 25 words.
|
|
|
|
|
|
|
|
|
|
A "Transparent" copy of the Document means a machine-readable copy,
|
|
|
|
|
represented in a format whose specification is available to the
|
|
|
|
|
general public, that is suitable for revising the document
|
|
|
|
|
straightforwardly with generic text editors or (for images
|
|
|
|
|
composed of pixels) generic paint programs or (for drawings) some
|
|
|
|
|
widely available drawing editor, and that is suitable for input to
|
|
|
|
|
text formatters or for automatic translation to a variety of
|
|
|
|
|
formats suitable for input to text formatters. A copy made in an
|
|
|
|
|
otherwise Transparent file format whose markup, or absence of
|
|
|
|
|
markup, has been arranged to thwart or discourage subsequent
|
|
|
|
|
modification by readers is not Transparent. An image format is
|
|
|
|
|
not Transparent if used for any substantial amount of text. A
|
|
|
|
|
copy that is not "Transparent" is called "Opaque".
|
|
|
|
|
|
|
|
|
|
Examples of suitable formats for Transparent copies include plain
|
|
|
|
|
ASCII without markup, Texinfo input format, LaTeX input format,
|
|
|
|
|
SGML or XML using a publicly available DTD, and
|
|
|
|
|
standard-conforming simple HTML, PostScript or PDF designed for
|
|
|
|
|
human modification. Examples of transparent image formats include
|
|
|
|
|
PNG, XCF and JPG. Opaque formats include proprietary formats that
|
|
|
|
|
can be read and edited only by proprietary word processors, SGML or
|
|
|
|
|
XML for which the DTD and/or processing tools are not generally
|
|
|
|
|
available, and the machine-generated HTML, PostScript or PDF
|
|
|
|
|
produced by some word processors for output purposes only.
|
|
|
|
|
|
|
|
|
|
The "Title Page" means, for a printed book, the title page itself,
|
|
|
|
|
plus such following pages as are needed to hold, legibly, the
|
|
|
|
|
material this License requires to appear in the title page. For
|
|
|
|
|
works in formats which do not have any title page as such, "Title
|
|
|
|
|
Page" means the text near the most prominent appearance of the
|
|
|
|
|
work's title, preceding the beginning of the body of the text.
|
|
|
|
|
|
|
|
|
|
A section "Entitled XYZ" means a named subunit of the Document
|
|
|
|
|
whose title either is precisely XYZ or contains XYZ in parentheses
|
|
|
|
|
following text that translates XYZ in another language. (Here XYZ
|
|
|
|
|
stands for a specific section name mentioned below, such as
|
|
|
|
|
"Acknowledgements", "Dedications", "Endorsements", or "History".)
|
|
|
|
|
To "Preserve the Title" of such a section when you modify the
|
|
|
|
|
Document means that it remains a section "Entitled XYZ" according
|
|
|
|
|
to this definition.
|
|
|
|
|
|
|
|
|
|
The Document may include Warranty Disclaimers next to the notice
|
|
|
|
|
which states that this License applies to the Document. These
|
|
|
|
|
Warranty Disclaimers are considered to be included by reference in
|
|
|
|
|
this License, but only as regards disclaiming warranties: any other
|
|
|
|
|
implication that these Warranty Disclaimers may have is void and
|
|
|
|
|
has no effect on the meaning of this License.
|
|
|
|
|
|
|
|
|
|
2. VERBATIM COPYING
|
|
|
|
|
|
|
|
|
|
You may copy and distribute the Document in any medium, either
|
|
|
|
|
commercially or noncommercially, provided that this License, the
|
|
|
|
|
copyright notices, and the license notice saying this License
|
|
|
|
|
applies to the Document are reproduced in all copies, and that you
|
|
|
|
|
add no other conditions whatsoever to those of this License. You
|
|
|
|
|
may not use technical measures to obstruct or control the reading
|
|
|
|
|
or further copying of the copies you make or distribute. However,
|
|
|
|
|
you may accept compensation in exchange for copies. If you
|
|
|
|
|
distribute a large enough number of copies you must also follow
|
|
|
|
|
the conditions in section 3.
|
|
|
|
|
|
|
|
|
|
You may also lend copies, under the same conditions stated above,
|
|
|
|
|
and you may publicly display copies.
|
|
|
|
|
|
|
|
|
|
3. COPYING IN QUANTITY
|
|
|
|
|
|
|
|
|
|
If you publish printed copies (or copies in media that commonly
|
|
|
|
|
have printed covers) of the Document, numbering more than 100, and
|
|
|
|
|
the Document's license notice requires Cover Texts, you must
|
|
|
|
|
enclose the copies in covers that carry, clearly and legibly, all
|
|
|
|
|
these Cover Texts: Front-Cover Texts on the front cover, and
|
|
|
|
|
Back-Cover Texts on the back cover. Both covers must also clearly
|
|
|
|
|
and legibly identify you as the publisher of these copies. The
|
|
|
|
|
front cover must present the full title with all words of the
|
|
|
|
|
title equally prominent and visible. You may add other material
|
|
|
|
|
on the covers in addition. Copying with changes limited to the
|
|
|
|
|
covers, as long as they preserve the title of the Document and
|
|
|
|
|
satisfy these conditions, can be treated as verbatim copying in
|
|
|
|
|
other respects.
|
|
|
|
|
|
|
|
|
|
If the required texts for either cover are too voluminous to fit
|
|
|
|
|
legibly, you should put the first ones listed (as many as fit
|
|
|
|
|
reasonably) on the actual cover, and continue the rest onto
|
|
|
|
|
adjacent pages.
|
|
|
|
|
|
|
|
|
|
If you publish or distribute Opaque copies of the Document
|
|
|
|
|
numbering more than 100, you must either include a
|
|
|
|
|
machine-readable Transparent copy along with each Opaque copy, or
|
|
|
|
|
state in or with each Opaque copy a computer-network location from
|
|
|
|
|
which the general network-using public has access to download
|
|
|
|
|
using public-standard network protocols a complete Transparent
|
|
|
|
|
copy of the Document, free of added material. If you use the
|
|
|
|
|
latter option, you must take reasonably prudent steps, when you
|
|
|
|
|
begin distribution of Opaque copies in quantity, to ensure that
|
|
|
|
|
this Transparent copy will remain thus accessible at the stated
|
|
|
|
|
location until at least one year after the last time you
|
|
|
|
|
distribute an Opaque copy (directly or through your agents or
|
|
|
|
|
retailers) of that edition to the public.
|
|
|
|
|
|
|
|
|
|
It is requested, but not required, that you contact the authors of
|
|
|
|
|
the Document well before redistributing any large number of
|
|
|
|
|
copies, to give them a chance to provide you with an updated
|
|
|
|
|
version of the Document.
|
|
|
|
|
|
|
|
|
|
4. MODIFICATIONS
|
|
|
|
|
|
|
|
|
|
You may copy and distribute a Modified Version of the Document
|
|
|
|
|
under the conditions of sections 2 and 3 above, provided that you
|
|
|
|
|
release the Modified Version under precisely this License, with
|
|
|
|
|
the Modified Version filling the role of the Document, thus
|
|
|
|
|
licensing distribution and modification of the Modified Version to
|
|
|
|
|
whoever possesses a copy of it. In addition, you must do these
|
|
|
|
|
things in the Modified Version:
|
|
|
|
|
|
|
|
|
|
A. Use in the Title Page (and on the covers, if any) a title
|
|
|
|
|
distinct from that of the Document, and from those of
|
|
|
|
|
previous versions (which should, if there were any, be listed
|
|
|
|
|
in the History section of the Document). You may use the
|
|
|
|
|
same title as a previous version if the original publisher of
|
|
|
|
|
that version gives permission.
|
|
|
|
|
|
|
|
|
|
B. List on the Title Page, as authors, one or more persons or
|
|
|
|
|
entities responsible for authorship of the modifications in
|
|
|
|
|
the Modified Version, together with at least five of the
|
|
|
|
|
principal authors of the Document (all of its principal
|
|
|
|
|
authors, if it has fewer than five), unless they release you
|
|
|
|
|
from this requirement.
|
|
|
|
|
|
|
|
|
|
C. State on the Title page the name of the publisher of the
|
|
|
|
|
Modified Version, as the publisher.
|
|
|
|
|
|
|
|
|
|
D. Preserve all the copyright notices of the Document.
|
|
|
|
|
|
|
|
|
|
E. Add an appropriate copyright notice for your modifications
|
|
|
|
|
adjacent to the other copyright notices.
|
|
|
|
|
|
|
|
|
|
F. Include, immediately after the copyright notices, a license
|
|
|
|
|
notice giving the public permission to use the Modified
|
|
|
|
|
Version under the terms of this License, in the form shown in
|
|
|
|
|
the Addendum below.
|
|
|
|
|
|
|
|
|
|
G. Preserve in that license notice the full lists of Invariant
|
|
|
|
|
Sections and required Cover Texts given in the Document's
|
|
|
|
|
license notice.
|
|
|
|
|
|
|
|
|
|
H. Include an unaltered copy of this License.
|
|
|
|
|
|
|
|
|
|
I. Preserve the section Entitled "History", Preserve its Title,
|
|
|
|
|
and add to it an item stating at least the title, year, new
|
|
|
|
|
authors, and publisher of the Modified Version as given on
|
|
|
|
|
the Title Page. If there is no section Entitled "History" in
|
|
|
|
|
the Document, create one stating the title, year, authors,
|
|
|
|
|
and publisher of the Document as given on its Title Page,
|
|
|
|
|
then add an item describing the Modified Version as stated in
|
|
|
|
|
the previous sentence.
|
|
|
|
|
|
|
|
|
|
J. Preserve the network location, if any, given in the Document
|
|
|
|
|
for public access to a Transparent copy of the Document, and
|
|
|
|
|
likewise the network locations given in the Document for
|
|
|
|
|
previous versions it was based on. These may be placed in
|
|
|
|
|
the "History" section. You may omit a network location for a
|
|
|
|
|
work that was published at least four years before the
|
|
|
|
|
Document itself, or if the original publisher of the version
|
|
|
|
|
it refers to gives permission.
|
|
|
|
|
|
|
|
|
|
K. For any section Entitled "Acknowledgements" or "Dedications",
|
|
|
|
|
Preserve the Title of the section, and preserve in the
|
|
|
|
|
section all the substance and tone of each of the contributor
|
|
|
|
|
acknowledgements and/or dedications given therein.
|
|
|
|
|
|
|
|
|
|
L. Preserve all the Invariant Sections of the Document,
|
|
|
|
|
unaltered in their text and in their titles. Section numbers
|
|
|
|
|
or the equivalent are not considered part of the section
|
|
|
|
|
titles.
|
|
|
|
|
|
|
|
|
|
M. Delete any section Entitled "Endorsements". Such a section
|
|
|
|
|
may not be included in the Modified Version.
|
|
|
|
|
|
|
|
|
|
N. Do not retitle any existing section to be Entitled
|
|
|
|
|
"Endorsements" or to conflict in title with any Invariant
|
|
|
|
|
Section.
|
|
|
|
|
|
|
|
|
|
O. Preserve any Warranty Disclaimers.
|
|
|
|
|
|
|
|
|
|
If the Modified Version includes new front-matter sections or
|
|
|
|
|
appendices that qualify as Secondary Sections and contain no
|
|
|
|
|
material copied from the Document, you may at your option
|
|
|
|
|
designate some or all of these sections as invariant. To do this,
|
|
|
|
|
add their titles to the list of Invariant Sections in the Modified
|
|
|
|
|
Version's license notice. These titles must be distinct from any
|
|
|
|
|
other section titles.
|
|
|
|
|
|
|
|
|
|
You may add a section Entitled "Endorsements", provided it contains
|
|
|
|
|
nothing but endorsements of your Modified Version by various
|
|
|
|
|
parties--for example, statements of peer review or that the text
|
|
|
|
|
has been approved by an organization as the authoritative
|
|
|
|
|
definition of a standard.
|
|
|
|
|
|
|
|
|
|
You may add a passage of up to five words as a Front-Cover Text,
|
|
|
|
|
and a passage of up to 25 words as a Back-Cover Text, to the end
|
|
|
|
|
of the list of Cover Texts in the Modified Version. Only one
|
|
|
|
|
passage of Front-Cover Text and one of Back-Cover Text may be
|
|
|
|
|
added by (or through arrangements made by) any one entity. If the
|
|
|
|
|
Document already includes a cover text for the same cover,
|
|
|
|
|
previously added by you or by arrangement made by the same entity
|
|
|
|
|
you are acting on behalf of, you may not add another; but you may
|
|
|
|
|
replace the old one, on explicit permission from the previous
|
|
|
|
|
publisher that added the old one.
|
|
|
|
|
|
|
|
|
|
The author(s) and publisher(s) of the Document do not by this
|
|
|
|
|
License give permission to use their names for publicity for or to
|
|
|
|
|
assert or imply endorsement of any Modified Version.
|
|
|
|
|
|
|
|
|
|
5. COMBINING DOCUMENTS
|
|
|
|
|
|
|
|
|
|
You may combine the Document with other documents released under
|
|
|
|
|
this License, under the terms defined in section 4 above for
|
|
|
|
|
modified versions, provided that you include in the combination
|
|
|
|
|
all of the Invariant Sections of all of the original documents,
|
|
|
|
|
unmodified, and list them all as Invariant Sections of your
|
|
|
|
|
combined work in its license notice, and that you preserve all
|
|
|
|
|
their Warranty Disclaimers.
|
|
|
|
|
|
|
|
|
|
The combined work need only contain one copy of this License, and
|
|
|
|
|
multiple identical Invariant Sections may be replaced with a single
|
|
|
|
|
copy. If there are multiple Invariant Sections with the same name
|
|
|
|
|
but different contents, make the title of each such section unique
|
|
|
|
|
by adding at the end of it, in parentheses, the name of the
|
|
|
|
|
original author or publisher of that section if known, or else a
|
|
|
|
|
unique number. Make the same adjustment to the section titles in
|
|
|
|
|
the list of Invariant Sections in the license notice of the
|
|
|
|
|
combined work.
|
|
|
|
|
|
|
|
|
|
In the combination, you must combine any sections Entitled
|
|
|
|
|
"History" in the various original documents, forming one section
|
|
|
|
|
Entitled "History"; likewise combine any sections Entitled
|
|
|
|
|
"Acknowledgements", and any sections Entitled "Dedications". You
|
|
|
|
|
must delete all sections Entitled "Endorsements."
|
|
|
|
|
|
|
|
|
|
6. COLLECTIONS OF DOCUMENTS
|
|
|
|
|
|
|
|
|
|
You may make a collection consisting of the Document and other
|
|
|
|
|
documents released under this License, and replace the individual
|
|
|
|
|
copies of this License in the various documents with a single copy
|
|
|
|
|
that is included in the collection, provided that you follow the
|
|
|
|
|
rules of this License for verbatim copying of each of the
|
|
|
|
|
documents in all other respects.
|
|
|
|
|
|
|
|
|
|
You may extract a single document from such a collection, and
|
|
|
|
|
distribute it individually under this License, provided you insert
|
|
|
|
|
a copy of this License into the extracted document, and follow
|
|
|
|
|
this License in all other respects regarding verbatim copying of
|
|
|
|
|
that document.
|
|
|
|
|
|
|
|
|
|
7. AGGREGATION WITH INDEPENDENT WORKS
|
|
|
|
|
|
|
|
|
|
A compilation of the Document or its derivatives with other
|
|
|
|
|
separate and independent documents or works, in or on a volume of
|
|
|
|
|
a storage or distribution medium, is called an "aggregate" if the
|
|
|
|
|
copyright resulting from the compilation is not used to limit the
|
|
|
|
|
legal rights of the compilation's users beyond what the individual
|
|
|
|
|
works permit. When the Document is included an aggregate, this
|
|
|
|
|
License does not apply to the other works in the aggregate which
|
|
|
|
|
are not themselves derivative works of the Document.
|
|
|
|
|
|
|
|
|
|
If the Cover Text requirement of section 3 is applicable to these
|
|
|
|
|
copies of the Document, then if the Document is less than one half
|
|
|
|
|
of the entire aggregate, the Document's Cover Texts may be placed
|
|
|
|
|
on covers that bracket the Document within the aggregate, or the
|
|
|
|
|
electronic equivalent of covers if the Document is in electronic
|
|
|
|
|
form. Otherwise they must appear on printed covers that bracket
|
|
|
|
|
the whole aggregate.
|
|
|
|
|
|
|
|
|
|
8. TRANSLATION
|
|
|
|
|
|
|
|
|
|
Translation is considered a kind of modification, so you may
|
|
|
|
|
distribute translations of the Document under the terms of section
|
|
|
|
|
4. Replacing Invariant Sections with translations requires special
|
|
|
|
|
permission from their copyright holders, but you may include
|
|
|
|
|
translations of some or all Invariant Sections in addition to the
|
|
|
|
|
original versions of these Invariant Sections. You may include a
|
|
|
|
|
translation of this License, and all the license notices in the
|
|
|
|
|
Document, and any Warrany Disclaimers, provided that you also
|
|
|
|
|
include the original English version of this License and the
|
|
|
|
|
original versions of those notices and disclaimers. In case of a
|
|
|
|
|
disagreement between the translation and the original version of
|
|
|
|
|
this License or a notice or disclaimer, the original version will
|
|
|
|
|
prevail.
|
|
|
|
|
|
|
|
|
|
If a section in the Document is Entitled "Acknowledgements",
|
|
|
|
|
"Dedications", or "History", the requirement (section 4) to
|
|
|
|
|
Preserve its Title (section 1) will typically require changing the
|
|
|
|
|
actual title.
|
|
|
|
|
|
|
|
|
|
9. TERMINATION
|
|
|
|
|
|
|
|
|
|
You may not copy, modify, sublicense, or distribute the Document
|
|
|
|
|
except as expressly provided for under this License. Any other
|
|
|
|
|
attempt to copy, modify, sublicense or distribute the Document is
|
|
|
|
|
void, and will automatically terminate your rights under this
|
|
|
|
|
License. However, parties who have received copies, or rights,
|
|
|
|
|
from you under this License will not have their licenses
|
|
|
|
|
terminated so long as such parties remain in full compliance.
|
|
|
|
|
|
|
|
|
|
10. FUTURE REVISIONS OF THIS LICENSE
|
|
|
|
|
|
|
|
|
|
The Free Software Foundation may publish new, revised versions of
|
|
|
|
|
the GNU Free Documentation License from time to time. Such new
|
|
|
|
|
versions will be similar in spirit to the present version, but may
|
|
|
|
|
differ in detail to address new problems or concerns. See
|
|
|
|
|
`http://www.gnu.org/copyleft/'.
|
|
|
|
|
|
|
|
|
|
Each version of the License is given a distinguishing version
|
|
|
|
|
number. If the Document specifies that a particular numbered
|
|
|
|
|
version of this License "or any later version" applies to it, you
|
|
|
|
|
have the option of following the terms and conditions either of
|
|
|
|
|
that specified version or of any later version that has been
|
|
|
|
|
published (not as a draft) by the Free Software Foundation. If
|
|
|
|
|
the Document does not specify a version number of this License,
|
|
|
|
|
you may choose any version ever published (not as a draft) by the
|
|
|
|
|
Free Software Foundation.
|
|
|
|
|
|
|
|
|
|
A.1.1 ADDENDUM: How to use this License for your documents
|
|
|
|
|
----------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
To use this License in a document you have written, include a copy of
|
|
|
|
|
the License in the document and put the following copyright and license
|
|
|
|
|
notices just after the title page:
|
|
|
|
|
|
|
|
|
|
Copyright (C) YEAR YOUR NAME.
|
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
|
|
|
under the terms of the GNU Free Documentation License, Version 1.2
|
|
|
|
|
or any later version published by the Free Software Foundation;
|
|
|
|
|
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
|
|
|
|
|
A copy of the license is included in the section entitled ``GNU
|
|
|
|
|
Free Documentation License''.
|
|
|
|
|
|
|
|
|
|
If you have Invariant Sections, Front-Cover Texts and Back-Cover
|
|
|
|
|
Texts, replace the "with...Texts." line with this:
|
|
|
|
|
|
|
|
|
|
with the Invariant Sections being LIST THEIR TITLES, with
|
|
|
|
|
the Front-Cover Texts being LIST, and with the Back-Cover Texts
|
|
|
|
|
being LIST.
|
|
|
|
|
|
|
|
|
|
If you have Invariant Sections without Cover Texts, or some other
|
|
|
|
|
combination of the three, merge those two alternatives to suit the
|
|
|
|
|
situation.
|
|
|
|
|
|
|
|
|
|
If your document contains nontrivial examples of program code, we
|
|
|
|
|
recommend releasing these examples in parallel under your choice of
|
|
|
|
|
free software license, such as the GNU General Public License, to
|
|
|
|
|
permit their use in free software.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Tag Table:
|
|
|
|
|
Node: Top691
|
|
|
|
|
Node: Introduction1379
|
|
|
|
|
Node: Copying LASH2951
|
|
|
|
|
Node: Installation4157
|
|
|
|
|
Node: Server7871
|
|
|
|
|
Node: Server interface8023
|
|
|
|
|
Node: Client reference8359
|
|
|
|
|
Node: Operational overview8890
|
|
|
|
|
Node: Types and functions21497
|
|
|
|
|
Ref: lash_alsa_client_id25720
|
|
|
|
|
Ref: Protocol versioning26060
|
|
|
|
|
Ref: Events27235
|
|
|
|
|
Ref: Server interface events27888
|
|
|
|
|
Ref: Configs28680
|
|
|
|
|
Node: Event protocol30502
|
|
|
|
|
Node: Normal clients30851
|
|
|
|
|
Ref: Normal LASH_Jack_Client_Name31549
|
|
|
|
|
Ref: Normal LASH_Alsa_Client_ID32335
|
|
|
|
|
Node: Server interfaces36461
|
|
|
|
|
Node: GNU Free Documentation License42554
|
|
|
|
|
|
|
|
|
|
End Tag Table
|