OSCBundle.h

00001 /*
00002  Written by Yotam Mann, The Center for New Music and Audio Technologies,
00003  University of California, Berkeley.  Copyright (c) 2012, 2013, The Regents of
00004  the University of California (Regents).
00005  
00006  Permission to use, copy, modify, distribute, and distribute modified versions
00007  of this software and its documentation without fee and without a signed
00008  licensing agreement, is hereby granted, provided that the above copyright
00009  notice, this paragraph and the following two paragraphs appear in all copies,
00010  modifications, and distributions.
00011  
00012  IN NO EVENT SHALL REGENTS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
00013  SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING
00014  OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF REGENTS HAS
00015  BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00016  
00017  REGENTS SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
00018  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00019  PURPOSE. THE SOFTWARE AND ACCOMPANYING DOCUMENTATION, IF ANY, PROVIDED
00020  HEREUNDER IS PROVIDED "AS IS". REGENTS HAS NO OBLIGATION TO PROVIDE
00021  MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
00022  
00023 
00024  */
00025 
00026 #ifndef OSCBUNDLE_h
00027 #define OSCBUNDLE_h
00028 
00029 #include "OSCMessage.h"
00030 #include "OSCTiming.h"
00031 
00032 
00033 extern osctime_t zerotime;
00034 class OSCBundle
00035 {
00036 
00037 private:
00038 
00039 /*=============================================================================
00040     PRIVATE VARIABLES
00041 =============================================================================*/
00042 
00043     //the array of messages contained in the bundle
00044     OSCMessage ** messages;
00045 
00046     //the number of messages in the array
00047     int numMessages;
00048     
00049     osctime_t timetag;
00050     
00051     //error codes
00052     OSCErrorCode error;
00053     
00054 /*=============================================================================
00055  DECODING INCOMING BYTES
00056  =============================================================================*/
00057     
00058     //the decoding states for incoming bytes
00059     enum DecodeState {
00060         STANDBY,
00061         HEADER,
00062         TIMETAG,
00063         MESSAGE_SIZE,
00064         MESSAGE,
00065     } decodeState;
00066     
00067     //stores incoming bytes until they can be decoded
00068     uint8_t * incomingBuffer;
00069     int incomingBufferSize;
00070     
00071     //the size of the incoming message
00072     int incomingMessageSize;
00073     
00074     //adds a byte to the buffer
00075     void addToIncomingBuffer(uint8_t);
00076     //clears the incoming buffer
00077     void clearIncomingBuffer();
00078     
00079     //decoding functions
00080     void decode(uint8_t);
00081     void decodeTimetag();
00082     void decodeHeader();
00083     void decodeMessage(uint8_t);
00084     
00085     //just a placeholder while filling
00086     OSCMessage & add();
00087 
00088 
00089 public:
00090 
00091 /*=============================================================================
00092     CONSTRUCTORS / DESTRUCTOR
00093 =============================================================================*/
00094         
00095     //default timetag of
00096     OSCBundle(osctime_t = zerotime);
00097 
00098     //DESTRUCTOR
00099     ~OSCBundle();
00100 
00101     //clears all of the OSCMessages inside
00102     OSCBundle& empty();
00103     
00104 /*=============================================================================
00105     SETTERS
00106 =============================================================================*/
00107     
00108     //start a new OSC Message in the bundle
00109     OSCMessage & add(const char * address);
00110     //add with nothing in it produces an invalid osc message
00111     //copies an existing message into the bundle
00112     OSCMessage & add(OSCMessage & msg);
00113 
00114 
00115 
00116     template <typename T>
00117     OSCBundle& setTimetag(T t){
00118         timetag = (osctime_t) t;
00119         return *this;
00120     }
00121     //sets the timetag from a buffer
00122     OSCBundle& setTimetag(uint8_t * buff){
00123         memcpy(&timetag, buff, 8);
00124         return *this;
00125     }
00126 
00127 /*=============================================================================
00128     GETTERS
00129  =============================================================================*/
00130 
00131     //gets the message the matches the address string
00132     //will do regex matching
00133     OSCMessage * getOSCMessage(char * addr);
00134     
00135     //get message by position
00136     OSCMessage * getOSCMessage(int position);
00137     
00138 /*=============================================================================
00139     MATCHING
00140 =============================================================================*/
00141 
00142     //if the bundle contains a message that matches the pattern, 
00143     //call the function callback on that message
00144     bool dispatch(const char * pattern, void (*callback)(OSCMessage&), int = 0);
00145     
00146     //like dispatch, but allows for partial matches
00147     //the address match offset is sent as an argument to the callback
00148     bool route(const char * pattern, void (*callback)(OSCMessage&, int), int = 0);
00149     
00150 /*=============================================================================
00151      SIZE
00152 =============================================================================*/
00153     //returns the number of messages in the bundle;
00154     int size();
00155     
00156 /*=============================================================================
00157     ERROR
00158  =============================================================================*/
00159     
00160     bool hasError();
00161     
00162     OSCErrorCode getError();
00163     
00164 /*=============================================================================
00165     SENDING
00166  =============================================================================*/
00167     
00168     OSCBundle& send(UDPSocket &p, const SocketAddress &address);
00169     
00170 /*=============================================================================
00171     FILLING
00172  =============================================================================*/
00173     
00174     OSCBundle& fill(uint8_t incomingByte);
00175     
00176     OSCBundle& fill(const uint8_t * incomingBytes, int length);
00177 };
00178 
00179 #endif