---

Functions

Functions
int	DecMPA_CreateUsingFile (void **ppDecoder, const char *sFilePath, int APIVersion)
	Creates a new decoder that obtains its input data from a file.
int	DecMPA_CreateUsingCallbacks (void **ppDecoder, const DecMPA_Callbacks *pCallbacks, void *pCallbackContext, int APIVersion)
	Creates a new decoder that obtains its input data using callback functions.
int	DecMPA_SetParam (void *pDecoder, int ID, long Value)
	Sets additional DecMPA parameters.
long	DecMPA_GetParam (void *pDecoder, int ID)
	Returns the current value of a DecMPA parameter.
int	DecMPA_Decode (void *pDecoder, void *pBuffer, long nBufferBytes, long *pBytesDecoded)
	Decodes some data and stores it in the supplied buffer.
int	DecMPA_DecodeNoData (void *pDecoder, long *pDecodedBytes)
	This is a special version of DecMPA_Decode that does not actually decode any MPEG Audio data, but only decodes the header information.
int	DecMPA_SeekToTime (void *pDecoder, long Millis)
	Changes the decoding position to the specified time, relative to the beginning of the data stream.
int	DecMPA_GetTime (void *pDecoder, long *pTime)
	Retrieves the current decoding time.
int	DecMPA_GetDuration (void *pDecoder, long *pDuration)
	Retrieves the time that it takes to play back the whole data stream.
int	DecMPA_GetOutputFormat (void *pDecoder, DecMPA_OutputFormat *pFormat)
	Retrieves the format of the data that was returned by the last call to DecMPA_Decode.
int	DecMPA_OutputFormatChanged (void *pDecoder)
	Checks wether the output format has changed during the last call to DecMPA_Decode.
int	DecMPA_GetMPEGHeader (void *pDecoder, DecMPA_MPEGHeader *pHeader)
	Retrieve mpeg header of the data that was returned by the last call to DecMPA_Decode.
int	DecMPA_GetID3v2Data (void *pDecoder, unsigned char **ppData, long *pDataSize)
	Returns the file's ID3v2 tag, if it has one.
void	DecMPA_Destroy (void *pDecoder)
	Destroys a decoder.
int	DecMPA_GetVersion (void)
	Returns the version number of the DecMPA API used by the library.

---

Function Documentation

int DecMPA_CreateUsingFile (  void **    ppDecoder, const char *    sFilePath, int    APIVersion )

Creates a new decoder that obtains its input data from a file. If you want to provide the input data in some other customized way, use DecMPA_CreateUsingCallbacks instead. After the decoder is created, additional parameters can be configured with DecMPA_SetParam. Parameters: ppDecoder  pointer to a void* variable that receives the address of the decoder object. sFilePath  path of the file to open APIVersion  version number of the DecMPA API. You should always pass the constant DECMPA_VERSION for this parameter. Returns : a DecMPA result code (see Result Codes).

int DecMPA_CreateUsingCallbacks (  void **    ppDecoder, const DecMPA_Callbacks *    pCallbacks, void *    pCallbackContext, int    APIVersion )

Creates a new decoder that obtains its input data using callback functions. After the decoder is created, additional parameters can be configured with DecMPA_SetParam. Parameters: ppDecoder  pointer to a void* variable that receives the address of the decoder object. pCallbacks  structure containing pointers to the callback functions that are used to retrieve the MPEG Audio data. pCallbackContext  a pointer that is simply passed to the callback functions. It has no meaning to the decoder and is only meant to be used to pass arbitrary data to the callback functions. APIVersion  version number of the DecMPA API. You should always pass the constant DECMPA_VERSION for this parameter. Returns : a DecMPA result code (see Result Codes).

int DecMPA_SetParam (  void *    pDecoder, int    ID, long    Value )

Sets additional DecMPA parameters. Calling this function is completely optional - if you don't call it or only call it for some parameters, the remaining parameters will simply keep their default values. This function should only be called directly after the decoder was created, before calling any of the other functions. Otherwise DecMPA_SetParam may return DECMPA_ERROR_WRONGSTATE. Parameters: pDecoder  the decoder object ID  ID of the parameter to set. See Configuations Parameters. Value  the new value for the specified parameter. Which values are possible depends of the parameter. Returns : a DecMPA result code (see Result Codes).

long DecMPA_GetParam (  void *    pDecoder, int    ID )

Returns the current value of a DecMPA parameter. Parameters: pDecoder  the decoder object ID  ID of the parameter. See Configuations Parameters. Returns : the current value of the specified parameter. See also: DecMPA_SetParam

int DecMPA_Decode (  void *    pDecoder, void *    pBuffer, long    nBufferBytes, long *    pBytesDecoded )

Decodes some data and stores it in the supplied buffer. The buffer is not necessarily completely filled. Always check the value stored in pBytesDecoded to find out how much data has been decoded. The format of the data (frequency and number of channels) can be obtained by calling DecMPA_GetOutputFormat after DecMPA_Decode. The format may change from one call of DecMPA_Decode to the next. Wether the format has changed can be checked using DecMPA_OutputFormatChanged. Parameters: pDecoder  the decoder object pBuffer  pointer to a buffer that receives the decoded data. nBufferBytes  size of the buffer, in bytes pBytesDecoded  pointer to a variable that receives the number of bytes that were stored in the buffer. Returns : a DecMPA result code (see Result Codes).

