
* 7. Messaging API:
~~~~~~~~~~~~~~~~~~~

This document covers the messaging API used by AMPlay and AMPlayCfg. It
could be used by other applications to control AMPlay. If you aren't a
programmer, this section probably isn't of much interest to you. Indeed,
the AMPlayCfg stuff is only likely to be useful if you feel like
playing with the AMPlay source itself.

The source download for AMPlay includes a sample app for communicating
with AMPlay using the API. The AMPlayCmd utility included with AMPlay
is also a useful source of example code. 

These are all user messages (type 17). AMPlay's officially registered
message block is &563C0 - &563FF.

All strings referred to are CR terminated.


* 7.1 AMPlay_Command (&563C0):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+20 flags
+24 Command
+28 parameter 1
+32 parameter 2
+36 parameter 3

AMPlay_command is for immediate commands that will affect the state of
the player. Normally, an AMPlay_Ack is returned to the sending task,
to indicate success or failure (and why it failed). Optionally, it can
write a file into PipeFS with the result (see reply by file, below).

The parameters may be optional, depending on the command used.

The parameters may contain strings or integers, again depending on the
command used. The command is always a string.


Flags:

Flags are sent at +20 in the message block.

Bit:   Meaning if set:
0:     Don't bother replying.
1:     Reply by file instead of by message
       see below for more details of reply by file.
8:     v2xx format understood. MUST BE SET.

other bits should be zero.

Bit 8 must be set in the flags in order for the message to be processed
further by AMPlay.

The reason for this is that v1.5x of AMPlay used a different mechanism
here (the flags and command number were combined in a single word). Any
1.5x message that AMPlay 2.x receives will not have bit 8 set, and
AMPlay will reply with a not supported error code using the 1.5x reply
format (which also differs from how 2.x would normally reply).

This avoids 1.5x command potentially being executed with different
meanings by 2.x

The AMPlay_ack returned will indicate success/failure only. This is
because commands are telling AMPlay to do something, rather than asking
it for particular information. For that, see AMPlay_request


Commands:

The command is sent at +24 in the message block.

A command consists of a string of up to three characters, CR terminated
(so that it occupies 4 bytes at most).

Commands are not case sensitive, and are hardcoded - i.e. they are not
fetched from the messages file, and therefore are not language
dependant.

Recognised commands

Command     Meaning                                  Parameters.
                                                     
PLA         Play                                     1
PAU         Pause                                    1
STP         Stop                                     No
REW         Rewind                                   1
FWD         Forward                                  1
PRE         Previous                                 1
NXT         Next                                     1
AUT         Autonext                                 1
VUP         Volume Up                                2
VDN         Volume Dn                                2
VST         Volume Set                               2

RPT         Repeat item                              1
RST         Restart Track                            1
PTR         Previous Track                           1
NTR         Next Track                               1
PAL         Previous Album                           1
NAL         Next Album                               1
PAR         Previous Artist                          1
NAR         Next Artist                              1
                                                    
ORD         Change playback order                    2

STF         Set exclusive filter                     2
MDF         Modify single filter                     3
SAF         Set absolute filter                      2
                                                     
LD          Pass file/dir to be loaded               1
STA         Save state                               No
CLR         Clear history                            No
REF         Refresh                                  1
SRT         Sort                                     No
DIE         Quit                                     1

PAI         Play any item                            3
QAI         Queue any item                           3
FAI         Alter filter status of any item          4
WAI         Alter random weighting of any item       3
LAI         Alter link status of any item            3
UAI         Alter ignore unique for any item         3
AVT         Alter relative volume of any track       3
RTA         Refresh time on any item                 2
RDB         Remove any item from the database        2
RHT         Remove any item from the track history   2
SWP         Swap adjacent items                      2

OPT         Save options file                        1
SPL         Save playlist                            1

TST         Testing                                  No

Command details;

PLA, PAU, STP, REW, FWD, PRE, NXT, AUT:

