1555 lines
64 KiB
Plaintext
1555 lines
64 KiB
Plaintext
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).
|
||
|
||
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.
|
||
|
||
Starting the server can also be disabled by specifying the
|
||
`--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
|
||
know, you probably are) you can disable auto-start with the following
|
||
command:
|
||
|
||
`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.
|
||
|
||
|
||
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
|