Browse Source

Document return values of the sysex module

Add Doxygen-like comments to each public function in the sysex
module to document all possible return values.
develop
Damien Goutte-Gattat 8 years ago
parent
commit
00351c3b6a
  1. 35
      src/sysex.c

35
src/sysex.c

@ -22,6 +22,18 @@
#include <sysex.h>
/**
* @return
* - The number of bytes read and stored in the @a data buffer.
*
* If this value equals the size of the buffer, the caller should
* check whether the last byte in the buffer is a SysEx terminating
* byte (0xF7); if it is not, the buffer was not large enough to
* hold the entire message, and the caller may call the function
* again to get the rest of the message.
* - 0 if the SysEx message was abruptly interrupted.
* - -1 if an I/O error occured.
*/
ssize_t
sysex_read(midi_io_t *midi, unsigned char *data, size_t len)
{
@ -31,7 +43,7 @@ sysex_read(midi_io_t *midi, unsigned char *data, size_t len)
n = p = 0;
while ( n < len && loop ) {
if ( (byte = midi_next(midi)) < 0 )
if ( (byte = midi_next(midi)) == -1 )
return byte;
/*
@ -79,6 +91,12 @@ sysex_read(midi_io_t *midi, unsigned char *data, size_t len)
return n;
}
/**
* @return
* - The number of bytes read and stored in the @a reply buffer;
* - 0 if the reply message was abruptly terminated;
* - -1 if an I/O error occured.
*/
ssize_t
sysex_query(midi_io_t *midi,
unsigned char *query,
@ -88,12 +106,18 @@ sysex_query(midi_io_t *midi,
{
ssize_t n;
if ( (n = midi_write(midi, query, query_len)) > 0 )
if ( (n = midi_write(midi, query, query_len)) != -1 )
n = sysex_read(midi, reply, reply_len);
return n;
}
/**
* @return
* - 1 if the identify attempt was successful;
* - 0 if the reply was not a valid Device Inquiry Reply;
* - -1 if an I/O error occured.
*/
int
sysex_identify(midi_io_t *midi, midi_device_id_t *devid)
{
@ -107,7 +131,7 @@ sysex_identify(midi_io_t *midi, midi_device_id_t *devid)
0xF7 /* SysEx message end */ };
if ( (n = sysex_query(midi, query, sizeof(query),
reply, sizeof(reply))) < 0 )
reply, sizeof(reply))) == -1 )
return n;
if ( n != 15 && n != 17 ) /* invalid reply length */
@ -143,6 +167,11 @@ struct manufacturer
const char *name;
};
/**
* @return
* A static string containing the name of the MIDI manufacturer
* with the specified @a id.
*/
const char *
sysex_get_manufacturer(unsigned int id)
{

Loading…
Cancel
Save