1High-level OSC API(3) Liblo High-level OSC API(3)
2
6 High-level OSC API -
7 Data Structures
9 struct lo_timetag
10 A structure to store OSC TimeTag values.
11 union lo_arg
12 Union used to read values from incoming messages.
13 Defines
15 #define LO_TT_IMMEDIATE ((lo_timetag){0U,0U})
16 Enumerations
18 enum lo_type { LO_INT32 = 'i', LO_FLOAT = 'f', LO_STRING = 's',
19 LO_BLOB = 'b', LO_INT64 = 'h', LO_TIMETAG = 't', LO_DOUBLE =
20 'd', LO_SYMBOL = 'S', LO_CHAR = 'c', LO_MIDI = 'm', LO_TRUE =
21 'T', LO_FALSE = 'F', LO_NIL = 'N', LO_INFINITUM = 'I' }
22 An enumeration of the OSC types liblo can send and receive.
23 Functions
25 lo_address lo_address_new (const char *host, const char *port)
26 Declare an OSC destination, given IP address and port number.
27 lo_address lo_address_new_from_url (const char *url)
28 Create a lo_address object from an OSC URL.
29 void lo_address_free (lo_address t)
30 Free the memory used by the lo_address object.
31 int lo_send (lo_address targ, const char *path, const char *type,...)
32 Send a OSC formatted message to the address specified.
33 int lo_send_from (lo_address targ, lo_server from, lo_timetag ts, const
34 char *path, const char *type,...)
35 Send a OSC formatted message to the address specified, from the
36 same socket as the specificied server.
37 int lo_send_timestamped (lo_address targ, lo_timetag ts, const char
38 *path, const char *type,...)
39 Send a OSC formatted message to the address specified, scheduled to
40 be dispatch at some time in the future.
41 int lo_address_errno (lo_address a)
42 Return the error number from the last failed lo_send or
43 lo_address_new call.
44 const char * lo_address_errstr (lo_address a)
45 Return the error string from the last failed lo_send or
46 lo_address_new call.
47 lo_server_thread lo_server_thread_new (const char *port, lo_err_handler
48 err_h)
49 Create a new server thread to handle incoming OSC messages.
50 void lo_server_thread_free (lo_server_thread st)
51 Free memory taken by a server thread.
52 lo_method lo_server_thread_add_method (lo_server_thread st, const char
53 *path, const char *typespec, lo_method_handler h, void *user_data)
54 Add an OSC method to the specifed server thread.
55 void lo_server_thread_del_method (lo_server_thread st, const char
56 *path, const char *typespec)
57 Delete an OSC method from the specifed server thread.
58 void lo_server_thread_start (lo_server_thread st)
59 Start the server thread.
60 void lo_server_thread_stop (lo_server_thread st)
61 Stop the server thread.
62 int lo_server_thread_get_port (lo_server_thread st)
63 Return the port number that the server thread has bound to.
64 char * lo_server_thread_get_url (lo_server_thread st)
65 Return a URL describing the address of the server thread.
66 lo_server lo_server_thread_get_server (lo_server_thread st)
67 Return the lo_server for a lo_server_thread.
68 int lo_server_thread_events_pending (lo_server_thread st)
69 Return true if there are scheduled events (eg. from bundles)
70 waiting to be dispatched by the thread.
71 lo_blob lo_blob_new (int32_t size, void *data)
72 Create a new OSC blob type.
73 void lo_blob_free (lo_blob b)
74 Free the memory taken by a blob.
75 uint32_t lo_blob_datasize (lo_blob b)
76 Return the ammount of valid data in a lo blob object.
77 void * lo_blob_dataptr (lo_blob b)
78 Return a pointer to the start of the blob data to allow contents to
79 be changed.
80
82 Defines the high-level API functions neccesary to implement OSC
83 support. Should be adequate for most applications, but ig you require
84 lower level control you can use the functions defined in lo_lowlevel.h.
85
87 #define LO_TT_IMMEDIATE ((lo_timetag){0U,0U})
89 enum lo_type
90 An enumeration of the OSC types liblo can send and receive.
91 The value of the enumeration is the typechar used to tag messages and
93 to specify arguemnts with lo_send().
94 Enumerator:
96 LO_INT32
98 32 bit signed integer.
99 LO_FLOAT
101 32 bit IEEE-754 float.
102 LO_STRING
104 Standard C, NULL terminated string.
105 LO_BLOB
107 OSC binary blob type. Accessed using the lo_blob_*() functions.
108 LO_INT64
110 64 bit signed integer.
111 LO_TIMETAG
113 OSC TimeTag type, represented by the lo_timetag structure.
114 LO_DOUBLE
116 64 bit IEEE-754 double.
117 LO_SYMBOL
119 Standard C, NULL terminated, string. Used in systems which
120 distinguish strings and symbols.
121 LO_CHAR
123 Standard C, 8 bit, char variable.
124 LO_MIDI
126 A 4 byte MIDI packet.
127 LO_TRUE
129 Sybol representing the value True.
130 LO_FALSE
132 Sybol representing the value False.
133 LO_NIL Sybol representing the value Nil.
135 LO_INFINITUM
137 Sybol representing the value Infinitum.
138
140 int lo_address_errno (lo_address a)
141 Return the error number from the last failed lo_send or lo_address_new
142 call.
143 const char* lo_address_errstr (lo_address a)
145 Return the error string from the last failed lo_send or lo_address_new
146 call.
147 void lo_address_free (lo_address t)
149 Free the memory used by the lo_address object.
150 lo_address lo_address_new (const char * host, const char * port)
152 Declare an OSC destination, given IP address and port number.
153 Parameters:
155 host An IP address or number, or NULL for the local machine.
156 port a decimal port number or service name.
157 The lo_address object may be used as the target of OSC messages.
159 Note: if you wish to receive replies from the target of this address,
161 you must first create a lo_server_thread or lo_server object which will
162 receive the replies. The last lo_server(_thread) object creted will be
163 the receiver.
164 lo_address lo_address_new_from_url (const char * url)
166 Create a lo_address object from an OSC URL.
167 example: osc.udp://localhost:4444/my/path/
169 void* lo_blob_dataptr (lo_blob b)
171 Return a pointer to the start of the blob data to allow contents to be
172 changed.
173 uint32_t lo_blob_datasize (lo_blob b)
175 Return the ammount of valid data in a lo blob object.
176 If you want to know the storage size, use lo_arg_size().
178 void lo_blob_free (lo_blob b)
180 Free the memory taken by a blob.
181 lo_blob lo_blob_new (int32_t size, void * data)
183 Create a new OSC blob type.
184 Parameters:
186 size The ammount of space to allocate in the blob structure.
187 data The data that will be used to initialise the blob, should be
188 size bytes long.
189 int lo_send (lo_address targ, const char * path, const char * type, ...)
191 Send a OSC formatted message to the address specified.
192 Parameters:
194 targ The target OSC address
195 path The OSC path the message will be delivered to
196 type The types of the data items in the message, types are defined
197 in lo_types_common.h
198 ... The data values to be transmitted. The types of the arguments
199 passed here must agree with the types specified in the type
200 parameter.
201 example:
203 lo_send(t, '/foo/bar', 'ff', 0.1f, 23.0f);
204 returns -1 on failure.
206 int lo_send_from (lo_address targ, lo_server from, lo_timetag ts, const
208 char * path, const char * type, ...)
209 Send a OSC formatted message to the address specified, from the same
210 socket as the specificied server.
211 Parameters:
213 targ The target OSC address
214 from The server to send message from (can be NULL to use new
215 socket)
216 ts The OSC timetag timestamp at which the message will be processed
217 (can be LO_TT_IMMEDIATE if you don't want to attach a timetag)
218 path The OSC path the message will be delivered to
219 type The types of the data items in the message, types are defined
220 in lo_types_common.h
221 ... The data values to be transmitted. The types of the arguments
222 passed here must agree with the types specified in the type
223 parameter.
224 example:
226 serv = lo_server_new(NULL, err);
227 lo_server_add_method(serv, '/reply', 'ss', reply_handler, NULL);
228 lo_send_from(t, serv, LO_TT_IMMEDIATE, '/foo/bar', 'ff', 0.1f, 23.0f);
229 on success returns the number of bytes sent, returns -1 on failure.
231 int lo_send_timestamped (lo_address targ, lo_timetag ts, const char * path,
233 const char * type, ...)
234 Send a OSC formatted message to the address specified, scheduled to be
235 dispatch at some time in the future.
236 Parameters:
238 targ The target OSC address
239 ts The OSC timetag timestamp at which the message will be processed
240 path The OSC path the message will be delivered to
241 type The types of the data items in the message, types are defined
242 in lo_types_common.h
243 ... The data values to be transmitted. The types of the arguments
244 passed here must agree with the types specified in the type
245 parameter.
246 example:
248 lo_timetag now;
249 lo_timetag_now(&now);
250 lo_send_timestamped(t, now, '/foo/bar', 'ff', 0.1f, 23.0f);
251 on success returns the number of bytes sent, returns -1 on failure.
253 lo_method lo_server_thread_add_method (lo_server_thread st, const char *
255 path, const char * typespec, lo_method_handler h, void * user_data)
256 Add an OSC method to the specifed server thread.
257 Parameters:
259 st The server thread the method is to be added to.
260 path The OSC path to register the method to. If NULL is passed the
261 method will match all paths.
262 typespec The typespec the method accepts. Incoming messages with
263 similar typespecs (e.g. ones with numerical types in the same
264 position) will be coerced to the typespec given here.
265 h The method handler callback function that will be called it a
266 matching message is received
267 user_data A value that will be passed to the callback function, h,
268 when its invoked matching from this method.
269 void lo_server_thread_del_method (lo_server_thread st, const char * path,
271 const char * typespec)
272 Delete an OSC method from the specifed server thread.
273 Parameters:
275 st The server thread the method is to be removed from.
276 path The OSC path of the method to delete. If NULL is passed the
277 method will match the generic handler.
278 typespec The typespec the method accepts.
279 int lo_server_thread_events_pending (lo_server_thread st)
281 Return true if there are scheduled events (eg. from bundles) waiting to
282 be dispatched by the thread.
283 void lo_server_thread_free (lo_server_thread st)
285 Free memory taken by a server thread.
286 Frees the memory, and, if currently running will stop the associated
288 thread.
289 int lo_server_thread_get_port (lo_server_thread st)
291 Return the port number that the server thread has bound to.
292 lo_server lo_server_thread_get_server (lo_server_thread st)
294 Return the lo_server for a lo_server_thread.
295 This function is useful for passing a thread's lo_server to
297 lo_send_from().
298 char* lo_server_thread_get_url (lo_server_thread st)
300 Return a URL describing the address of the server thread.
301 Return value must be free()'d to reclaim memory.
303 lo_server_thread lo_server_thread_new (const char * port, lo_err_handler
305 err_h)
306 Create a new server thread to handle incoming OSC messages.
307 Server threads take care of the message reception and dispatch by
309 transparently creating a systme thread to handle incoming messages. Use
310 this if you do not want to handle the threading yourself.
311 Parameters:
313 port If NULL is passed then an unused UDP port will be chosen by
314 the system, its number may be retreived with
315 lo_server_thread_get_port() so it can be passed to clients.
316 Otherwise a decimal port number, service name or UNIX domain socket
317 path may be passed.
318 err_h A function that will be called in the event of an error being
319 raised. The function prototype is defined in lo_types.h
320 void lo_server_thread_start (lo_server_thread st)
322 Start the server thread.
323 Parameters:
325 st the server thread to start.
326 void lo_server_thread_stop (lo_server_thread st)
328 Stop the server thread.
329 Parameters:
331 st the server thread to start.
332Version 0.23 22 Feb 2007 High-level OSC API(3)