apps/plugins/pdbox/PDa/extra/OSC-client.h

   1 /*
   2 Written by Matt Wright, The Center for New Music and Audio Technologies,
   3 University of California, Berkeley.  Copyright (c) 1996,97,98,99,2000,01,02,03
   4 The Regents of the University of California (Regents).
   5
   6 Permission to use, copy, modify, distribute, and distribute modified versions
   7 of this software and its documentation without fee and without a signed
   8 licensing agreement, is hereby granted, provided that the above copyright
   9 notice, this paragraph and the following two paragraphs appear in all copies,
  10 modifications, and distributions.
  11
  12 IN NO EVENT SHALL REGENTS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
  13 SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING
  14 OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF REGENTS HAS
  15 BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  16
  17 REGENTS SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  18 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 PURPOSE. THE SOFTWARE AND ACCOMPANYING DOCUMENTATION, IF ANY, PROVIDED
  20 HEREUNDER IS PROVIDED "AS IS". REGENTS HAS NO OBLIGATION TO PROVIDE
  21 MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  22 */
  23
  24 /*
  25
  26    OSC-client.h: library for constructing OpenSoundControl messages.
  27    Derived from SynthControl.h
  28    Author: Matt Wright
  29    Version 0.1: 6/13/97
  30    Version 0.2: 7/21/2000: Support for type-tagged messages
  31
  32
  33    General notes:
  34
  35    This library abstracts away the data format for the OpenSoundControl
  36    protocol.  Users of this library can construct OpenSoundControl packets
  37    with a function call interface instead of knowing how to lay out the bits.
  38
  39    All issues of memory allocation are deferred to the user of this library.
  40    There are two data structures that the user must allocate.  The first
  41    is the actual buffer that the message will be written into.  This buffer
  42    can be any size, but if it's too small there's a possibility that it
  43    will become overfull.  The other data structure is called an OSCbuf,
  44    and it holds all the state used by the library as it's constructing
  45    a buffer.
  46
  47    All procedures that have the possibility of an error condition return int,
  48    with 0 indicating no error and nonzero indicating an error.  The variable
  49    OSC_errorMessage will be set to point to a string containing an error
  50    message explaining what the problem is.
  51
  52 */
  53
  54
  55
  56 /* The int4byte type has to be a 4-byte integer.  You may have to
  57    change this to long or something else on your system.  */
  58 #ifdef __MWERKS__
  59   /* In Metrowerks you can set ints to be 2 or 4 bytes on 68K, but long is
  60      always 4 bytes */
  61     typedef long int4byte;
  62 #else
  63     typedef int int4byte;
  64 #endif
  65
  66 /* OSC_timetag.h */
  67
  68     typedef struct {
  69         int seconds;
  70         int fraction;
  71     } OSCTimeTag;
  72
  73 OSCTimeTag OSCTT_Immediately(void);
  74 OSCTimeTag OSCTT_PlusSeconds(OSCTimeTag original, float secondsOffset);
  75 OSCTimeTag OSCTT_CurrentTime(void);
  76
  77
  78
  79 /* The maximum depth of bundles within bundles within bundles within...
  80    This is the size of a static array.  If you exceed this limit you'll
  81    get an error message. */
  82 #define MAX_BUNDLE_NESTING 32
  83
  84
  85 /* Don't ever manipulate the data in the OSCbuf struct directly.  (It's
  86    declared here in the header file only so your program will be able to
  87    declare variables of type OSCbuf and have the right amount of memory
  88    be allocated.) */
  89
  90 typedef struct OSCbuf_struct {
  91     char *buffer;            /* The buffer to hold the OSC packet */
  92     int size;                /* Size of the buffer */
  93     char *bufptr;            /* Current position as we fill the buffer */
  94     int state;               /* State of partially-constructed message */
  95     int4byte *thisMsgSize;   /* Pointer to count field before
  96                                 currently-being-written message */
  97     int4byte *prevCounts[MAX_BUNDLE_NESTING];
  98                              /* Pointers to count field before each currently
  99                                 open bundle */
 100     int bundleDepth;         /* How many sub-sub-bundles are we in now? */
 101     char *typeStringPtr;    /* This pointer advances through the type
 102                                tag string as you add arguments. */
 103     int gettingFirstUntypedArg; /* nonzero if this message doesn't have
 104                                    a type tag and we're waiting for the 1st arg */
 105 } OSCbuf;
 106
 107
 108
 109 /* Initialize the given OSCbuf.  The user of this module must pass in the
 110    block of memory that this OSCbuf will use for a buffer, and the number of
 111    bytes in that block.  (It's the user's job to allocate the memory because
 112    you do it differently in different systems.) */
 113 void OSC_initBuffer(OSCbuf *buf, int size, char *byteArray);
 114
 115
 116 /* Reset the given OSCbuf.  Do this after you send out the contents of
 117    the buffer and want to start writing new data into it. */
 118 void OSC_resetBuffer(OSCbuf *buf);
 119
 120
 121 /* Is the buffer empty?  (I.e., would it be stupid to send the buffer
 122    contents to the synth?) */
 123 int OSC_isBufferEmpty(OSCbuf *buf);
 124
 125
 126 /* How much space is left in the buffer? */
 127 int OSC_freeSpaceInBuffer(OSCbuf *buf);
 128
 129 /* Does the buffer contain a valid OSC packet?  (Returns nonzero if yes.) */
 130 int OSC_isBufferDone(OSCbuf *buf);
 131
 132 /* When you're ready to send out the buffer (i.e., when OSC_isBufferDone()
 133    returns true), call these two procedures to get the OSC packet that's been
 134    assembled and its size in bytes.  (And then call OSC_resetBuffer() if you
 135    want to re-use this OSCbuf for the next packet.)  */
 136 char *OSC_getPacket(OSCbuf *buf);
 137 int OSC_packetSize(OSCbuf *buf);
 138
 139
 140
 141 /* Here's the basic model for building up OSC messages in an OSCbuf:
 142
 143     - Make sure the OSCbuf has been initialized with OSC_initBuffer().
 144
 145     - To open a bundle, call OSC_openBundle().  You can then write
 146       messages or open new bundles within the bundle you opened.
 147       Call OSC_closeBundle() to close the bundle.  Note that a packet
 148       does not have to have a bundle; it can instead consist of just a
 149       single message.
 150
 151
 152     - For each message you want to send:
 153
 154         - Call OSC_writeAddress() with the name of your message.  (In
 155           addition to writing your message name into the buffer, this
 156           procedure will also leave space for the size count of this message.)
 157
 158         - Alternately, call OSC_writeAddressAndTypes() with the name of
 159           your message and with a type string listing the types of all the
 160           arguments you will be putting in this message.
 161
 162         - Now write each of the arguments into the buffer, by calling one of:
 163             OSC_writeFloatArg()
 164             OSC_writeFloatArgs()
 165             OSC_writeIntArg()
 166             OSC_writeStringArg()
 167
 168         - Now your message is complete; you can send out the buffer or you can
 169           add another message to it.
 170 */
 171
 172 int OSC_openBundle(OSCbuf *buf, OSCTimeTag tt);
 173 int OSC_closeBundle(OSCbuf *buf);
 174 int OSC_closeAllBundles(OSCbuf *buf);
 175
 176 int OSC_writeAddress(OSCbuf *buf, char *name);
 177 int OSC_writeAddressAndTypes(OSCbuf *buf, char *name, char *types);
 178 int OSC_writeFloatArg(OSCbuf *buf, float arg);
 179 int OSC_writeFloatArgs(OSCbuf *buf, int numFloats, float *args);
 180 int OSC_writeIntArg(OSCbuf *buf, int4byte arg);
 181 int OSC_writeStringArg(OSCbuf *buf, char *arg);
 182
 183 extern char *OSC_errorMessage;
 184
 185 /* How many bytes will be needed in the OSC format to hold the given
 186    string?  The length of the string, plus the null char, plus any padding
 187    needed for 4-byte alignment. */
 188 int OSC_effectiveStringLength(char *string);
 189