These correspond to the main window buttons. Default behaviour is the
same as a select click on the corresponding button.

STP takes no further paramters.

PAU and LOP take a further parameter in +28. This must be one of;

OFF
ON
TOG

And indicate what to do - e.g. to pause, unpause, or toggle the
existing state, whatever it may be.

PLA, REW, FWD, PRE, NXT take a further parameter in +28. This must be
one of;

NRM
MOD

This indicates whether to take the normal or the modified action.
Modified in the case means adjust-click behaviour. For REW and FWD,
normal behaviour is to move in units of 10% of the current track
length. Modified behaviour is to move in units of 1% of the track
length, for fine tuning.

For PLA, PRE and NXT, again NRM refers to the select click action,
while MOD specifies the adjust click behaviour.

AUT is a special case as it has three possible states. It requires a
parameter in +28 which must be one of;

ALW
NVR
INH
CYL
CYR

These mean Always, Never, In history, cycle left, and cycle right.


VUP, VDN, VST:

Parameter 1 must be one of
BAS
REL

Indicating whether it is the base volume or the relative track volume
you wish to edit.

For VUP, VDN, parameter 2 must be NRM or MOD, as above. NRM modifies
the volume in multiples of volumeincrement. MOD modifies the volume at
double the normal rate.

For VST, parameter 2 is an integer containing the new volume. The range
varies depending on whether it is a base or relative volume being
passed. Base volumes must be 0>127, while relative volumes must be in
the range -63>+63.


RPT:

Paramater 1 must be one of

ON
OFF
TRK
ALB
ART
CYL
CYR

ON enables repeat at the current selection level. The others either
disable repeat, or enable it at the specified selection level. CYL and
CYR cycle through the options in the same way that clicks on the main
window icon do.


RST, PTR, NTR, PAL, NAL, PAR, NAR:

These all take NRM or MOD as their parameter 1.

RST means restart track, and currently has no corresponding main window
button (although it is a playonplay option, and and adjust-click action
for the play button). NRM for it means just to rewind to position 0,
and make no other changes. MOD tells it to do that, but also to unpause
the track if it was paused.

The others listed here correspond to the previous and next buttons that
are associated with the track, album and artist rows on the main window
(as distinct from the row of buttons at the base of the window). NRM
refers to the normal select click action (move within history if
possible). MOD refers to the adjust-click behaviour of moving within
the database instead.


ORD:

This takes a string in its parameter 1, which indicates which
playback order you wish to change. This must be one of;

CHA
TRK
ALB
ART

CHA turns chaos mode on, and takes no further parameters. The others
then take a further string in parameter 2. This must be one of;

LIN
RND
IGN

If parameter 1 is TRK, then IGN is not allowed in parameter 2. This is
because while albums and artist can have a playback order of ignore,
tracks always have to be either linear or random.
To turn chaos mode off, just set the playback order to one of the other
states.


STF, MDF, SAF:

These are all methods for altering which filters are currently
available, or active.

They all take the same parameter 1 - a string which must be one of;

ACT
AVL

and indicates whether it is the available filter set or the active
filter set that we wish to modify.

STF takes an integer in parameter 2. This integer must be a number from
1 to 20 (inclusive). The corresponding filter will be activated or made
available (depending on parameter 1), and all the others turned off.

MDF is similar to STF - if takes an integer in parameter 2, indicating
which filter is to be operated on. Parameter 3 then indicates what is
to be done to it, using the ON, OFF, TOG mechanism described above.

SAF takes an integer in parameter 2. This integer is a bit mask, where
bits 0-19 correspond to filters 1-20 (other bits should be 0). This
specifies the new state of the active or available filters word within
AMPlay. At least one bit must be set.


Notes:

MDF and STF differ in that STF affects all filters - it turns a
specified one on, and everything else off. MDF allows you to turn
particular filters on or off without affecting the state of the others.

Similarly, SAF affects all filters. There is currently no equivalent of
SAF that allows multiple filters to be altered.

