Main Page Modules Alphabetical List Compound List File List Compound Members File Members

# 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.