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