Any attempt to activate a filter that is not in the available filters
list will result in a 'disabled' error being returned. Some operations
may therefore require several calls - an AMPlay_Request call to read the
current status, a call to make a specified filter available, and then
one to activate it.

Changes to the available filter that remove an active filter are
allowed, as long as at least one filter is left active. e.g. if filters
1,2 and 3 are available, and filters 1 and 2 are active, then a call to
make filter2 the only available filter will succeed, and implicitly
inactivate filter 1. If filter 1 was not active in the first place, the
operation would fail with a 'disabled' error.


LD:

This takes no parameter 1 or parameter 2, but does take a parameter 3.
This isn't as weird as it sounds because parameters 1 and 2 are limited
to 4 bytes, whereas parameter 3 is limited only by the overall size of
the message block (around 200 bytes in practice).

Parameter 3 contains the filespec or dirspec. AMPlay then responds as
if the specified item had just been dragged onto it. It can contain
variables, but it must resolve to a single object (i.e. mp3$dir is
fine, mp3$path might cause undefined behaviour.)


STA, CLR, SRT:

These take no further parameters.


REF:

This takes parameter 1 only. This must be one of;

TIM
BND
NAM

These indicate Time, Boundaries and Names, and correspond to the menu
options with the same function.


DIE:

This takes parameter 1 only. This must be one of;

NRM
MOD

This indicates whether to save state on exit (NRM) or not (MOD).


PAI, QAI, FAI, WAI, LAI, UAI, AVT, RTA, RDB, RHT, SWP:

These all take the same infomation in parameter 1;

TRK
ALB
ART

This indicates whether the item is a track, album or artist.

Parameter 2 then specifies which track, album or artist. This is an
integer, and provides the number in the AMPlay database of the item in
question. Use -1 to specify the current track, album or artist (if
any - an error will be returned if there is no track playing)

Parameter 3 then provides any details needed.

PAI, QAI, RTA, RDB, RHT, SWP - no further details needed.

LAI, UAI - ON, OFF or TOG.

At this point we make use of a pseudo parameter 4, at offset 40. I.e.
we no longer assume parameter 3 is one long string but continue to deal
with each word in turn.

WAI, AVT - Parameter 3 contains either SET or CHG, and specifies
whether to set an absolute weight/volume or whether to modify the
existing value. Parameter 4 then contains an integer specifying either
the new value, or the change to be made. Weights must be in the range -
7 to +7, volumes in the range -63 to +63.

FAI - Parameter 3 contains an integer from 1-20 specifying which filter
is to be editted. Parameter 4 then contains one of NVR, ALW, ISO, LIN.
This specifies the new state for the given filter.


Notes;

The track,album and artist numbers required are the pre-filter numbers,
also known as the global number. A mapping from particular tracks to
particular numbers can be obtained by either calling AMPlay repeatedly
to request the details of each track in turn via macro expansion, or,
asking AMPlay to dump out the playlist to file, and examining that.
However, it is probably most likely to be useful in cases where you
want to alter the current track, album or artist, in which case
specify -1 as the item number.

For linkage, ignore uniqueness etc, the attributes exist independently
on albums, artists etc as well as at the track level. For filtering and
relative track volume however, they exist only at the track level. In
such cases, performing the operation at the album or artist level is
just a way to get the operation performed on multiple tracks.

When changing weights or volumes, the resulting weight or volume is
constrained within the normal allowed ranges. Attempts to set a value
outside the normal range will result in an error. Attempts to change a
specific track album or artist to a value outside the allowed range
will also result in an error.

However, if changing the relative track volume on an album, say, as
long as the change is plausible, even if any tracks within the album
would have overshot the end, no error is returned. The offending tracks
are silently constrained. (e.g. if a one track in an album has a volume
of +50, and the album is told to change by +20, that track will end up
with +63, but no error is returned because the request was plausible -
+20 may have been added to the other tracks in the album successfully).

