tmk_core/protocol/midi/sysex_tools.h

   1 //midi for embedded chips,
   2 //Copyright 2010 Alex Norman
   3 //
   4 //This file is part of avr-midi.
   5 //
   6 //avr-midi is free software: you can redistribute it and/or modify
   7 //it under the terms of the GNU General Public License as published by
   8 //the Free Software Foundation, either version 3 of the License, or
   9 //(at your option) any later version.
  10 //
  11 //avr-midi is distributed in the hope that it will be useful,
  12 //but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 //MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 //GNU General Public License for more details.
  15 //
  16 //You should have received a copy of the GNU General Public License
  17 //along with avr-midi.  If not, see <http://www.gnu.org/licenses/>.
  18
  19 #ifndef SYSEX_TOOLS_H
  20 #define SYSEX_TOOLS_H
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 #include <inttypes.h>
  27
  28 /**
  29  * @file
  30  * @brief Sysex utility functions
  31  *
  32  * These functions are for converting data to and from a "midi-safe" format,
  33  * which can be use to send data with sysex messages.  Sysex messages may only
  34  * contain data where the to bit is not set.
  35  *
  36  * An "encoded" midi message is one that contains all of the data from its
  37  * original state, but does not have any of the top bits set.
  38  *
  39  * Every 7 bytes of decoded data is converted into 8 bytes of encoded data and
  40  * visa-versa.  If you'd like to operate on small segments, make sure that you
  41  * encode in 7 byte increments and decode in 8 byte increments.
  42  *
  43  */
  44
  45 /** @defgroup sysex_tools Sysex utility functions
  46  * @{
  47  */
  48
  49 /**
  50  * @brief Compute the length of a message after it is encoded.
  51  *
  52  * @param decoded_length The length, in bytes, of the message to encode.
  53  *
  54  * @return The length, in bytes, of the message after encodeing.
  55  */
  56 uint16_t sysex_encoded_length(uint16_t decoded_length);
  57
  58 /**
  59  * @brief Compute the length of a message after it is decoded.
  60  *
  61  * @param encoded_length The length, in bytes, of the encoded message.
  62  *
  63  * @return The length, in bytes, of the message after it is decoded.
  64  */
  65 uint16_t sysex_decoded_length(uint16_t encoded_length);
  66
  67 /**
  68  * @brief Encode data so that it can be transmitted safely in a sysex message.
  69  *
  70  * @param encoded The output data buffer, must be at least sysex_encoded_length(length) bytes long.
  71  * @param source The input buffer of data to be encoded.
  72  * @param length The number of bytes from the input buffer to encode.
  73  *
  74  * @return number of bytes encoded.
  75  */
  76 uint16_t sysex_encode(uint8_t *encoded, const uint8_t *source, uint16_t length);
  77
  78 /**
  79  * @brief Decode encoded data.
  80  *
  81  * @param decoded The output data buffer, must be at least sysex_decoded_length(length) bytes long.
  82  * @param source The input buffer of data to be decoded.
  83  * @param length The number of bytes from the input buffer to decode.
  84  *
  85  * @return number of bytes decoded.
  86  */
  87 uint16_t sysex_decode(uint8_t *decoded, const uint8_t *source, uint16_t length);
  88
  89 /**@}*/
  90
  91 #ifdef __cplusplus
  92 }
  93 #endif
  94
  95 #endif