int DecMPA_DecodeNoData (  void *    pDecoder, long *    pDecodedBytes )

This is a special version of DecMPA_Decode that does not actually decode any MPEG Audio data, but only decodes the header information. This function is a lot faster than DecMPA_Decode and can be used to make a quick run through the file and obtain accurate information about its properties, like the exact duration or decoded file size. The function behaves in all ways like DecMPA_Decode, except that it does not return any data. In particular, the output format and mpeg audio header information returned by DecMPA_GetOutputFormat and DecMPA_GetMPEGHeader will be properly updated, just as DecMPA_Decode does. Parameters: pDecoder  the decoder object pDecodedBytes  pointer to a variable that receives the decoded size (in bytes) of the current MPEG audio frame. If DecMPA_Decode was called before and some parts of the current frame have already been read, the size of the remaining data is returned Returns : a DecMPA result code (see Result Codes).

int DecMPA_SeekToTime (  void *    pDecoder, long    Millis )

Changes the decoding position to the specified time, relative to the beginning of the data stream. If DecMPA_CreateUsingCallbacks was used to create the decoder and no Seek callback function has been specified, seeking is not supported and DECMPA_ERROR_UNSUPPORTED is returned. Parameters: pDecoder  the decoder object Millis  the target time, in milliseconds Returns : a DecMPA result code (see Result Codes).

int DecMPA_GetTime (  void *    pDecoder, long *    pTime )

Retrieves the current decoding time. The decoding time corresponds to the time that it takes to play the data that has been decoded up to now. Parameters: pDecoder  the decoder object pTime  pointer to a variable that receives the time, in milliseconds. Returns : a DecMPA result code (see Result Codes).

int DecMPA_GetDuration (  void *    pDecoder, long *    pDuration )

Retrieves the time that it takes to play back the whole data stream. If the duration is not known -1 is returned. Note: The duration is an estimation that can be slightly wrong for some files but is pretty accurate for the wide majority of files. If you need a 100% accurate duration value, there is really no other way than to read through the whole file with DecMPA_Decode or DecMPA_DecodeNoData and add up the DecodedBytes values that are returned by those functions. Note that if you only make this pass through the file to get the duration, i.e. you do not need decoded audio data, you can use DecMPA_DecodeNoData which is a lot faster than DecMPA_Decode. Parameters: pDecoder  the decoder object pDuration  pointer to a variable that receives the duration, in milliseconds. Returns : a DecMPA result code (see Result Codes).

int DecMPA_GetOutputFormat (  void *    pDecoder, DecMPA_OutputFormat *    pFormat )

Retrieves the format of the data that was returned by the last call to DecMPA_Decode. The nType member of DecMPA_OutputFormat never changes and its value is defined by the DECMPA_PARAM_OUTPUT parameter that can be set using DecMPA_SetParam. If the value has not been explicitly changed using DecMPA_SetParam it will be DECMPA_OUTPUT_INT16, indicating 16 bit signed samples. The remaining fields of the structure may change after calls to DecMPA_Decode or DecMPA_DecodeNoData. Parameters: pDecoder  the decoder object pFormat  pointer to a DecMPA_OutputFormat object that is filled with the format data Returns : a DecMPA result code (see Result Codes).

int DecMPA_OutputFormatChanged (  void *    pDecoder )

Checks wether the output format has changed during the last call to DecMPA_Decode. Returns : nonzero if the format has changed, zero otherwise.

int DecMPA_GetMPEGHeader (  void *    pDecoder, DecMPA_MPEGHeader *    pHeader )

Retrieve mpeg header of the data that was returned by the last call to DecMPA_Decode. This function is only supplied for information purposes. Parameters: pDecoder  the decoder object pHeader  pointer to a DecMPA_MPEGHeader object that received the data. Returns : a DecMPA result code (see Result Codes).

int DecMPA_GetID3v2Data (  void *    pDecoder, unsigned char **    ppData, long *    pDataSize )

Returns the file's ID3v2 tag, if it has one. If the file has no ID3v2 tag, DECMPA_ERROR_NOTAVAILABLE is returned. This function will always return DECMPA_ERROR_NOTAVAILABLE if the decoder parameter DECMPA_PARAM_PROVIDEID3V2 has not been set to DECMPA_YES with DecMPA_SetParam. Note: There are other libraries that can be used to parse the returned data, one of them being id3lib. It can be found at http://id3lib.sourceforge.net/ . Parameters: pDecoder  the decoder object ppData  pointer to a pointer variable that will receive the address of the ID3v2 data. The memory that contains the data will remain valid until the decoder is destroyed. pDataSize  pointer to a variable that will receive the size of the ID3v2 data, in bytes. Returns : a DecMPA result code (see Result Codes).

void DecMPA_Destroy (  void *    pDecoder )

Destroys a decoder. Parameters: pDecoder  decoder object.

---