BASICS
------
all irmp3 modules are able to communicate to each other using the
message queues. you receive messages on the message function of your
module, and you can send messages using either mod_sendmsg or
mod_sendmsgf. these messages are added to a message queue, and will be
sent to ALL modules when possible. modules should not make any
assumption on delivery order or timing, and as little as possible on
other modules being available.



RECEIVING MESSAGES
------------------
modules receive messages via the message callback of their message
structure. the message callback has the following type:

void mod_xxxx_messages (int messagetype, char* message)

the messagetype parameter specifies the queue on which the message was
posted, the message parameter points to the message itself. The
message parameter is a private copy of the message, and you can change
it as much as you like (using strtok on it is ok) you don't need to
free it, the irmp3d main loop will do that for you. However, if you
need to keep the message you have to copy it, since your private copy
will be freed once the message function has returned.



SENDING MESSAGES
----------------
to send messages you can use the two following functions, defined in
irmp3mod.h

void mod_sendmsg(int msgtype, char* message)
void mod_sendmsgf(int msgtype, char* message,...)

the messagetype specifies on which message queue the message should be
posted.
the message is the message itself.
the mod_semdmsgf accepts a variable argument  la printf.



THE MESSAGE QUEUES
------------------

when a module receive a message it should always check first for the
messagetype. messages types are defined as MSGTYPE_XXX in irmp3mod.h
these are NOT flags and shall NOT be ored.


THE MSGTYPE_INPUT QUEUE
-----------------------

this queue is used to echo all user requests comming from the
different input modules. there is no special protocol on this queue,
and all answered messages shall be documented in src/irmp3d/irmp3d.7
modules should be particularly cautious when listening to this types
of messages. They come directly from the user with no particular
syntax checking.

THE MSGTYPE_PLAYER QUEUE
------------------------

this queue allows synchronisation of the different players and
playlist. There is a strict protocol on this queue and only the active
player shall write to it. Other players shall listen to know when they
become active. Other modules can listen to detect player events (which
are not mirrored on the MSGTYPE_EVENT queue) but shall never post to
this queue. The complete protocol is documented in the player.txt
documentation file, which explains how to write a player module.

THE MSGTYPE_EVENT QUEUE
-----------------------

If your module has states, or detects particular events, it should
post a warining on this queue. All events that can appear on this
queue are documented in src/irmp3d/irmp3d.7 Modules should listen to
other  modules event on this queue.


QUERIES ANS ANSWERS, THE MSGTYPE_QUERY and MSGTYPE_INFO QUEUES
--------------------------------------------------------------
from time to time, a module needs to ask a question to another
module, and it might need the answer immediatly. To do such things,
modules should use the mod_query function

	mod_message_t *mod_query(int msgtype, char* msg);
	mod_message_t *mod_queryf(int msgtype, char* msg,...);

these functions will post a message to all modules immediatly,
bypassing the normal message queue. they should be used with caution.
The returned type is a linked list of messagess from the different
modules.

You will normaly use this function with the MSGTYPE_QUERY type which
is dedicated to posting questions, but nothing prevents you from using
another queue, if you want to execute an order immediatly. (again, use
with caution)

An interesting use of query is to ensure the chronology of actions.
Because queries force all modules to act immediatly, it's the only way
to ensure an action is taken before you go on with your code


The list of answers is the list of all answers posted by all modules
in reply to that query (including other queries, but excluding the
answers to these queries). You are responsible for freeing this list
using the free_answer function (which can safely be used on an empty list)

you should usually check the msgtype and if needed the first word of
the answer since any message could come in the answer.

If you are not interested by the answer to a question, and if
executing the order immediatly isn't important, you can post on the MSGTYPE_QUERY
queue the normal way. All answers to all queries are posted to
MSGTYPE_INFO for other modules to monitor.

Note that it is safe to ask a query from within a query (except for
the usual problem of infinite recursion)

