Error Handling
- Functions with no return value in the corresponding C++ API return 0 on failure and 1 on success.
- Functions that return a string in the corresponding C++ API return a dynamically allocated const char *. I case of failure or memory allocation failure, a NULL pointer is returned.
- Functions that return integer values signal error condition by returning an invalid value (-1 in most cases, 0 in some cases).
Strings
- All strings returned from libopenmpt are encoded in UTF-8.
- All strings passed to libopenmpt should also be encoded in UTF-8. Behaviour in case of invalid UTF-8 is unspecified.
- All strings returned from libopenmpt are dynamically allocated and must be freed with openmpt_free_string(). Do NOT used C standard library free() for libopenmpt strings as that would make your code invalid on windows when dynamically linking against libopenmpt which itself statically links to the C runtime.
- All strings passed to libopenmpt are copied. No ownership is assumed or transferred.
Detailed documentation
libopenmpt C
The C API documentaion currently lacks behind the C++ API documentation. In case a function is not documented here, you might want to look at the libopenmpt C++ documentation. The C and C++ APIs are kept semantically as close as possible.
Examples
FILE*
#include <memory.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <portaudio.h>
#define BUFFERSIZE 480
#define SAMPLERATE 48000
static int16_t left[BUFFERSIZE];
static int16_t right[BUFFERSIZE];
static int16_t* const buffers[2] = {left,right};
int main(int argc,char* argv[]){
FILE* file = 0;
size_t count = 0;
PaStream* stream = 0;
PaStreamParameters streamparameters;
memset(&streamparameters,0,sizeof(PaStreamParameters));
(void)argc;
file = fopen(argv[1],"rb");
fclose(file);
Pa_Initialize();
streamparameters.device = Pa_GetDefaultOutputDevice();
streamparameters.channelCount = 2;
streamparameters.sampleFormat = paInt16|paNonInterleaved;
streamparameters.suggestedLatency = Pa_GetDeviceInfo(streamparameters.device)->defaultHighOutputLatency;
Pa_OpenStream(&stream,NULL,&streamparameters,SAMPLERATE,paFramesPerBufferUnspecified,0,NULL,NULL);
Pa_StartStream(stream);
while(1){
if(count==0){
break;
}
Pa_WriteStream(stream,buffers,count);
}
Pa_StopStream(stream);
Pa_CloseStream(stream);
Pa_Terminate();
return 0;
}
in memory
#include <memory.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <portaudio.h>
#define BUFFERSIZE 480
#define SAMPLERATE 48000
static int16_t left[BUFFERSIZE];
static int16_t right[BUFFERSIZE];
static int16_t* const buffers[2] = {left,right};
int main(int argc,char* argv[]){
FILE* file = 0;
size_t size = 0;
void* data = 0;
size_t count = 0;
PaStream* stream = 0;
PaStreamParameters streamparameters;
memset(&streamparameters,0,sizeof(PaStreamParameters));
(void)argc;
file = fopen(argv[1],"rb");
fseek(file,0,SEEK_END);
size = ftell(file);
fseek(file,0,SEEK_SET);
data = malloc(size);
size = fread(data,1,size,file);
fclose(file);
free(data);
Pa_Initialize();
streamparameters.device = Pa_GetDefaultOutputDevice();
streamparameters.channelCount = 2;
streamparameters.sampleFormat = paInt16|paNonInterleaved;
streamparameters.suggestedLatency = Pa_GetDeviceInfo(streamparameters.device)->defaultHighOutputLatency;
Pa_OpenStream(&stream,NULL,&streamparameters,SAMPLERATE,paFramesPerBufferUnspecified,0,NULL,NULL);
Pa_StartStream(stream);
while(1){
if(count==0){
break;
}
Pa_WriteStream(stream,buffers,count);
}
Pa_StopStream(stream);
Pa_CloseStream(stream);
Pa_Terminate();
return 0;
}