media/midi/midi_message_queue.h

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MEDIA_MIDI_MIDI_MESSAGE_QUEUE_H_
   6 #define MEDIA_MIDI_MIDI_MESSAGE_QUEUE_H_
   7
   8 #include <deque>
   9 #include <vector>
  10
  11 #include "base/basictypes.h"
  12 #include "media/midi/midi_export.h"
  13
  14 namespace media {
  15 namespace midi {
  16
  17 // A simple message splitter for possibly unsafe/corrupted MIDI data stream.
  18 // This class allows you to:
  19 // - maintain fragmented MIDI message.
  20 // - skip any invalid data sequence.
  21 // - reorder MIDI messages so that "System Real Time Message", which can be
  22 //   inserted at any point of the byte stream, is placed at the boundary of
  23 //   complete MIDI messages.
  24 // - (Optional) reconstruct complete MIDI messages from data stream where
  25 //   MIDI status byte is abbreviated (a.k.a. "running status").
  26 //
  27 // Example (pseudo message loop):
  28 //   MidiMessageQueue queue(true);  // true to support "running status"
  29 //   while (true) {
  30 //     if (is_incoming_midi_data_available()) {
  31 //       std::vector<uint8> incoming_data;
  32 //       read_incoming_midi_data(&incoming_data)
  33 //       queue.Add(incoming_data);
  34 //     }
  35 //     while (true) {
  36 //       std::vector<uint8> next_message;
  37 //       queue.Get(&next_message);
  38 //       if (!next_message.empty())
  39 //         dispatch(next_message);
  40 //     }
  41 //   }
  42 class MIDI_EXPORT MidiMessageQueue {
  43  public:
  44   // Initializes the queue. Set true to |allow_running_status| to enable
  45   // "MIDI running status" reconstruction.
  46   explicit MidiMessageQueue(bool allow_running_status);
  47   ~MidiMessageQueue();
  48
  49   // Enqueues |data| to the internal buffer.
  50   void Add(const std::vector<uint8>& data);
  51   void Add(const uint8* data, size_t length);
  52
  53   // Fills the next complete MIDI message into |message|. If |message| is
  54   // not empty, the data sequence falls into one of the following types of
  55   // MIDI message.
  56   // - Single "Channel Voice Message"    (w/o "System Real Time Messages")
  57   // - Single "Channel Mode Message"     (w/o "System Real Time Messages")
  58   // - Single "System Exclusive Message" (w/o "System Real Time Messages")
  59   // - Single "System Common Message"    (w/o "System Real Time Messages")
  60   // - Single "System Real Time message"
  61   // |message| is empty if there is no complete MIDI message any more.
  62   void Get(std::vector<uint8>* message);
  63
  64  private:
  65   std::deque<uint8> queue_;
  66   std::vector<uint8> next_message_;
  67   const bool allow_running_status_;
  68   DISALLOW_COPY_AND_ASSIGN(MidiMessageQueue);
  69 };
  70
  71 }  // namespace midi
  72 }  // namespace media
  73
  74 #endif  // MEDIA_MIDI_MIDI_MESSAGE_QUEUE_H_