1137 lines
42 KiB
Plaintext
1137 lines
42 KiB
Plaintext
\input texinfo
|
|
@c %**start of header
|
|
@setfilename lash-manual.info
|
|
@settitle LASH Audio Session Handler
|
|
@c %**end of header
|
|
|
|
|
|
@ifinfo
|
|
This is the LASH Audio Session Handler Reference Manual,
|
|
Edition 0.5.0, September 2005 for LASH version 0.5.
|
|
|
|
Copyright @copyright{} 2002, 2003 Robert Ham (rah@@bash.sh)
|
|
|
|
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''.
|
|
|
|
@end ifinfo
|
|
|
|
|
|
@titlepage
|
|
@title LASH Reference Manual
|
|
@subtitle Audio application session management and configuration
|
|
@subtitle Edition 0.5.0, September 2005
|
|
@subtitle Covering LASH 0.5.0
|
|
@author Bob Ham (rah@@bash.sh)
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
|
|
Copyright @copyright{} 2002, 2003 Robert Ham (rah@@bash.sh)
|
|
|
|
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''.
|
|
|
|
@end titlepage
|
|
|
|
@node Top, Introduction, ,(dir)
|
|
@comment node-name, next, previous, up
|
|
|
|
@ifinfo
|
|
|
|
This is the LASH Audio Session Handler
|
|
Reference Manual, edition 0.5.0, September 2005 for LASH version 0.5.0.
|
|
|
|
@url{http://www.nongnu.org/lash}
|
|
|
|
@end ifinfo
|
|
|
|
@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, @command{lashd}
|
|
* Server interface:: How to use the simple LASH server interface, @command{lash_control}
|
|
* Client reference:: How to program LASH clients using @code{liblash}
|
|
|
|
Appendicies
|
|
* GNU Free Documentation License:: How you can copy and distribute this document.
|
|
@end menu
|
|
|
|
@contents
|
|
|
|
|
|
@node Introduction, Copying LASH, Top, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter 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, @command{lashd},
|
|
an application library, @code{liblash}, and a command line control program,
|
|
@command{laddca_control}. 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.
|
|
|
|
@section Nomenclature
|
|
|
|
In order to describe the system, we should introduce some terminology.
|
|
First of all, the @dfn{server} is the @command{lashd} server program, an
|
|
omni-present marshaller and database for storing arbitrary application data.
|
|
The @dfn{library} is the @samp{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 @dfn{client}.
|
|
|
|
The server deals with things in terms of collections of clients, called
|
|
@dfn{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 @dfn{server interface} that allows the user to control the
|
|
server. There are two server interface included with the system, the
|
|
@command{lash_control} command-line interface, and the @command{lash_panel}
|
|
GTK interface.
|
|
|
|
|
|
|
|
|
|
@node Copying LASH, Installation, Introduction, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Copying LASH
|
|
|
|
LASH is distributed under the GNU General Public License. A copy of the
|
|
license text is provided in the file @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.
|
|
|
|
|
|
|
|
@node Installation, Server, Copying LASH, Top
|
|
@chapter Installation
|
|
|
|
This chapter describes how to get LASH installed on your system.
|
|
|
|
@section 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 @url{http://www.alsa-project.org/}.
|
|
|
|
JACK is available from @url{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
|
|
@url{http://e2fsprogs.sf.net/}.
|
|
The libxml2 library is available from @url{http://www.xmlsoft.org/}.
|
|
|
|
The LASH Control client depends on the GNU Readline library,
|
|
available from @url{ftp://ftp.gnu.org/pub/gnu/readline/}.
|
|
|
|
The LASH GTK Test Client, LASH Save Button 2, and LASH Panel all depend
|
|
on the GTK+ 2 toolkit, available from @url{ftp://ftp.gtk.org/pub/gtk/v2.0/}.
|
|
The LASH Synth client has an optional GUI which also uses the GTK+ 2 toolkit.
|
|
|
|
The LASH Save Button client depends on the GTK+ 1.2 toolkit, also
|
|
available from @url{ftp://ftp.gtk.org/pub/gtk/v1.2/}.
|
|
|
|
@section Installation
|
|
|
|
First off, you need to download the package. It is available from the
|
|
LASH webpage, @url{http://www.nongnu.org/lash}. After you have
|
|
downloaded it, unpack the tarball into a directory using @command{tar -xzf
|
|
/where/ever/you/put/lash-0.5.0.tar.gz} and change into the source directory
|
|
with @command{cd lash-0.5.0}.
|
|
|
|
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.
|
|
|
|
@subsection Configuration
|
|
To configure the package, there is a shell script named @file{configure} in the
|
|
top source directory. It is a standard GNU autoconf configure script, and
|
|
so accepts the standard GNU configuration options (such as
|
|
@option{--prefix}, @option{--datadir}, etc.) To run it type
|
|
@command{./configure} and add any options. The non-standard options that
|
|
the script recognises are described below.
|
|
Running the script with the @option{--help} option will also provide a
|
|
quick summary of the recognised options.
|
|
|
|
@subsubsection Configure script options
|
|
|
|
@table @option
|
|
@item --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. The
|
|
LASH Save Button 2 and LASH GTK Test Client both rely on GTK+ 2.
|
|
|
|
@item --disable-gtk
|
|
Prevents the configure script from checking for the presence of the
|
|
GTK+ 1.2 toolkit and disables the building of any code that relies on it.
|
|
The LASH Save Button client relies on GTK+ 1.2.
|
|
|
|
@item --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.
|
|
|
|
@item --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 @file{audio-projects}.
|
|
|
|
@item --disable-serv-inst
|
|
The LASH server and library look up port addresses for the LASH service
|
|
using standard system calls that refer to the @file{/etc/services} database.
|
|
If @file{/etc/services} does not contain a valid entry, an error will result.
|
|
By default, the installation routine will install a service entry if one does not
|
|
exist. This flag disables that action.
|
|
|
|
@end table
|
|
|
|
@subsection Building
|
|
To build the package, simply type @command{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.
|
|
|
|
@subsection Installing
|
|
To install the package, type @command{make install} in the top source
|
|
directory. By default the package installation prefix is @file{/usr/local} but
|
|
the @option{--prefix} option to the configure script will change this. The
|
|
@command{lashd} server and the clients that were built are installed in
|
|
@file{@var{prefix}/bin}. The @code{liblash} client library is installed
|
|
in @file{@var{prefix}/lib}. The C header files for the client library are
|
|
installed under @file{@var{prefix}/include}. This manual is installed under
|
|
@file{@var{prefix}/info}.
|
|
|
|
With @command{make install}, the package is installed with debugging symbols in the object
|
|
files. To save space, you can install with @command{make install-strip} to
|
|
install the object files without debugging symbols.
|
|
|
|
|
|
|
|
|
|
|
|
@node Server, Server interface, Installation, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Server
|
|
|
|
The LASH server is called @file{lashd}.
|
|
|
|
|
|
|
|
@node Server interface, Client reference, Server, Top
|
|
@chapter Server interface
|
|
|
|
For a command line interface, run the command @command{lashd_control}.
|
|
There is a @command{help} command.
|
|
|
|
For a graphical interface, run the command @command{lash_panel}.
|
|
|
|
|
|
|
|
@node Client reference, Operational overview, Server interface, Top
|
|
@chapter 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
|
|
@end menu
|
|
|
|
@node Operational overview, Types and functions, Client reference, Client reference
|
|
@section 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
|
|
@command{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 @dfn{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
|
|
@code{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 @code{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 @dfn{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 @code{uint32_t} integer due to byte-order conversions
|
|
done when sending data over the network.)
|
|
|
|
@subsection 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.
|
|
|
|
@subsubsection 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.
|
|
|
|
|
|
@subsubsection 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 @emph{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
|
|
@code{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 @dfn{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 @samp{project-1} in the directory
|
|
@file{/home/@var{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.
|
|
|
|
The client then connects up to the JACK server and, after having done this,
|
|
sends a @code{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.)
|
|
|
|
|
|
@subsubsection 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
|
|
@code{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,
|
|
@samp{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.
|
|
|
|
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
|
|
@code{LASH_Alsa_Client_Name} event. The server regards this similarly to
|
|
the other client's JACK client name.
|
|
|
|
@subsubsection Saving the project
|
|
|
|
After the user has done some work in the two clients, they want to save
|
|
their work. They click a button on one of the clients (or something similar)
|
|
and the client sends a @code{LASH_Save} event to 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
|
|
@code{LASH_Config_File} flag set,) so the server creates a
|
|
directory under the project directory for it to save in and then sends a
|
|
@code{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 @code{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 @code{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 @code{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 @code{LASH_Save_Data_Set} event
|
|
from the client, it tells the data store to write the data to
|
|
disk. The save is now complete.
|
|
|
|
@subsubsection 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
|
|
@code{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 @code{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
|
|
@option{--lash-no-autoresume} option on the client's command line.
|
|
|
|
@subsubsection 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 @command{lash_control} program. This is a text
|
|
interface command program for controlling the server. They get a command
|
|
prompt and into it type @kbd{restore
|
|
/home/@var{user}/audio-projects/project-1}. The lash_control client sends
|
|
a @code{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 @code{LASH_Restore_File} event with the string as
|
|
the directory name. The ALSA client does exactly the same, except having
|
|
its data restored through @code{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
|
|
@code{LASH_Jack_Client_Name} and @code{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.
|
|
|
|
@node Types and functions, Event protocol, Operational overview, Client reference
|
|
@section Types and functions
|
|
|
|
@subsection Server interaction
|
|
|
|
@deftypefun {lash_client_t *} lash_init (lash_args_t * @var{args}, const char * @var{client_class}, int @var{client_flags}, lash_protocol_t @var{protocol})
|
|
Open a connection to the server. Returns @code{NULL} on failure.
|
|
|
|
The @var{args} argument must be obtained using @code{lash_extract_args}.
|
|
|
|
The @var{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 @code{PACKAGE_NAME} macro that is automatically defined.
|
|
|
|
The @var{client_flags}
|
|
argument should be 0 or bitwise-OR'd values from this list:
|
|
|
|
@table @code
|
|
@item LASH_Config_Data_Set
|
|
The client wishes to save its data use the LASH config system. See @ref{Configs} and
|
|
@ref{Event protocol}.
|
|
@item LASH_Config_File
|
|
The client saves its data to a file. @xref{Event protocol}.
|
|
@item LASH_Server_Interface
|
|
The client is a server interface. @xref{Server interfaces}.
|
|
@item LASH_No_Autoresume
|
|
This flag is set by the @command{--lash-no-autoresume} command line option and
|
|
should not normally be set by clients themselves.
|
|
@item LASH_Terminal
|
|
The client is dependant on being run in a terminal.
|
|
@end table
|
|
|
|
The @var{protocol} argument should be the version of the high-level protocol that the client
|
|
implements See @ref{Protocol versioning} for information on how to contruct a @code{lash_protocol_t}
|
|
variable.
|
|
|
|
@end deftypefun
|
|
|
|
@deftypefun {lash_args_t *} lash_extract_args (int * @var{argc}, char *** @var{argv})
|
|
Extract LASH-specific arguments from argc/argv for use in @code{lash_init}. This should be done before the
|
|
client checks the arguments, obviously.
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} lash_get_server_name (lash_client_t * @var{client})
|
|
Get the hostname of the server.
|
|
@end deftypefun
|
|
|
|
@deftypefun {unsigned int} lash_get_pending_event_count (lash_client_t * @var{client})
|
|
Get the number of pending events.
|
|
@end deftypefun
|
|
|
|
@deftypefun {lash_event_t *} lash_get_event (lash_client_t * @var{client})
|
|
Retrieve an event. The event must be freed using @code{lash_event_destroy}.
|
|
Returns @code{NULL} if there are no events pending.
|
|
@end deftypefun
|
|
|
|
@deftypefun {unsigned int} lash_get_pending_config_count (lash_client_t * @var{client})
|
|
Get the number of pending configs.
|
|
@end deftypefun
|
|
|
|
@deftypefun {lash_config_t *} lash_get_config (lash_client_t * @var{client})
|
|
Retrieve a config. The config must be freed using @code{lash_config_destroy}.
|
|
Returns @code{NULL} if there are no configs pending.
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_send_event (lash_client_t * @var{client}, lash_event_t * @var{event})
|
|
Send an event to the server. The event must be created using
|
|
@code{lash_event_new} or @code{lash_event_new_with_type}. The library takes over
|
|
ownership of the memory and it should not be freed by the client.
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_send_config (lash_client_t * @var{client}, lash_config_t * @var{config})
|
|
Send some configuration data to the server. The config must be created using
|
|
@code{lash_config_new}, @code{lash_config_new_with_key} or
|
|
@code{lash_config_dup}. The library takes
|
|
over ownership of the memory and it should not be freed by the client.
|
|
@end deftypefun
|
|
|
|
@defmac lash_enabled (client)
|
|
Check whether the lash_client_t pointer @var{client} is not @code{NULL}, and if it
|
|
isn't, that the server is still connected.
|
|
@end defmac
|
|
|
|
@deftypefun int lash_server_connected (lash_client_t * @var{client})
|
|
Check whether the server is connected. Returns 1 if the server is still
|
|
connected or 0 if it isn't
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_jack_client_name (lash_client_t * @var{client}, const char * @var{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. @xref{Normal LASH_Jack_Client_Name}.
|
|
@end deftypefun
|
|
|
|
@anchor{lash_alsa_client_id}
|
|
@deftypefun void lash_alsa_client_id (lash_client_t * @var{client}, unsigned char @var{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. @xref{Normal LASH_Alsa_Client_ID}.
|
|
@end deftypefun
|
|
|
|
@subsection Protocol versioning
|
|
@anchor{Protocol versioning}
|
|
The event protocol (@xref{Event protocol},) is versioned with a major and minor component.
|
|
The @code{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.
|
|
|
|
@defmac LASH_PROTOCOL (major, minor)
|
|
Contruct a protocol version with a major component @var{major} and a minor
|
|
component @var{minor}.
|
|
@end defmac
|
|
|
|
@defmac LASH_PROTOCOL_GET_MAJOR (protocol)
|
|
Obtain the major component of a @code{lash_protocol_t} protocol version.
|
|
@end defmac
|
|
|
|
@defmac LASH_PROTOCOL_GET_MINOR (protocol)
|
|
Obtain the minor component of a @code{lash_protocol_t} protocol version.
|
|
@end defmac
|
|
|
|
@deftypefun const char * lash_protocol_string (lash_protocol_t @var{protocol})
|
|
Obtain a string representation of the protocol version @var{protocol}.
|
|
String representations are of the form ``@var{major}.@var{minor}''.
|
|
@end deftypefun
|
|
|
|
@subsection Events
|
|
@anchor{Events}
|
|
|
|
@deftypefun {lash_event_t *} lash_event_new (@var{void})
|
|
@end deftypefun
|
|
|
|
@deftypefun {lash_event_t *} lash_event_new_with_type (enum LASH_Event_Type @var{type})
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_event_destroy (lash_event_t * @var{event})
|
|
@end deftypefun
|
|
|
|
@deftypefun {enum LASH_Event_Type} lash_event_get_type (const lash_event_t * @var{event})
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} lash_event_get_string (const lash_event_t * @var{event})
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_event_set_type (lash_event_t * @var{event}, enum LASH_Event_Type @var{type})
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_event_set_string (lash_event_t * @var{event}, const char * @var{string});
|
|
@end deftypefun
|
|
|
|
@subsubsection Server interface events
|
|
@anchor{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.)
|
|
|
|
|
|
@deftypefun {void} lash_event_get_client_id (const lash_event_t * @var{event}, uuid_t @var{id})
|
|
The event's client ID property will be copied into @var{id}.
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} lash_event_get_string (const lash_event_t * @var{event})
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_event_set_client_id (lash_event_t * @var{event}, enum uuid_t @var{id})
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} lash_event_get_project (const lash_event_t * @var{event})
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_event_set_project (lash_event_t * @var{event}, const char * @var{project_name});
|
|
@end deftypefun
|
|
|
|
|
|
@subsection Configs
|
|
@anchor{Configs}
|
|
|
|
@deftypefun {lash_config_t *} lash_config_new (@var{void})
|
|
@end deftypefun
|
|
|
|
@deftypefun {lash_config_t *} lash_config_dup (const lash_config_t * @var{config})
|
|
@end deftypefun
|
|
|
|
@deftypefun {lash_config_t *} lash_config_new_with_key (const char * @var{key})
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_config_destroy (lash_config_t * @var{config})
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} lash_config_get_key (const lash_config_t * @var{config})
|
|
@end deftypefun
|
|
|
|
@deftypefun {const void *} lash_config_get_value (const lash_config_t * @var{config})
|
|
@end deftypefun
|
|
|
|
@deftypefun size_t lash_config_get_value_size (const lash_config_t * @var{config})
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_config_set_key (lash_config_t * @var{config}, const char * @var{key})
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_config_set_value (lash_config_t * @var{config}, const void * @var{value}, size_t @var{value_size})
|
|
@end deftypefun
|
|
|
|
@subsubsection Semi-typed configs
|
|
With these functions, no type checking is done; you can do
|
|
@code{lash_config_get_value_int} on a config that was set with
|
|
@code{lash_config_set_value_float}. The integer values are converted
|
|
to and from network byte order as appropriate.
|
|
|
|
@deftypefun uint32_t lash_config_get_value_int (const lash_config_t * @var{config})
|
|
@end deftypefun
|
|
|
|
@deftypefun float lash_config_get_value_float (const lash_config_t * @var{config})
|
|
@end deftypefun
|
|
|
|
@deftypefun double lash_config_get_value_double (const lash_config_t * @var{config})
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} lash_config_get_value_string (const lash_config_t * @var{config})
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_config_set_value_int (lash_config_t * @var{config}, uint32_t @var{value})
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_config_set_value_float (lash_config_t * @var{config}, float @var{value})
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_config_set_value_double (lash_config_t * @var{config}, double @var{value})
|
|
@end deftypefun
|
|
|
|
@deftypefun void lash_config_set_value_string (lash_config_t * @var{config}, const char * @var{value})
|
|
@end deftypefun
|
|
|
|
|
|
@node Event protocol, Normal clients, Types and functions, Client reference
|
|
@section 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
|
|
@end menu
|
|
|
|
|
|
@node Normal clients, Server interfaces, Event protocol, Event protocol
|
|
@subsection Normal clients
|
|
|
|
This section deals with normal clients (as opposed to @ref{Server interfaces}.)
|
|
|
|
@table @code
|
|
@item LASH_Client_Name
|
|
@table @emph
|
|
@item To server, non-@code{NULL} string
|
|
Set the client's user-visible name.
|
|
@item To server, @code{NULL} string
|
|
Request the client's user-visible name.
|
|
@item From server
|
|
This will only be sent in response to a @code{LASH_Client_Name} with a
|
|
@code{NULL} string. The string will be @code{NULL} if the client has not
|
|
set a user-visible name, and the name itself if it has.
|
|
@end table
|
|
|
|
@item LASH_Jack_Client_Name
|
|
@anchor{Normal LASH_Jack_Client_Name}
|
|
@table @emph
|
|
@item To server, non-@code{NULL} string
|
|
Tell the server what name the client is connected to JACK with.
|
|
Clients should only ever send one non-@code{NULL} @code{LASH_Jack_Client_Name}
|
|
event. Note that you @emph{must} send this event @emph{after} calling
|
|
@code{jack_activate()}; otherwise, the server will not be able to connect
|
|
the client's ports.
|
|
|
|
@item To server, @code{NULL} string
|
|
Request the client name that the server thinks the client is connected to
|
|
JACK with.
|
|
@item From server
|
|
This will only be sent in response to a @code{LASH_Jack_Client_Name} with a
|
|
@code{NULL} string. The string will be @code{NULL} if the client has not
|
|
set a JACK client name, and the client name itself if it has.
|
|
@end table
|
|
|
|
@item LASH_Alsa_Client_ID
|
|
@anchor{Normal LASH_Alsa_Client_ID}
|
|
To communicate ALSA client IDs within events, use the first character
|
|
of a two character string of the form @code{@{ @var{id}, '\0' @}} as the
|
|
event string. A
|
|
convenience function, @code{lash_alsa_client_id}, exists to do this for you
|
|
(see @ref{lash_alsa_client_id}.)
|
|
|
|
@table @emph
|
|
@item To server, non-@code{NULL} string
|
|
Tell the server what ID the client is connected to ALSA with.
|
|
Clients should only ever send one non-@code{NULL} @code{LASH_Alsa_Client_ID}
|
|
event.
|
|
|
|
@item To server, @code{NULL} string
|
|
Request the client ID that the server thinks the client is connected to
|
|
ALSA with.
|
|
@item From server
|
|
This will only be sent in response to a @code{LASH_Alsa_Client_ID} with a
|
|
@code{NULL} string. The string will be @code{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.
|
|
@end table
|
|
|
|
@item LASH_Save_File
|
|
@table @emph
|
|
@item From server
|
|
Tell the client to save all its data to files within a specific directory.
|
|
The event string will never be @code{NULL} and will contain the name of the
|
|
directory in which the client should save its data. Clients must always
|
|
send a @code{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 @code{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 @code{fopen()},) preferably without user confirmation if you care
|
|
for their sanity.
|
|
@item From client
|
|
Tell the server that the client has finished saving its data within the
|
|
directory it was told to. The string is ignored.
|
|
@end table
|
|
|
|
@item LASH_Restore_File
|
|
@table @emph
|
|
@item From server
|
|
Tell the client to load all its data from files within a specific directory.
|
|
The event string will never be @code{NULL} and will contain the name of the
|
|
directory from which the client should load its data. Clients must always
|
|
send a @code{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 @code{LASH_Restore_File}
|
|
event back.
|
|
@item 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.
|
|
@end table
|
|
|
|
|
|
@item LASH_Save_Data_Set
|
|
@table @emph
|
|
@item 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 @code{LASH_Save_Data_Set}
|
|
event back to the server when it has finished sending its configs. The
|
|
event string will always be @code{NULL}.
|
|
@item From client
|
|
Tell the server that the client has finished sending its configs to the
|
|
server. The event string is ignored.
|
|
@end table
|
|
|
|
@item LASH_Restore_Data_Set
|
|
@table @emph
|
|
@item 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 @code{NULL}. The client must always send
|
|
a @code{LASH_Restore_Data_Set} back to the server when it has recieved
|
|
all of its configs.
|
|
@item From client
|
|
Tell the server that the client has finished recieving its configs from the
|
|
server. The event string is ignored.
|
|
@end table
|
|
|
|
@item LASH_Save
|
|
@table @emph
|
|
@item From client
|
|
Tell the server to save the project that the client is attached to.
|
|
@item From server
|
|
Never occurs.
|
|
@end table
|
|
|
|
@item LASH_Quit
|
|
@table @emph
|
|
@item From client
|
|
Tell the server to close all clients in the project that the client is attached to.
|
|
@item 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.
|
|
@end table
|
|
@end table
|
|
|
|
|
|
@node Server interfaces, GNU Free Documentation License, Normal clients, Event protocol
|
|
@subsection 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 @code{lash_event_t} type has
|
|
@code{project} and @code{client_id} properties which facilitate this. @xref{Server interface
|
|
events}. The @code{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 (@code{LASH_Project_Add},
|
|
@code{LASH_Client_Add}, @code{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.
|
|
|
|
@table @code
|
|
|
|
@c ***
|
|
@c *** LASH_Project_Add
|
|
@c ***
|
|
|
|
@item LASH_Project_Add
|
|
@table @emph
|
|
|
|
@item From interface
|
|
Restore a project from an existing directory. The event string should contain the
|
|
directory's name.
|
|
@table @code
|
|
@item project
|
|
Ignored.
|
|
@item client_id
|
|
Ignored.
|
|
@end table
|
|
|
|
@item From server
|
|
A new project has been added. The event string will contain the project's name.
|
|
@table @code
|
|
@item project
|
|
@code{NULL}
|
|
@item client_id
|
|
Undefined.
|
|
@end table
|
|
@end table
|
|
|
|
|
|
@c ***
|
|
@c *** LASH_Project_Remove
|
|
@c ***
|
|
|
|
@item LASH_Project_Remove
|
|
@table @emph
|
|
|
|
@item 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.
|
|
@table @code
|
|
@item project
|
|
The project to remove.
|
|
@item client_id
|
|
Ignored.
|
|
@end table
|
|
|
|
@item From server
|
|
A project has been removed.
|
|
@table @code
|
|
@item project
|
|
The project that has been removed.
|
|
@item client_id
|
|
Undefined.
|
|
@end table
|
|
@end table
|
|
|
|
|
|
@c ***
|
|
@c *** LASH_Project_Dir
|
|
@c ***
|
|
|
|
@item LASH_Project_Dir
|
|
@table @emph
|
|
@item From interface, non-@code{NULL} string
|
|
Move a project to a different directory. The directory name should be contained in
|
|
the event's string.
|
|
@table @code
|
|
@item project
|
|
The project to move.
|
|
@item client_id
|
|
Undefined.
|
|
@end table
|
|
|
|
@item From interface, @code{NULL} string
|
|
Request a project's directory.
|
|
@table @code
|
|
@item project
|
|
The project whose directory is being requested.
|
|
@item client_id
|
|
Undefined.
|
|
@end table
|
|
|
|
@item 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.
|
|
@table @code
|
|
@item project
|
|
The project whose directory is being declared.
|
|
@item client ID
|
|
Undefined.
|
|
@end table
|
|
@end table
|
|
|
|
@c ***
|
|
@c *** LASH_Project_Name
|
|
@c ***
|
|
|
|
@item LASH_Project_Name
|
|
@table @emph
|
|
@item From interface
|
|
Change a project's name. The new project name should be contained in the
|
|
event's string.
|
|
@table @code
|
|
@item project
|
|
The project name to change.
|
|
@item client_id
|
|
Undefined.
|
|
@end table
|
|
|
|
@item From server
|
|
A project's name has changed. The new project name is contained in the event's
|
|
string.
|
|
@table @code
|
|
@item project
|
|
The project name that has changed.
|
|
@item client ID
|
|
Undefined.
|
|
@end table
|
|
@end table
|
|
|
|
@c ***
|
|
@c *** LASH_Client_Add
|
|
@c ***
|
|
|
|
@item LASH_Client_Add
|
|
@table @emph
|
|
@item From interface
|
|
Should not occur
|
|
|
|
@item From server
|
|
A new client has been added.
|
|
@table @code
|
|
@item project
|
|
The project that the new client has been added to.
|
|
@item client ID
|
|
The new client's ID.
|
|
@end table
|
|
@end table
|
|
|
|
|
|
@c ***
|
|
@c *** LASH_Client_Name
|
|
@c ***
|
|
|
|
@item LASH_Client_Name
|
|
@table @emph
|
|
@item From interface, non-@code{NULL} string
|
|
Should not occur.
|
|
|
|
@item From interface, @code{NULL} string
|
|
Request a client's name.
|
|
@table @code
|
|
@item project
|
|
The client's project.
|
|
@item client ID
|
|
The client's ID.
|
|
@end table
|
|
|
|
@item 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.
|
|
@table @code
|
|
@item project
|
|
The client's project.
|
|
@item client ID
|
|
The client's ID.
|
|
@end table
|
|
@end table
|
|
|
|
|
|
@c ***
|
|
@c *** LASH_Jack_Client_Name
|
|
@c ***
|
|
|
|
@item LASH_Jack_Client_Name
|
|
@table @emph
|
|
@item From interface, non-@code{NULL} string
|
|
Should not occur.
|
|
|
|
@item From interface, @code{NULL} string
|
|
Request a client's JACK client name.
|
|
@table @code
|
|
@item project
|
|
The client's project.
|
|
@item client ID
|
|
The client's ID.
|
|
@end table
|
|
|
|
@item 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.
|
|
@table @code
|
|
@item project
|
|
The client's project.
|
|
@item client ID
|
|
The client's ID.
|
|
@end table
|
|
@end table
|
|
|
|
|
|
@c ***
|
|
@c *** LASH_Alsa_Client_ID
|
|
@c ***
|
|
|
|
@item LASH_Alsa_Client_ID
|
|
@table @emph
|
|
@item From interface, non-@code{NULL} string
|
|
Should not occur.
|
|
|
|
@item From interface, @code{NULL} string
|
|
Request a client's ALSA client ID.
|
|
@table @code
|
|
@item project
|
|
The client's project.
|
|
@item client ID
|
|
The client's LASH ID.
|
|
@end table
|
|
|
|
@item 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 @ref{Normal LASH_Alsa_Client_ID}.
|
|
@table @code
|
|
@item project
|
|
The client's project.
|
|
@item client ID
|
|
The client's LASH ID.
|
|
@end table
|
|
@end table
|
|
|
|
|
|
@c ***
|
|
@c *** LASH_Percentage
|
|
@c ***
|
|
|
|
@item 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.
|
|
|
|
@table @emph
|
|
@item From interface
|
|
Should not occur.
|
|
|
|
@item From server
|
|
The percentage of completion of the current operation. The percentage
|
|
is sent as a string, derived from @code{sprintf}ing an @code{int}.
|
|
@table @code
|
|
@item project
|
|
The project whose operation is being described.
|
|
@item client ID
|
|
Undefined.
|
|
@end table
|
|
@end table
|
|
|
|
@end table
|
|
|
|
@node GNU Free Documentation License, , Server interfaces, Top
|
|
@appendix Copying restrictions
|
|
@include fdl.texi
|
|
|
|
@bye
|