SWP swaps the item with the one below it in database terms. If you want
to swap track 5 with track 6, you would call SWP with 6 as the track
number. As with the interface in the database editor, you cannot move
tracks outside their album, or albums outside their artist (an 'outside
range' error will be returned).

SPL

Parameter 3 indicates the filename to save the playlist to.
(Note - this is all there is at present. Future versions of the API may
offer some or all of the functionality of the export interface).


OPT

Parameter 3 indicates the filename to save as. This is used by
AMPlayCFG if it is started manually, to get the current state of the
options from the running copy of AMPlay.


TST

This is a simple test command. It takes no parameters, and does
nothing. However, it is a valid command, and so will generate a
'success' reply. Can be useful while testing. It's also a useful test
of whether you're talking to a copy of AMPlay that understands the v2
message formats

________________________________________________________________________


* 7.2 AMPlay_Request (&563C1):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(Formerly known as AMPlay_Status)

+20 flags
+24 Command
+28 optional parameter 1
+32 optional parameter 2
+36 optional parameter 3

This is used to request information about AMPlay's current state, or
specific items via macro expansion. The reply will come back as an
AMPlay_Ack by default unless reply by file is requested.

Don't forget SWI AMPlayer_Info will return a lot of information about
current status at the mp3 level - elapsed time etc, and doesn't have
the delays involved in sending a message and waiting for the reply. Use
this only if you want information about the AMPlay front end.)


Flags:

Flags set sent at +20 in the message block.

Bit:   Meaning if set:
0:     Don't bother replying.
1:     Reply by file instead of by message
       see below for more details of reply by file.
8:     v2 and later understood. MUST BE SET.

other bits should be zero.



Commands:

The command is sent at +24 in the message block.

A command consists of a string of up to three characters, CR terminated
(so that it occupies 4 bytes at most).

Commands are not case sensitive, and are hardcoded - i.e. they are not
fetched from the messages file, and therefore are not language
dependant.

Recognised commands

Command     Meaning                       Further parameters.

STS         Request status                1
MAC         Expand Macro                  3


Command details:


STS:

Parameter 1 indicates what area we are interested in;

AVR - AMPlay version information
API - AMPlay API information
SRC - AMPlay search information
STA - AMPlay state information
OPT - AMPlay options information
SKN - AMPlay skin information
PLR - General player information
FLT - Filter information
ORD - Playback order information


MAC:

Parameter 1 must be one of;

CUR
ATC
ATM
ATN

This specifies how the track for which the macro expansion is to be
relative to is determined.

CUR = current track. 'No track playing' is returned if there is no
current track. (Note - not a no current track error).
ATC = Any track, using the current track number, if any. Middle track
of database if there is no current track.
ATM = Any track, using the middle track of the database.
ATN = Any track, using track N, specified in parameter2.


Some explanation required here:

Some macros are intrinsically tied to the currently playing track
(elapsed time, for example), and make no sense otherwise. The macro
expansion function inside AMPlay knows this, and needs a parameter to
tell it whether it is ok to expand such macros.

So, parameter1=CUR will expand macros in the for-current-track-only
list, while parameter1=anythingelse will ignore them.

When determining the middle track in the database, it always rounds up,
so if there are only two tracks in the database, it always picks the
latter.

For any of the totals macros, the track specified doesn't actually
matter. Clearly, if you are interested in a particular track, album or
artist, you need to specify the track via ATN.

Parameter 2 is empty, unless parameter 1 is ATN, in which case
parameter 2 is an integer containing the track number.

Parameter 3 contains the string to be expanded.

________________________________________________________________________


* 7.3 AMPlay_Ack (&563C2):
~~~~~~~~~~~~~~~~~~~~~~~~~~

This is sent by AMPlay to tasks that send it "AMPlay_Command"'s or
"AMPlay_Request"'s, unless they request reply by file instead. It is
used to return basic success/failure information, and can also return
other items, such as the results of string expansion.

The layout is the same in all cases;

Flags at +20
Response at +24
Response at +28
Response at +32
Response at +36

