=head1 Section 2: The Low-Level Details of Client-Server Communication

The information in this section is generally only necessary to people who wish
to write a Moosic client in a programming language other than Python.  If you
are using Python to write a Moosic client, then you can use the classes
LocalMoosicProxy and InetMoosicProxy from the moosic_factory.py module, and
blissfully ignore most of these gory details.  However, Python programmers can
also benefit from reading this section, as it will deepen their understanding of
Moosic's inter-process communication model.

The first thing to know about writing your own Moosic client is that
communication between the client and server is done through a BSD-style socket.
Read the "socket" manual page (and related manual pages) on a Unix system if you
are unfamiliar with BSD sockets.  The socket used by Moosic belongs to the
Unix-domain protocol family (PF_UNIX or PF_LOCAL) and has a type of SOCK_STREAM.
This means that a Moosic client can only communicate with a Moosic server that
is running on the same computer as the client.  This limitation is a very
purposeful part of Moosic's design.  It has the advantage of vastly reducing the
consequences of any security flaws that Moosic might have.

If you really, really think that you need the client and the server to run on
separate hosts, then you can run moosicd with the -t option, which tells it to
listen on a TCP/IP socket instead of a Unix domain socket.  I recommend
firewalling such a port very carefully.

Regardless of which kind of socket is used by the server, XML-RPC is used as the
data protocol for requests and responses.  For an introduction to XML-RPC, see
the XML-RPC homepage L<http://www.xmlrpc.com/> and the XML-RPC HOWTO
L<http://xmlrpc-c.sourceforge.net/xmlrpc-howto/xmlrpc-howto.html>.  Python users
should note that if the XML-RPC HOWTO tells you that you need to install a
third-party library to use XML-RPC, it is assuming that you are using a Python
version earlier than 2.2.  Since version 2.2, Python has included the xmlrpclib
module in its standard library.

In summary, all you need to do to talk to a Moosic server in your own program is
to send XML-RPC requests to the appropriate address.  By default, the
appropriate address for contacting moosicd is the file named "socket" in a
directory named ".moosic" in the home directory of the user that started moosicd
(i.e. "~/.moosic/socket").  If moosicd is started with the -c option, then the
directory that contains "socket" will be the argument provided to the -c option
instead of ~/.moosic.  If moosicd is started with the -t option, then clients
will have to address it by using a (host, port) pair instead of a filename.


=head1 Section 3: Valid Moosic Server Methods

moosicd's XML-RPC server implements the introspection API mentioned on
L<http://xmlrpc-c.sourceforge.net/xmlrpc-howto/xmlrpc-howto-api-introspection.html>,
so the API presented by moosicd is essentially self-documenting.  Thus, the
information in this section has been automatically generated by querying a
running Moosic server.

The Moosic API contains the following methods: