Decoder plug-ins
Decoder plug-ins must implement and export the functions defined in
decoder_plug.h.
int _System decoder_init(void **w)
BOOL _System decoder_uninit(void *w)
- w : Allocate any chunk of memory necessary for the decoder's
function. This pointer will be passed to the other functions.
- return value : -1 means the decoder was not initialized
successfully.
Init function is called when pm123 needs the specified decoder
to play the stream demanded by the user. So only one decoder plug-in is
active at any given time. It should initialize the necessary semaphores
and threads. decoder_uninit is called when another decoder
than yours is needed, and should destroy the decoder's thread,
semaphores, other opened handles and free allocated memory for w.
ULONG _System decoder_command(void *w, ULONG msg, DECODER_PARAMS *params)
- msg: one of the following:
DECODER_PLAY
DECODER_STOP
DECODER_FFWD
DECODER_REW
DECODER_JUMPTO
DECODER_SETUP
DECODER_EQ
DECODER_BUFFER
- params: structure that contains the parameters needed by the preceding
commands
- return value:
0 -> ok
1 -> command unsupported
1xx -> msg specific
There is a lot of commands to implement for this function. Parameters
needed for each of the are described in the definition of the structure
in the .h file.
- DECODER_PLAY start playing the given filename, URL or others.
- DECODER_STOP stop playing.
- DECODER_FFWD engage in ffwd mode (ie.: play faster or skip when playing)
- DECODER_REW engage rewind mode
- DECODER_JUMPTO jump and start decoding at the given time position
- DECODER_SETUP setup various parameters such as the output plugin
functions, hwnd where to send messages and an optional play semaphore.
- DECODER_EQ usually only useful for MPEG decoding where frequency
equalization is cheap.
- DECODER_BUFFER reports the reader buffer status.
The decoder MUST WinPostMsg() the following messages to hwnd:
- WM_PLAYSTOP when the stream has finished decoding.
- WM_PLAYERROR when a playback error occured so that pm123 should know to
stop immediately.
- WM_SEEKSTOP when a JUMPTO operation is completed (ie.: when no buffers
from before the seek is sent to the output plugin anymore).
ULONG _System decoder_status(void *w)
- return value - One of the following:
DECODER_STOPPED
DECODER_PLAYING
DECODER_STARTING
ULONG _System decoder_length(void *w)
- return value - number of milliseconds the stream lasts (you can
report -1 if unknown)
The call to this function must be valid even if DECODER_STARTING or
DECODER_STOPPED is reported (when the stream plays too fast for
example).
ULONG _System decoder_fileinfo(char *filename, DECODER_INFO *info)
ULONG _System decoder_trackinfo(char *drive, int track, DECODER_INFO *info)
- filename : full path or URL to the desired stream.
- drive : ie.: "X:"
- track : CD tracks start from 1.
- info : this structure must be filled with the required
information.
- return value:
0 = everything's perfect, structure is set
100 = error reading file (too small?)
200 = decoder can't play that
1001 = http error occured
other values = errno
decoder_fileinfo and decoder_trackinfo (for CD
decoders) must be independant from the current status of the decoder.
It should always be functionnaly and give consistent results in any
conditions.
ULONG _System decoder_cdinfo(char *drive, DECODER_CDINFO *info)
- drive: ...
- info: required info on the number of tracks available from the
decoder.
This is used by pm123 before calling decoder_trackinfo.
ULONG _System decoder_support(char *fileext[], int *size)
- fileext: fill this array with all the wildcard expression matching
filenames this decoder can play (each element is a 8 bytes char array).
- size I/O: number of wildcard expressions returned (if this value is not
big enough, ie.: 0, return the appropriate size without filling
fileext)
- return value: return what kind of stream can the decoder play:
DECODER_FILENAME
DECODER_URL
DECODER_TRACK
DECODER_OTHER
This is used by pm123 to suggest to the user what he can play with the
decoder. Extentions can be for example "*.MOD".
Last revised May 20, 2000, Copyright ©
Taneli Leppä <rosmo@sektori.com>, Samuel Audet <guardia@cam.org>