Whether the response is a string or an integer will vary, but in
general, the response (if any) at +36 will always be a string, the rest
will vary.


+20
This is always returned in response to any command or status request.

It is a bitfield, where the bits reflect error/success

bit 0  - set if success, unset if error.
bit 1  - set if response at +24 is valid
bit 2  - set if response at +28 is valid
bit 3  - set if response at +32 is valid
bit 4  - set if response at +36 is valid (always a string, if present)
bit 5  - set if response at +24 is a string (integer if unset)
bit 6  - set if response at +28 is a string (integer if unset)
bit 7  - set if response at +32 is a string (integer if unset)
bit 8  - error: unrecognised command.
bit 9  - error: unrecognised parameter for command.
bit 10 - error: file not found
bit 11 - error: file wrong type.
bit 12 - error: outside range
bit 13 - error: disabled.
bit 14 - error: no current track.
bit 15 - error: no tracks in database
Other bits undefined, should be unset.

If bit 0 is set, then bits 1-7 indicate what else is being returned.
If bit 0 is unset, then bits 1,2,3,5,6,7 should be 0, and bits 8-13
indicate the error details. bit 4 may still be set indicating textual
information has also been provided. (e.g. to indicate the filename to
which a file not found error refers)
The 'no current track' error is also returned in the case where there
is a track playing, but it was started by a different front end. In
that case, AMPlay has no connection between that track and an entry in
its tracks database, and so cannot perform operations on it (such as
relative track volume).
The 'disabled' error occurs if you try to do something that is
specifically disallowed. e.g. activate a filter that is not available,
or make unavailable a filter that is active. In general terms, it
occurs when you try to alter the state of something that would be
greyed out if you tried to do it through the graphical interface.


For a reply to AMPlay_Request, STS, AVR:

+24 - AMPlay version. (integer)
+28 - Application status (bitfield).
      bit0 for production release.
      bit1 indicates a public beta.
      bit2 indicates a private beta.
      bit3 indicates an alpha.
      bit4 indicates a user-customised version
      other bits reserved, must be 0.
      
+36 - AMPlay version string, as on program info window.

(a public beta would be a test version uploaded to the website for
anyone to download. A private beta might be sent in email to test a
specific problem. Alpha versions are my own works in progress, and are
not normally released. Custom versions are, in accordance with the
license agreement, user-modified versions that the user wishes to
release widely. It is possible that a custom version might also be a
beta/alpha)

For a reply to AMPlay_Request, STS, API:

+24 - AMPlay API version (integer)
+28 - AMPlay API lowest compatible version.

This is because - if the next version of AMPlay extends the api (which
is quite likely), the api version number will increase. However, if
these are purely extensions and contain no changes to existing
behaviour, then existing apps will still be able to talk using v200 as
described here.

So, v210 of the api would specify 210 at +24, but 200 at +28,
indicating that there is nothing in 200 that is not supported, just
extra things that 210 can do.

For a reply to AMPlay_Request, STS, SRC:

+24 - AMPlay search version (integer)
+28 - AMPlay search lowest compatible version.

This specifies the acceptable formats of search block. As search blocks
are not yet passable via API commands, this isn't of much use yet.

For a reply to AMPlay_Request, STS, OPT:

+24 - AMPlay options file version (integer). Version that AMPlay writes.
+28 - AMPlay options lowest compatible version.

This specifies the acceptable formats of options file. For backwards
compatibility, a version of 0 corresponds to files that have no version
number.

For a reply to AMPlay_Request, STS, STA:

+24 - AMPlay state version (integer)
+28 - AMPlay state lowest compatible version.

As above, but for the state file format. Current version, and lowest
compatible version.

For a reply to AMPlay_Request, STS, SKN:

+24 - AMPlay skin version (integer)
+28 - AMPlay skin lowest compatible version.

As above, but for the skin format. Current version, and lowest
compatible version. (You can't directly read the name of the
currently configured skin, but as AMPlay cannot currently change
skin without restarting, this information can be read from the
options file.)

