Create an MPD connection by calling elmpd-connect. This will
return an elmpd-connection instance immediately; asynchronously,
it will be parsing the MPD greeting message, perhaps sending an initial
password, and if so requested, sending the “idle” command.
Connect to an MPD server according to kwargs, which shall be a list of keyword arguments:
:name The name by which to refer to the underlying network process; it will be modified as necessary to make it unique. If not specified, it defaults to “*elmpd-connection*”.
:host The host on which the MPD server resides; if not given, it
defaults first to the environment variable MPD_HOST, and then
to “localhost”.
:port The port on which MPD is listening. If not given, it defaults
to the environment variable MPD_PORT, then to the value 6600.
:local The path to the Unix socket on which MPD is listening. This
argument is mutually exclusive with :host & :port. This option is
preferred, so to force a TCP connection, pass this explicitly as
nil.
:password If given, the “password” command shall be issued after the initial connection is made with this parameter; this should of course only be done over an encrypted connection, such as port forwarding over SSH.
:subsystems If given, this connection will perpetually idle;
whenever a command is issued on this connection, a “noidle”
command shall be given, followed by the command. When that command
completes, the “idle” command will be re-issued specifying the
same subsystems. This argument shall be a cons cell whose car is
either the symbol 'all, the symbol representing the subsystem
of interest, or a list of symbols naming the subsystems of interest
(e.g. '(player mixer output)) and whose cdr is a callback to
be invoked when any of those subsystems change; the callback shall
take two parameters the first of which will be the
elmpd-connection which saw the state change & the second of
which will be either a single symbol or a list of symbols naming the
changed subsystems.
A few examples follow. To attempt to connect to the “default” MPD instance, say:
(elmpd-connect)
This will attempt to connect first to the Unix socket at
/var/run/mpd/socket, and failing that, to the TCP/IP socket at
(or (getenv ``MPD_HOST'') ``localhost'')
at port
(or (getenv ``MPD_PORT'') ``6600'')
To force a connection to the MPD instance on localhost at port 1234, and
to create a connection that will, in between explicit commands, idle on
subystems options, player and sticker, and invoke a function named
my-callback when any one of those subsystems changes:
(elmpd-connect :local nil :port 1234 :subsystems '((options player sticker) . #'my-callback))
The available symbols naming subsystems:
elpmd-connect returns an elmpd-connection instance,
an opaque type representing an MPD connection.
As already mentioned, the connection object will still be in the process of construction on return. The caller is free to send commands through the connection immediately; they will be queued up & sent as soon as possible.
If the MPD server is down, or the elmpd-connect arguments are
incorrect, the connection will never be made; the connection will be
stalled in the 'failed state, with any commands issued so far
stuck in its queue. Since the failure will take place asynchronously,
there is no convenient point at which to detect this; it is up to the
caller to at some point, perhaps periodically, query the connection
state, detect this & correct it.
Returns a symbol representing the process status for conn, as
defined by process-status (see process-status in Emacs Lisp)
Returns #t if conn’s connection status is 'failed,
nil else.