PlatformIO package of the Teensy core framework compatible with GCC 10 & C++20
您最多选择25个主题 主题必须以字母或数字开头,可以包含连字符 (-),并且长度不得超过35个字符

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355
  1. # OSCMessage
  2. An OSCMessage is an address followed by any number of data. Messages can have mixed data types like an integer followed by a string followed by a float, etc.
  3. ## Constructor
  4. OSCMessages can be constructed with or without an address.
  5. ### `OSCMessage(const char *)`
  6. Set the address of the message in the constructor
  7. ```C++
  8. OSCMessage msg("/address");
  9. ```
  10. ### `OSCMessage()`
  11. An OSCMessage constructed without an address is not valid until it is given an address.
  12. ## Add/Set Data
  13. ### `OSCMessage& add(int i)`
  14. Append an integer to the OSCMessage.
  15. ```C++
  16. msg.add(1);
  17. ```
  18. ### `OSCMessage& add(float f)`
  19. Append a float to the OSCMessage.
  20. ### `OSCMessage& add(bool b)`
  21. Append a boolean to the OSCMessage.
  22. ### `OSCMessage& add(const char * str)`
  23. Append a string to the OSCMessage.
  24. ```C++
  25. msg.add("hello");
  26. ```
  27. ### `OSCMessage& add(uint8_t * blob, int length)`
  28. Append a [blob](https://en.wikipedia.org/wiki/Binary_large_object) to the OSCMessage. Pass in the length of the blob as the second argument.
  29. ### `OSCMessage& set(int position, Type data)`
  30. Replace the data at the given position with the data. `Type` can be any of the supported data types.
  31. ```C++
  32. //replace the data at the 0th position with a string
  33. msg.set(0, "string");
  34. ```
  35. ### `OSCMessage& set(int position, uint8_t * data, int length)`
  36. Set the data at the given position to be a blob of the given length.
  37. ### `OSCMessage& add(double d)`
  38. Append a double precision floating point value to the OSCMessage. NOTE: double is not supported on most Arduino platforms. It will fall back to float, when double is not supported.
  39. ## Get Data
  40. ### `int getInt(int position)`
  41. Returns the integer at the given position
  42. ```C++
  43. //returns the integer at the third position
  44. msg.getInt(2);
  45. ```
  46. ### `float getFloat(int position)`
  47. Returns the float at the given position
  48. ### `bool getBoolean(int position)`
  49. Returns the boolean at the given position
  50. ### `double getDouble(int position)`
  51. Returns the double at the given position. NOTE: double is not supported by most Arduino platforms. This will fail silently if double is not supported.
  52. ### `int getString(int position, char * str, int length)`
  53. Copy `length` number of characters from the given position into the `str` buffer. Returns the number of copied characters.
  54. ```C++
  55. char str[8];
  56. //fill str with 8 characters from the 0th datum
  57. msg.getString(0, str, 8);
  58. ```
  59. ### `int getBlob(int position, uint8_t * blob, int length)`
  60. Copy `length` number of bytes from the given position into the `blob` buffer. Returns the number of copied bytes.
  61. ### `char getType(int position)`
  62. Returns the type of the data at the given position.
  63. ```C++
  64. OSCMessage msg("/address");
  65. msg.add(1);
  66. msg.getType(0); //-> returns 'i'
  67. ```
  68. ## Query Data
  69. ### `bool isInt(int position)`
  70. Returns `true` when the data at the given position is an integer.
  71. ### `bool isFloat(int position)`
  72. Returns `true` when the data at the given position is a float.
  73. ### `bool isBoolean(int position)`
  74. Returns `true` when the data at the given position is a boolean.
  75. ### `bool isString(int position)`
  76. Returns `true` when the data at the given position is a string.
  77. ### `bool isBlob(int position)`
  78. Returns `true` when the data at the given position is a blob.
  79. ### `bool isDouble(int position)`
  80. Returns `true` when the data at the given position is a double.
  81. ### `int size()`
  82. Returns the number of data the OSCMessage has.
  83. ### `int bytes()`
  84. Returns the size of the OSCMessage in bytes (if everything is 32-bit aligned).
  85. ## Address
  86. ### `OSCMessage& setAddress(const char * address)`
  87. Set the address of the OSCMessage.
  88. ### `OSCMessage& getAddress(char * str, int offset=0)`
  89. Copy the address of the OSCMessage into the `str` buffer. Copy after the given address offset (defaults to 0).
  90. ## Send Receive
  91. ### `OSCMessage& send(Print &p)`
  92. Output the message to the given transport layer which extends Arduino's [Print class](http://playground.arduino.cc/Code/Printclass) like the `Serial` out.
  93. ```C++
  94. msg.send(SLIPSerial);
  95. ```
  96. ### `OSCMessage& fill(uint8_t incomingByte)`
  97. Add the incoming byte to the OSCMessage where it will be decoded.
  98. ### `OSCMessage& fill(uint8_t * bytes, int length)`
  99. Add and decode the array of bytes as an OSCMessage.
  100. ## Matching / Routing
  101. ### `bool fullMatch( const char * pattern, int offset = 0)`
  102. Returns true if the message's address is a full match to the given pattern after the offset.
  103. ```C++
  104. OSCMessage msg("/a/0");
  105. msg.fullMatch("/0", 2); // ->returns true
  106. ```
  107. ### `int match( const char * pattern, int offset = 0)`
  108. Returns the number of matched characters of the message's address against the given pattern (optionally with an offset). Unlike `fullMatch`, `match` allows for partial matches
  109. ```C++
  110. OSCMessage msg("/a/0");
  111. msg.match("/a"); // ->returns 2
  112. ```
  113. ### `bool dispatch(const char * pattern, void (*callback)(OSCMessage &), int offset = 0)`
  114. Invoke the given callback if the address if a full match with the pattern (after the offset). The message is passed into the callback function. Returns true if the pattern was a match and the callback function was invoked.
  115. ### `bool route(const char * pattern, void (*callback)(OSCMessage &, int), int offset = 0)`
  116. Invoke the given callback if the address if a match with the pattern (after the offset). The OSCMessage and the address offset is passed into the callback function. Returns true if the pattern was a match and the callback function was invoked.
  117. ```C++
  118. //define a callback function for matching messages
  119. void routeCallback(OSCMessage & message, int addressOffset){
  120. //do something with the message...
  121. //with the message below, the addressOffset will equal 2.
  122. }
  123. OSCMessage msg("/a/0");
  124. msg.route("/a", routeCallback);
  125. ```
  126. ## Address Patterns
  127. OSCMessages can be constructed with patterns and later routed or dispatched against addresses.
  128. ```C++
  129. OSCMessage msg("/{a,b}/[0-9]");
  130. msg.route("/a/0", a0_callback); //matches the address
  131. msg.route("/b/2", b2_callback); //matches the address
  132. msg.route("/c/11", c11_callback); //not invoked
  133. ```
  134. # OSCBundle
  135. A bundle is a group of OSCMessages with a timetag.
  136. ## Constructor
  137. ### `OSCBundle()`
  138. Construct an empty OSCBundle.
  139. ### `OSCBundle(osctime_t = zerotime)`
  140. Construct the bundle with a timetag. timetag defaults to 0 (immediate).
  141. ## Add OSCMessage
  142. ### `OSCMessage & add(char * address)`
  143. Create a new message with the given address in the bundle. Returns the newly created OSCMessage.
  144. ```C++
  145. //create a new OSCMessage and add some data to it
  146. bundle.add("/message").add("data");
  147. ```
  148. ## Get OSCMessage
  149. ### `OSCMessage * getOSCMessage(int position)`
  150. Return the OSCMessage in the bundle at the given position.
  151. ```C++
  152. OSCBundle bundle
  153. bundle.add("/a");
  154. bundle.add("/b");
  155. bundle.getOSCMessage(0);//returns the OSCMessage with the address "/a".
  156. ```
  157. ### `OSCMessage * getOSCMessage(char * address)`
  158. Return the OSCMessage in the bundle which matches the given address.
  159. ```C++
  160. OSCBundle bundle
  161. bundle.add("/a");
  162. bundle.add("/b");
  163. bundle.getOSCMessage("/b");//returns the second OSCMessage in the bundle
  164. ```
  165. ## Routing
  166. ### `bool dispatch(const char * pattern, void (*callback)(OSCMessage&), int offset = 0)`
  167. Invoke the callback function with all messages in the bundle which match the given pattern after the offset.
  168. ```C++
  169. bundle.add("/a/0");
  170. bundle.add("/b/0");
  171. bundle.dispatch("/0", dispatchZero, 2);
  172. ```
  173. ### `bool route(const char * pattern, void (*callback)(OSCMessage &, int), int offset = 0)`
  174. Invoke the callback with all the OSCMessages in the bundle which match the given pattern. `route` allows for partial matches.
  175. ## Send/Receive
  176. ### `OSCBundle& send(Print &p)`
  177. Output the bundle to the given transport layer which extends Arduino's [Print class](http://playground.arduino.cc/Code/Printclass) (such as `SLIPSerial` out).
  178. ```C++
  179. bundle.send(SLIPSerial);
  180. ```
  181. ### `OSCBundle& fill(uint8_t incomingByte)`
  182. Add the incoming byte to the OSCBundle where it will be decoded.
  183. ### `OSCBundle& fill(uint8_t * bytes, int length)`
  184. Add and decode the array of bytes as an OSCBundle.
  185. # Chaining
  186. Many methods return `this` which enables you to string together multiple commands.
  187. This technique allows multiple lines to be condensed into one:
  188. ```C++
  189. bundle.add("/address").add("data").add(0).send(SLIPSerial).empty();
  190. ```