For a reply to AMPlay_Request, STS, PLR:

+24 - Integer. Bitfield indicating status;

bit0:stopped
bit1:playing
bit2:paused
bit3:fastforwarding
bit4:rewinding
bit5:queueing
bit6:track history available
bit7:database contains at least one track

(some combinations make sense, some don't - paused and fastforwarding
means that it is heading for a target time, and will be paused when it
gets there)
If bit0 is set, bits1-5 should be unset.
bit2 set implies bit1 set
bits 3 and 4 are mutually exclusive

+28 Integer. Bitfield indicating status;
bits0-7: base volume
bits8-15: relative volume
bit21: loop status
bit22: 0=autonext never 1=autonext of type specified in bit23
bit23: (if bit22=1) 0=autonext within history 1=autonext always.
bit24: set if track repeat active
bit25: set if album repeat active
bit26: set if artist repeat active

Remaining bits currently unused.

For a reply to AMPlay_Request, STS, FLT:

+24 Integer. Bitfield where bits 0-19 indicate which filters are
available.
+28 Integer. As above, but indicating which ones are active.
+32 String. One of;
LIN
ISO
ALW
This indicates which filter setting is currently being used. (it's
decided based on the playback order.)

Note that bit0 = filter1 etc.

For a reply to AMPlay_Request, STS, ORD:

+24 String.
+28 String
+32 String.

The strings are all one of LIN, RND, IGN or CHA. +24 specifies the
track playback order, +28 specifies the album, +32 specifies the
artist. +24 therefore can never be IGN as the track playback order
has to be linear or random. If chaos mode is active, then all three
strings will be CHA.

For a reply to an AMPlay_Request, MAC;

+24 Integer.

0-static result, indefinite
1-static result, as long as current track remains current
2-dynamic result
So, 0 tells the calling application that the result will not change
until the string to be expanded changes (unless tracks are
added to / removed from  the database etc)
1 tells it that the result will change if the current track changes
2 tells it that it is changing rapidly (e.g. it contains a
remaining/elapsed time that is changing every second).
Generally, applications should not repeatedly re-expand the same string
unless it is dynamic. 

+28 Integer.
Normally 0.
A +ve value indicates that the macro expansion produced too long a
string. The value indicates the number of characters trimmed from the
right hand edge to fit the reply in to the message block. The calling
application might therefore use this to either indicate the truncation
to the user, or possibly break the string to be expanded down into
smaller segments that are in themselves expandable without truncation.

+36 String.

This contains the result of the macro expansion.

________________________________________________________________________


* 7.4 AMPlay_ChangingState (&563C3):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is broadcast by AMPlay on startup, and on quit. AMPlayCfg listens
for this, to work out whether AMPlay is running and is a new enough
version to support messages. AMPlayCfg also calls AMPlay_Request when
AMPlayCfg starts to determine if a new enough AMPlay is already running.
AMPlayCfg needs to know this information to work out whether to tell
AMPlay that options have been changed, or just update the config files
for AMPlay to re-read on next run.

It contains;

+20: Flags.
+24: Integer. AMPlay version
+28: Integer. AMPlay API version.
+32: Integer. Lowest compatible API version
+36: Integer. AMPlay options file version that AMPlay writes.
+40: Integer. Lowest compatible options file version

The flags word has the following meanings;

bit:  Meaning if set.
0:    Starting up (shutting down if unset)
other bits currently unused.

________________________________________________________________________


* 7.5 AMPlayCfg_ChangingState (&563C4):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is broadcast by AMPlayCfg on startup, and on quit. AMPlay listens
for this, to work out whether AMPlaycfg has been started by the user
(as opposed to being launched from AMPlay). AMPlay checks through the
list of running tasks to see whether it is already running when AMPlay
starts (there not being a version problem here). AMPlay only uses this
information to keep the button on the main window in the correct state.

