Browse Source

Document return values in the microx module

Add Doxygen-like comments to all public functions in microx.c
to document all possible returned values.
develop
Damien Goutte-Gattat 8 years ago
parent
commit
121829a3f9
  1. 4
      src/kmxtool.c
  2. 92
      src/microx.c

4
src/kmxtool.c

@ -313,7 +313,7 @@ main(int argc, char **argv)
int n;
dump.load = 0;
if ( kmx_microx_parse_dump_request(param, &dump) < 0 )
if ( kmx_microx_parse_dump_request(param, &dump) == -1 )
errx(EXIT_FAILURE, "invalid dump request: %s", param);
n = kmx_microx_get_dump_size(&dump);
@ -330,7 +330,7 @@ main(int argc, char **argv)
ssize_t n;
dump.load = 1;
if ( kmx_microx_parse_dump_request(param, &dump) < 0 )
if ( kmx_microx_parse_dump_request(param, &dump) == -1 )
errx(EXIT_FAILURE, "invalid load request: %s", param);
data = NULL;

92
src/microx.c

@ -25,6 +25,17 @@
#include <microx.h>
#include <sysex.h>
/**
* @return
* - 0 if the port is connected to a device which successfully
* identified itself as a microX device;
* - @e KMX_IO_ERROR if an I/O error occured;
* - @e KMX_INVALID_REPLY if the device replied incorrectly:
* - @e KMX_NOT_KORG is the device did not identify itself as
* a Korg device;
* - @e KMX_NOT_MICROX is the device did not identify itself
* as a microX device.
*/
int
kmx_microx_identify(midi_io_t *midi,
struct kmx_microx_version *version)
@ -32,7 +43,7 @@ kmx_microx_identify(midi_io_t *midi,
int n;
midi_device_id_t devid;
if ( (n = sysex_identify(midi, &devid)) < 0 )
if ( (n = sysex_identify(midi, &devid)) == -1 )
return KMX_IO_ERROR;
else if ( n == 0 )
return KMX_INVALID_REPLY;
@ -53,6 +64,13 @@ kmx_microx_identify(midi_io_t *midi,
return 0;
}
/**
* @return
* - 0 if the query was successful;
* - @e KMX_IO_ERROR if an I/O error occured;
* - @e KMX_NOT_KORG if the reply did not come from a Korg device;
* - @e KMX_INVALID_REPLY if the device replied incorrectly.
*/
int
kmx_microx_query_status(midi_io_t *midi,
struct kmx_microx_status *s)
@ -67,7 +85,7 @@ kmx_microx_query_status(midi_io_t *midi,
0xF7 /* SysEx message end */ };
if ( (n = sysex_query(midi, query, sizeof(query),
reply, sizeof(reply))) < 0 )
reply, sizeof(reply))) == -1 )
return KMX_IO_ERROR;
/*
@ -163,6 +181,10 @@ kmx_microx_query_status(midi_io_t *midi,
return 0;
}
/**
* @return
* A static string containing the user-readable error message.
*/
const char *
kmx_microx_error(midi_io_t *midi, int e)
{
@ -233,6 +255,11 @@ static struct {
{ 0x1E, 0x6E }
};
/**
* @return
* - The positive integer value contained in @a s;
* - -1 if @a s could not be parsed as a positive integer value.
*/
static int
parse_int(const char *s)
{
@ -251,6 +278,11 @@ parse_int(const char *s)
return val;
}
/**
* @return
* - 0 if the dump request was successfully parsed.
* - -1 if the dump request is invalid.
*/
int
kmx_microx_parse_dump_request(const char *what, struct kmx_microx_dump *dump)
{
@ -343,6 +375,10 @@ kmx_microx_parse_dump_request(const char *what, struct kmx_microx_dump *dump)
return ret;
}
/**
* @return
* The expected size of the specified data dump.
*/
size_t
kmx_microx_get_dump_size(struct kmx_microx_dump *dump)
{
@ -393,6 +429,13 @@ kmx_microx_get_dump_size(struct kmx_microx_dump *dump)
return s;
}
/**
* @return
* - 0 if the operation was successful;
* - -1 if an error occured.
*
* The current implementation is always successful.
*/
static int
get_dump_parameters(struct kmx_microx_dump *dump,
unsigned char *buffer)
@ -469,6 +512,14 @@ get_dump_parameters(struct kmx_microx_dump *dump,
return 0;
}
/**
* @return
* - The count of data bytes read and stored in the @a data buffer;
* - @e KMX_IO_ERROR if an I/O error occured;
* - @e KMX_NOT_KORG if the reply did not come from a Korg device;
* - @e KMX_NOT_MICROX if the reply did not come from a microX device;
* - @e KMX_INVALID_REPLY if the device replied incorrectly.
*/
int
kmx_microx_read_dump(midi_io_t *midi,
unsigned char reply_code,
@ -482,7 +533,7 @@ kmx_microx_read_dump(midi_io_t *midi,
j = k = m = 0;
do {
if ( (n = sysex_read(midi, reply, sizeof(reply))) < 0 )
if ( (n = sysex_read(midi, reply, sizeof(reply))) == -1 )
return KMX_IO_ERROR;
i = 0;
@ -529,6 +580,17 @@ kmx_microx_read_dump(midi_io_t *midi,
return j - 1; /* Remove SysEx terminating byte. */
}
/**
* @return
* - The number of bytes read and stored in the @a data buffer;
* - @e KMX_IO_ERROR if an I/O error occured;
* - @e KMX_INVALID_QUERY if the dump query was invalid;
* - @e KMX_BUFFER_TOO_SMALL if the provided buffer was not large
* enough to hold the expected data dump;
* - @e KMX_NOT_KORG if the reply did not come from a Korg device;
* - @e KMX_NOT_MICROX if the reply did not come from a microX device;
* - @e KMX_INVALID_REPLY if the device replied incorrectly.
*/
int
kmx_microx_dump(midi_io_t *midi,
struct kmx_microx_dump *dump,
@ -546,18 +608,34 @@ kmx_microx_dump(midi_io_t *midi,
0x00, /* Dump parameter 3 */
0xF7 /* SysEx message end */ };
if ( get_dump_parameters(dump, &(query[4])) < 0 )
if ( get_dump_parameters(dump, &(query[4])) == -1 )
return KMX_INVALID_QUERY;
if ( len < kmx_microx_get_dump_size(dump) )
return KMX_BUFFER_TOO_SMALL;
if ( (n = midi_write(midi, query, sizeof(query))) < 0 )
if ( (n = midi_write(midi, query, sizeof(query))) == -1 )
return KMX_IO_ERROR;
return kmx_microx_read_dump(midi, dump_codes[dump->type].reply, data, len);
}
/**
* @return
* - @e KMX_OK if the load operation completed successfully;
* - @e KMX_IO_ERROR if an I/O error occured;
* - @e KMX_INVALID_QUERY if the load query was invalid;
* - @e KMX_BUFFER_TOO_SMALL if the size of the @a data buffer did
* not match the expected size for the specified memory slot;
* - @e KMX_INVALID_REPLY if the device replied unexpectedly;
* - @e KMX_DEST_MEM_PROTECTED if the specified memory slot was
* write-protected;
* - @e KMX_DEST_PRG_MISSING if the specified memory slot did not
* exist;
* - @e KMX_MEM_OVERFLOW if a memory error occured on the device;
* - @e KMX_OTHER_ERROR if an unspecified error occured on the
* device.
*/
int
kmx_microx_load(midi_io_t *midi,
struct kmx_microx_dump *dump,
@ -576,7 +654,7 @@ kmx_microx_load(midi_io_t *midi,
0x00, /* Dump parameter 3 */ };
unsigned char reply[7];
if ( get_dump_parameters(dump, &(buffer[4])) < 0 )
if ( get_dump_parameters(dump, &(buffer[4])) == -1 )
return KMX_INVALID_QUERY;
if ( len < kmx_microx_get_dump_size(dump) )
@ -594,7 +672,7 @@ kmx_microx_load(midi_io_t *midi,
buffer[n++] = data[m++] & 0x7F;
if ( n == sizeof(buffer) ) {
if ( midi_write(midi, buffer, n) < 0 )
if ( midi_write(midi, buffer, n) == -1 )
status = KMX_IO_ERROR;
n = 0;
}

Loading…
Cancel
Save