Browse Source

Rationalize and document return values

All read/write functions return -1 on error.

Add Doxygen-like comments to each public function of the midi.c
module to document the possible returned values.
develop
Damien Goutte-Gattat 8 years ago
parent
commit
6b146486d2
  1. 55
      src/midi.c

55
src/midi.c

@ -101,14 +101,14 @@ alsa_midi_write(midi_io_t *midi, unsigned char *buffer, size_t len)
midi->pos = midi->len = 0;
midi->error = snd_rawmidi_write(midi->alsa.out, buffer, len);
return midi->error;
return midi->error == len ? midi->error : -1;
}
static ssize_t
alsa_midi_read(midi_io_t *midi, unsigned char *buffer, size_t len)
{
midi->error = snd_rawmidi_read(midi->alsa.in, buffer, len);
return midi->error;
return midi->error >= 0 ? midi->error : -1;
}
static const char *
@ -284,6 +284,11 @@ oss_midi_get_ports(char ***ports, size_t *n, size_t *max)
/* Backend-independent functions. */
/**
* @return
* - A pointer to a newly allocated @c midi_io_t object;
* - @c NULL if an error occured.
*/
midi_io_t *
midi_open(const char *name)
{
@ -302,6 +307,11 @@ midi_open(const char *name)
return midi;
}
/**
* @return
* - 0 if the port was successfully closed;
* - -1 if an error occured.
*/
int
midi_close(midi_io_t *midi)
{
@ -310,6 +320,11 @@ midi_close(midi_io_t *midi)
return midi->backend.close(midi);
}
/**
* @return
* - The number of bytes written to the port;
* - -1 if an error occured.
*/
ssize_t
midi_write(midi_io_t *midi, unsigned char *buffer, size_t len)
{
@ -319,6 +334,11 @@ midi_write(midi_io_t *midi, unsigned char *buffer, size_t len)
return midi->backend.write(midi, buffer, len);
}
/**
* @return
* - The number of bytes read and stored into @a buffer;
* - -1 if an error occured.
*/
ssize_t
midi_read(midi_io_t *midi, unsigned char *buffer, size_t len)
{
@ -328,6 +348,10 @@ midi_read(midi_io_t *midi, unsigned char *buffer, size_t len)
return midi->backend.read(midi, buffer, len);
}
/**
* @return
* A static string containing the user-readable error message.
*/
const char *
midi_error(midi_io_t *midi)
{
@ -336,6 +360,12 @@ midi_error(midi_io_t *midi)
return midi->backend.error(midi);
}
/**
* @return
* A newly allocated null-terminated array of strings, each
* string being the name of a MIDI port. Freeing each string
* and the array itself is the caller responsibility.
*/
char **
midi_get_ports(void)
{
@ -361,6 +391,11 @@ midi_get_ports(void)
return ports;
}
/**
* @return
* - A single MIDI byte;
* - -1 if an error occured.
*/
int
midi_next(midi_io_t *midi)
{
@ -371,9 +406,8 @@ midi_next(midi_io_t *midi)
if ( midi->pos >= midi->len ) {
ssize_t n;
n = midi_read(midi, midi->buffer, MIDI_IO_BUFFER_SIZE);
if ( n < 0 )
return n;
if ( (n = midi_read(midi, midi->buffer, MIDI_IO_BUFFER_SIZE)) == -1 )
return -1;
midi->len = n;
midi->pos = 0;
@ -387,12 +421,21 @@ midi_next(midi_io_t *midi)
return b;
}
/**
* @return
* The last MIDI Status byte encountered.
*/
inline unsigned char
midi_status(midi_io_t *midi)
{
return midi->status;
}
/**
* @return
* - 0 if the messages were successfully sent;
* - -1 if an error occured.
*/
int
midi_change_program(midi_io_t *midi,
unsigned char channel,
@ -417,7 +460,7 @@ midi_change_program(midi_io_t *midi,
msg[5] |= (bank & 0x7F);
msg[7] |= (program & 0x7F);
return midi_write(midi, msg, sizeof(msg));
return midi_write(midi, msg, sizeof(msg)) == sizeof(msg) ? 0 : -1;
}
const char *midi_gm_patches[] = {

Loading…
Cancel
Save