In v2.00 AMPlaycfg also broadcasts this when it received an
AMPlay_changing state that indicates that AMPlay has just started. This
allows AMPlay to know that a copy of AMPlayCfg is already running, and
what it's version information is.

It contains;

+20: Flags.
+24: Integer. AMPlayCFG version
+28: Integer. AMPlayCFG API version.
+32: Integer. Lowest compatible API version.
+36: Integer. AMPlay options file version that AMPlayCfg writes.
+40: Integer. Lowest compatible options file version


The flags word has the following meanings;

bit:  Meaning if set.
0:    Starting up (shutting down if unset)
other bits currently unused.

________________________________________________________________________


* 7.6 AMPlayCfg_Command (&563C5):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is broadcast by AMPlay when it wants to make a running copy of
AMPlayCfg either load an options file, or bring its window to the front.

It contains;

+20: Flags. 
+24: Command (three character string, CR terminated.)
+32: String. (if command requires it)

Flags:

Bit:   Meaning if set:
0:     Don't bother replying.
8:     v2 API understood. MUST BE SET.

Other bits unused.

Commands:

LOA
FRN

LOA:

This tells AMPlayCfg to load the file specified at +32, and bring
itself to the front.

FRN

This just tells AMPlayCfg to bring its window to the front, without
taking any other action.

________________________________________________________________________


* 7.7 AMPlayCfg_Ack (&563C6):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

AMPlayCfg returns this in response to AMPlayCfg_Command messages,
unless those messages set the flag to not bother replying. It comprises;

Flags at +20

Flags is a bitfield, where the bits reflect error/success

bit 0  - set if success, unset if error.

bit 8  - error: unrecognised command.
bit 10 - error: file not found
bit 11 - error: file wrong type.

(i.e. same as AMPlay_ack flags, but a reduced set as only certain ones
are relevant.)

'File wrong type' is returned if it is asked to load a file that is not
of type 'AMPlay', 'AMPlaycf' or text. No error is returned if the file
contains no recogniseable options.

________________________________________________________________________


* 7.8 Reply by file:
~~~~~~~~~~~~~~~~~~~~

Normally, AMPlay replies to an incoming message by sending a message
back to the application the message came from. AppA sends an
AMPlay_Command or AMPlay_Request to AMPlay, and AMPlay sends an
AMPlay_Ack to AppA.

This is fine if AppA is a normal wimp task, and capable of receiving
messages. If however, is is running in a taskwindow, it has no way
of receiving messages (the taskwindow itself gets them, and they
never reach the task running inside the taskwindow).

Reply by file is an alternative way for AMPlay to respond. Instead
of sending an AMPlay_Ack to the task that sent the message, it writes
the result to a file Pipe::$.AMPlayOut.

The output comprises each returned parameter that would have been sent
in the Ack. i.e. A flags word, followed by whatever returned
information the flags word indicates. Integers are written to the
output as strings.

e.g. A reply to an AMPlay_Request, MAC, ATC, 0, %tn might be;

23
1
0
04 - Epitaph

AMPlayCfg does not support reply by file.

(Note that this format is not the same as that used in 1.5x)

________________________________________________________________________


* 7.9 Compatibility:
~~~~~~~~~~~~~~~~~~~~

The API in 1.5x of AMPlay is not compatible in any way with that in
2.x. Commands are now named instead of numbered, and the flags word is
now separate from the command word rather than hiding information in
the high bits of the command.

I took the decision to make it incompatible when it became clear that
the 1.5x API made quite a few assumptions about filtering behaviour
(and playback order and a few other things) that were no longer valid.
This meant that 2.x was going to be incompatible in significant ways
anyway, and therefore it provided an opportunity to resolve any
outstanding issues with it. To do it properly, in other words.

The use of named instead of numbered commands and parameters opens up
the 'raw' format for AMPlayCmd commands, and allows AMPlayRCG to offer
the full range of API functionality to its clients, without having to
know what the full range of commands and parameters actually is. i.e.
it makes it much easier for such things to act as a passthrough that
places no limits on the content. AMPlayCmd can also do just about
anything that the API makes available without having to understand it
itself.

