common/JackMidiWriteQueue.h

   1 /*
   2 Copyright (C) 2010 Devin Anderson
   3
   4 This program is free software; you can redistribute it and/or modify
   5 it under the terms of the GNU Lesser General Public License as published by
   6 the Free Software Foundation; either version 2.1 of the License, or
   7 (at your option) any later version.
   8
   9 This program is distributed in the hope that it will be useful,
  10 but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 GNU Lesser General Public License for more details.
  13
  14 You should have received a copy of the GNU Lesser General Public License
  15 along with this program; if not, write to the Free Software
  16 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  17
  18 */
  19
  20 #ifndef __JackMidiWriteQueue__
  21 #define __JackMidiWriteQueue__
  22
  23 #include "JackMidiPort.h"
  24
  25 namespace Jack {
  26
  27     /**
  28      * Interface for classes that act as write queues for MIDI messages.  Write
  29      * queues are used by processors to transfer data to the next processor.
  30      */
  31
  32     class SERVER_EXPORT JackMidiWriteQueue {
  33
  34     public:
  35
  36         enum EnqueueResult {
  37             BUFFER_FULL,
  38             BUFFER_TOO_SMALL,
  39             EVENT_EARLY,
  40             EN_ERROR,
  41             OK
  42         };
  43
  44         virtual ~JackMidiWriteQueue();
  45
  46         /**
  47          * Enqueues a data packet in the write queue of `size` bytes contained
  48          * in `buffer` that will be sent the absolute time specified by `time`.
  49          * This method should not block unless 1.) this write queue represents
  50          * the actual outbound MIDI connection, 2.) the MIDI event is being
  51          * sent *now*, meaning that `time` is less than or equal to *now*, and
  52          * 3.) the method is *not* being called in the process thread.  The
  53          * method should return `OK` if the event was enqueued, `BUFFER_FULL`
  54          * if the write queue isn't able to accept the event right now,
  55          * `BUFFER_TOO_SMALL` if this write queue will never be able to accept
  56          * the event because the event is too large, `EVENT_EARLY` if this
  57          * queue cannot schedule events ahead of time, and `EN_ERROR` if an error
  58          * occurs that cannot be specified by another return code.
  59          */
  60
  61         virtual EnqueueResult
  62         EnqueueEvent(jack_nframes_t time, size_t size,
  63                      jack_midi_data_t *buffer) = 0;
  64
  65         /**
  66          * A wrapper method for the `EnqueueEvent` method above.  The optional
  67          * 'frame_offset' argument is an amount of frames to add to the event's
  68          * time.
  69          */
  70
  71         inline EnqueueResult
  72         EnqueueEvent(jack_midi_event_t *event, jack_nframes_t frame_offset=0)
  73         {
  74             return EnqueueEvent(event->time + frame_offset, event->size,
  75                                 event->buffer);
  76         }
  77
  78     };
  79
  80 }
  81
  82 #endif