If AMPlay 2.x receives a 1.5x style message (as indicated by bit8 not
being set in the flags word), it will reply in 1.5x style format with
an unrecognised command error.

Similarly, if you send a 2.x style message to 1.5x, you'll get back an
unrecognised command error in 1.5x format. This will look like this;

+20 Integer. A value of 8 indicates unrecognised command.

This can be detected because this corresponds to bit 3 set, with
everything else 0. i.e. bit 0 is unset, indicating an error, but none
of the error bits (8 onwards) are set. A version that speaks 2xx of the
API would never return this.

It's worth noting that compatibility gets a bit fuzzy in some areas.
Suppose v210 of AMPlay contains no changes to the API, but does extend
the range of macros supported. In that case a call to expand a macro
would work on one version of AMPlay and not the other even though the
API implementations are identical. Where you get into relying on other
features within AMPlay, you may need to take the AMPlay version itself
into account.

That said, AMPlay provides two pieces of version information for the
API - the current API version, and the lowest version with which it
is compatible. e.g. a version 210 which added extra commands, but
included the entire 200 API unchanged, would declare itself as 210,
compatible with 200.

________________________________________________________________________


* 7.10 Example Applications:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The AMPlayRCG application uses the API to communicate with AMPlay.

AMPlayCfg also makes (fairly minimal) use of it.

AMPlayCmd uses the API, and also uses the reply by file mechanisms to
retrieve the results of macro expansion.

The source for all of these is available. AMPlayCmd is included with
AMPlay, and is not crunched or otherwise compressed. AMPlayRCG is a
separate download from my website.

None of these make full use of every API call - in particlar AMPlayRCG
operates as a pass through and has very little understanding of the
data it passes on (although it does have to understand AMPlay's
replies).


* 7.10.1 Raw format:
~~~~~~~~~~~~~~~~~~~~

AMPlayCmd and AMPlayRC have a 'raw' mode which allows a string to be
passed that contains the command and parameters separated by #
characters. e.g.

cmd#pau#tog

would send a command to toggle the pause status. Fields that are
entirely numeric are assumed to be integers and passed as such. This is
covered in more detail in the AMPlayCmd (section 8.3) and AMPlayRCG
documentation (included with AMPlayRCG).

When using the raw format, they are not limited to the API version that
was current when they were produced - they can handle just about any
subsequent extensions or additions.

There is also the AMPlayAPI app, available as part of the source
archive. This contains generic code for sending and receiving messages,
although all the parameters are manually entered. However, it provides
a useful piece of scaffolding for testing API functionality.

________________________________________________________________________


* 7.11 Changing options via the API:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Possibly obvious, but worth noting.

There is no API for directly setting AMPlay options. If your client
wishes to change options, then it should write a temporary file in the
options file format, containing just the options that need changing,
filetype it as AMPlaycf, and pass it to AMPlay using the load file
mechanism.

A header including the text '[options]' will also work if you want to
leave the file with the text filetype.

AMPlayCfg uses this mechanism to update the running copy of AMPlay with
the changed options.

________________________________________________________________________


* 7.12 Future APIs:
~~~~~~~~~~~~~~~~~~~

Future versions of AMPlay may extend the range of commands available.
They may also extend the parameters available for particular commands.
However, there are no changes planned that would alter the structure of
the API in an incompatible way. If such a thing were to happen, the
version in which this change occurred would report its API version as
the lowest compatible version.

Particular things that are currently conspicuously absent from the api;

- The search mechanisms cannot be accessed from the API.

- There is no way to get to the export functionality via the API.

- The naming method for the tracks cannot be changed via the API.

Similarly, the re-read tags and write tags options are not available
via the API. (The naming details themselves also cannot be editted via
the API, but this is likely to remain the case).

________________________________________________________________________
Copyright  2008 Mike Sandells, mike@mikejs.com
Last Modified: 30.05.2008