CSL 5.2

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

lo_lowlevel.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2004 Steve Harris
3 *
4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public License
6 * as published by the Free Software Foundation; either version 2.1
7 * of the License, or (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 * $Id$
15 */
16
17 #ifndef LO_LOWLEVEL_H
18 #define LO_LOWLEVEL_H
19
20 #include "lo/lo_osc_types.h"
21
22 /**
23 * \file lo_lowlevel.h The liblo headerfile defining the low-level API
24 * functions.
25 */
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 #include <stdarg.h>
32 #ifdef _MSC_VER
33 #define ssize_t SSIZE_T
34 #define uint32_t unsigned __int32
35 #else
36 #include <stdint.h>
37 #endif
38
39 #include "lo/lo_types.h"
40 #include "lo/lo_errors.h"
41
42 /**
43 * \defgroup liblolowlevel Low-level OSC API
44 *
45 * Use these functions if you require more precise control over OSC message
46 * contruction or handling that what is provided in the high-level functions
47 * described in liblo.
48 * @{
49 */
50
51 /**
52 * \brief Type used to represent numerical values in conversions between OSC
53 * types.
54 */
55 typedef long double lo_hires;
56
57
58
59
60 /**
61 * \brief Send a lo_message object to target targ
62 *
63 * This is slightly more efficient than lo_send() if you want to send a lot of
64 * similar messages. The messages are constructed with the lo_message_new() and
65 * \ref lo_message_add_int32 "lo_message_add*()" functions.
66 */
67 int lo_send_message(lo_address targ, const char *path, lo_message msg);
68
69 /**
70 * \brief Send a lo_message object to target targ from address of serv
71 *
72 * This is slightly more efficient than lo_send() if you want to send a lot of
73 * similar messages. The messages are constructed with the lo_message_new() and
74 * \ref lo_message_add_int32 "lo_message_add*()" functions.
75 *
76 * \param targ The address to send the message to
77 * \param serv The server socket to send the message from
78 * (can be NULL to use new socket)
79 * \param path The path to send the message to
80 * \param msg The bundle itself
81 */
82 int lo_send_message_from(lo_address targ, lo_server serv,
83 const char *path, lo_message msg);
84
85 /**
86 * \brief Send a lo_bundle object to address targ
87 *
88 * Bundles are constructed with the
89 * lo_bundle_new() and lo_bundle_add_message() functions.
90 */
91 int lo_send_bundle(lo_address targ, lo_bundle b);
92
93 /**
94 * \brief Send a lo_bundle object to address targ from address of serv
95 *
96 * Bundles are constructed with the
97 * lo_bundle_new() and lo_bundle_add_message() functions.
98 *
99 * \param targ The address to send the bundle to
100 * \param serv The server socket to send the bundle from
101 * (can be NULL to use new socket)
102 * \param b The bundle itself
103 */
104 int lo_send_bundle_from(lo_address targ, lo_server serv, lo_bundle b);
105
106 /**
107 * \brief Create a new lo_message object
108 */
109 lo_message lo_message_new();
110
111 /**
112 * \brief Free memory allocated by lo_message_new() and any subsequent
113 * \ref lo_message_add_int32 lo_message_add*() calls.
114 */
115 void lo_message_free(lo_message m);
116
117 /**
118 * \brief Append a number of arguments to a message.
119 *
120 * The data will be added in OSC byteorder (bigendian).
121 *
122 * \param m The message to be extended.
123 * \param types The types of the data items in the message, types are defined in
124 * lo_types_common.h
125 * \param ... The data values to be transmitted. The types of the arguments
126 * passed here must agree with the types specified in the type parameter.
127 *
128 * \return Less than 0 on failure, 0 on success.
129 */
130 int lo_message_add(lo_message m, const char *types, ...);
131
132 /** \internal \brief the real message_add function (don't call directly) */
133 int lo_message_add_internal(lo_message m, const char *file, const int line,
134 const char *types, ...);
135
136 /**
137 * \brief Append a varargs list to a message.
138 *
139 * The data will be added in OSC byteorder (bigendian).
140 * IMPORTANT: args list must be terminated with LO_ARGS_END, or this call will
141 * fail. This is used to do simple error checking on the sizes of parameters
142 * passed.
143 *
144 * \param m The message to be extended.
145 * \param types The types of the data items in the message, types are defined in
146 * lo_types_common.h
147 * \param ap The va_list created by a C function declared with an
148 * ellipsis (...) argument, and pre-initialised with
149 * "va_start(ap)". The types of the arguments passed here must agree
150 * with the types specified in the type parameter.
151 *
152 * \return Less than 0 on failure, 0 on success.
153 */
154 int lo_message_add_varargs(lo_message m, const char *types, va_list ap);
155
156 /** \internal \brief the real message_add_varargs function (don't call directly) */
157 int lo_message_add_varargs_internal(lo_message m, const char *types, va_list ap,
158 const char *file, const int line);
159
160 /**
161 * \brief Append a data item and typechar of the specified type to a message.
162 *
163 * The data will be added in OSC byteorder (bigendian).
164 *
165 * \param m The message to be extended.
166 * \param a The data item.
167 *
168 * \return Less than 0 on failure, 0 on success.
169 */
170 int lo_message_add_int32(lo_message m, int32_t a);
171
172 /**
173 * \brief Append a data item and typechar of the specified type to a message.
174 * See lo_message_add_int32() for details.
175 *
176 * \return Less than 0 on failure, 0 on success.
177 */
178 int lo_message_add_float(lo_message m, float a);
179
180 /**
181 * \brief Append a data item and typechar of the specified type to a message.
182 * See lo_message_add_int32() for details.
183 *
184 * \return Less than 0 on failure, 0 on success.
185 */
186 int lo_message_add_string(lo_message m, const char *a);
187
188 /**
189 * \brief Append a data item and typechar of the specified type to a message.
190 * See lo_message_add_int32() for details.
191 *
192 * \return Less than 0 on failure, 0 on success.
193 */
194 int lo_message_add_blob(lo_message m, lo_blob a);
195
196 /**
197 * \brief Append a data item and typechar of the specified type to a message.
198 * See lo_message_add_int32() for details.
199 *
200 * \return Less than 0 on failure, 0 on success.
201 */
202 int lo_message_add_int64(lo_message m, int64_t a);
203
204 /**
205 * \brief Append a data item and typechar of the specified type to a message.
206 * See lo_message_add_int32() for details.
207 *
208 * \return Less than 0 on failure, 0 on success.
209 */
210 int lo_message_add_timetag(lo_message m, lo_timetag a);
211
212 /**
213 * \brief Append a data item and typechar of the specified type to a message.
214 * See lo_message_add_int32() for details.
215 *
216 * \return Less than 0 on failure, 0 on success.
217 */
218 int lo_message_add_double(lo_message m, double a);
219
220 /**
221 * \brief Append a data item and typechar of the specified type to a message.
222 * See lo_message_add_int32() for details.
223 *
224 * \return Less than 0 on failure, 0 on success.
225 */
226 int lo_message_add_symbol(lo_message m, const char *a);
227
228 /**
229 * \brief Append a data item and typechar of the specified type to a message.
230 * See lo_message_add_int32() for details.
231 *
232 * \return Less than 0 on failure, 0 on success.
233 */
234 int lo_message_add_char(lo_message m, char a);
235
236 /**
237 * \brief Append a data item and typechar of the specified type to a message.
238 * See lo_message_add_int32() for details.
239 *
240 * \return Less than 0 on failure, 0 on success.
241 */
242 int lo_message_add_midi(lo_message m, uint8_t a[4]);
243
244 /**
245 * \brief Append a data item and typechar of the specified type to a message.
246 * See lo_message_add_int32() for details.
247 *
248 * \return Less than 0 on failure, 0 on success.
249 */
250 int lo_message_add_true(lo_message m);
251
252 /**
253 * \brief Append a data item and typechar of the specified type to a message.
254 * See lo_message_add_int32() for details.
255 *
256 * \return Less than 0 on failure, 0 on success.
257 */
258 int lo_message_add_false(lo_message m);
259
260 /**
261 * \brief Append a data item and typechar of the specified type to a message.
262 * See lo_message_add_int32() for details.
263 *
264 * \return Less than 0 on failure, 0 on success.
265 */
266 int lo_message_add_nil(lo_message m);
267
268 /**
269 * \brief Append a data item and typechar of the specified type to a message.
270 * See lo_message_add_int32() for details.
271 *
272 * \return Less than 0 on failure, 0 on success.
273 */
274 int lo_message_add_infinitum(lo_message m);
275
276 /**
277 * \brief Returns the source (lo_address) of an incoming message.
278 *
279 * Returns NULL if the message is outgoing. Do not free the returned address.
280 */
281 lo_address lo_message_get_source(lo_message m);
282
283 /**
284 * \brief Returns the timestamp (lo_timetag *) of a bundled incoming message.
285 *
286 * Returns LO_TT_IMMEDIATE if the message is outgoing, or did not arrive
287 * contained in a bundle. Do not free the returned timetag.
288 */
289 lo_timetag lo_message_get_timestamp(lo_message m);
290
291 /**
292 * \brief Return the message type tag string.
293 *
294 * The result is valid until further data is added with lo_message_add*().
295 */
296 char *lo_message_get_types(lo_message m);
297
298 /**
299 * \brief Return the message argument count.
300 *
301 * The result is valid until further data is added with lo_message_add*().
302 */
303 int lo_message_get_argc(lo_message m);
304
305 /**
306 * \brief Return the message arguments. Do not free the returned data.
307 *
308 * The result is valid until further data is added with lo_message_add*().
309 */
310 lo_arg **lo_message_get_argv(lo_message m);
311
312 /**
313 * \brief Return the length of a message in bytes.
314 *
315 * \param m The message to be sized
316 * \param path The path the message will be sent to
317 */
318 size_t lo_message_length(lo_message m, const char *path);
319
320 /**
321 * \brief Serialise the lo_message object to an area of memory and return a
322 * pointer to the serialised form. Opposite of lo_message_deserialise().
323 *
324 * \param m The message to be serialised
325 * \param path The path the message will be sent to
326 * \param to The address to serialise to, memory will be allocated if to is
327 * NULL.
328 * \param size If this pointer is non-NULL the size of the memory area
329 * will be written here
330 *
331 * The returned form is suitable to be sent over a low level OSC transport,
332 * having the correct endianess and bit-packed structure.
333 */
334 void *lo_message_serialise(lo_message m, const char *path, void *to,
335 size_t *size);
336
337 /**
338 * \brief Deserialise a raw OSC message and return a new lo_message object.
339 * Opposite of lo_message_serialise().
340 *
341 * \param data Pointer to the raw OSC message data in network transmission form
342 * (network byte order where appropriate).
343 * \param size The size of data in bytes
344 * \param result If this pointer is non-NULL, the result or error code will
345 * be written here.
346 *
347 * Returns a new lo_message, or NULL if deserialisation fails.
348 * Use lo_message_free() to free the resulting object.
349 */
350 lo_message lo_message_deserialise(void *data, size_t size, int *result);
351
352 /**
353 * \brief Dispatch a raw block of memory containing an OSC message.
354 *
355 * This is useful when a raw block of memory is available that is
356 * structured as OSC, and you wish to use liblo to dispatch the
357 * message to a handler function as if it had been received over the
358 * network.
359 *
360 * \param s The lo_server to use for dispatching.
361 * \param data Pointer to the raw OSC message data in network transmission form
362 * (network byte order where appropriate).
363 * \param size The size of data in bytes
364 *
365 * Returns the number of bytes used if successful, or less than 0 otherwise.
366 */
367 int lo_server_dispatch_data(lo_server s, void *data, size_t size);
368
369 /**
370 * \brief Return the hostname of a lo_address object
371 *
372 * Returned value must not be modified or free'd. Value will be a dotted quad,
373 * colon'd IPV6 address, or resolvable name.
374 */
375 const char *lo_address_get_hostname(lo_address a);
376
377 /**
378 * \brief Return the port/service name of a lo_address object
379 *
380 * Returned value must not be modified or free'd. Value will be a service name
381 * or ASCII representation of the port number.
382 */
383 const char *lo_address_get_port(lo_address a);
384
385 /**
386 * \brief Return the protocol of a lo_address object
387 *
388 * Returned value will be one of LO_UDP, LO_TCP or LO_UNIX.
389 */
390 int lo_address_get_protocol(lo_address a);
391
392 /**
393 * \brief Return a URL representing an OSC address
394 *
395 * Returned value must be free'd.
396 */
397 char *lo_address_get_url(lo_address a);
398
399 /**
400 * \brief Set the Time-to-Live value for a given target address.
401 *
402 * This is required for sending multicast UDP messages. A value of 1
403 * (the usual case) keeps the message within the subnet, while 255
404 * means a global, unrestricted scope.
405 *
406 * \param t An OSC address.
407 * \param ttl An integer specifying the scope of a multicast UDP message.
408 */
409 void lo_address_set_ttl(lo_address t, int ttl);
410
411 /**
412 * \brief Get the Time-to-Live value for a given target address.
413 *
414 * \param t An OSC address.
415 * \return An integer specifying the scope of a multicast UDP message.
416 */
417 int lo_address_get_ttl(lo_address t);
418
419 /**
420 * \brief Create a new bundle object.
421 *
422 * OSC Bundles encapsulate one or more OSC messages and may include a timestamp
423 * indicating when the bundle should be dispatched.
424 *
425 * \param tt The timestamp when the bundle should be handled by the receiver.
426 * Pass LO_TT_IMMEDIATE if you want the receiving server to dispatch
427 * the bundle as soon as it receives it.
428 */
429 lo_bundle lo_bundle_new(lo_timetag tt);
430
431 /**
432 * \brief Adds an OSC message to an existing bundle.
433 *
434 * The message passed is appended to the list of messages in the bundle to be
435 * dispatched to 'path'.
436 *
437 * \return 0 if successful, less than 0 otherwise.
438 */
439 int lo_bundle_add_message(lo_bundle b, const char *path, lo_message m);
440
441 /**
442 * \brief Return the length of a bundle in bytes.
443 *
444 * Includes the marker and typetage length.
445 *
446 * \param b The bundle to be sized
447 */
448 size_t lo_bundle_length(lo_bundle b);
449
450 /**
451 * \brief Serialise the bundle object to an area of memory and return a
452 * pointer to the serialised form.
453 *
454 * \param b The bundle to be serialised
455 * \param to The address to serialise to, memory will be allocated if to is
456 * NULL.
457 * \param size If this pointer is non-NULL the size of the memory area
458 * will be written here
459 *
460 * The returned form is suitable to be sent over a low level OSC transport,
461 * having the correct endianess and bit-packed structure.
462 */
463 void *lo_bundle_serialise(lo_bundle b, void *to, size_t *size);
464
465 /**
466 * \brief Frees the memory taken by a bundle object.
467 *
468 * \param b The bundle to be freed.
469 */
470 void lo_bundle_free(lo_bundle b);
471
472 /**
473 * \brief Frees the memory taken by a bundle object and messages in the bundle.
474 *
475 * \param b The bundle, which may contain messages, to be freed.
476 */
477 void lo_bundle_free_messages(lo_bundle b);
478
479 /**
480 * \brief Return true if the type specified has a numerical value, such as
481 * LO_INT32, LO_FLOAT etc.
482 *
483 * \param a The type to be tested.
484 */
485 int lo_is_numerical_type(lo_type a);
486
487 /**
488 * \brief Return true if the type specified has a textual value, such as
489 * LO_STRING or LO_SYMBOL.
490 *
491 * \param a The type to be tested.
492 */
493 int lo_is_string_type(lo_type a);
494
495 /**
496 * \brief Attempt to convert one OSC type to another.
497 *
498 * Numerical types (eg LO_INT32, LO_FLOAT etc.) may be converted to other
499 * numerical types and string types (LO_STRING and LO_SYMBOL) may be converted
500 * to the other type. This is done automatically if a received message matches
501 * the path, but not the exact types, and is coercible (ie. all numerical
502 * types in numerical positions).
503 *
504 * On failure no translation occurs and false is returned.
505 *
506 * \param type_to The type of the destination variable.
507 * \param to A pointer to the destination variable.
508 * \param type_from The type of the source variable.
509 * \param from A pointer to the source variable.
510 */
511 int lo_coerce(lo_type type_to, lo_arg *to, lo_type type_from, lo_arg *from);
512
513 /**
514 * \brief Return the numerical value of the given argument with the
515 * maximum native system precision.
516 */
517 lo_hires lo_hires_val(lo_type type, lo_arg *p);
518
519 /**
520 * \brief Create a new server instance.
521 *
522 * Using lo_server_recv(), lo_servers block until they receive OSC
523 * messages. If you want non-blocking behaviour see
524 * lo_server_recv_noblock() or the \ref lo_server_thread_new
525 * "lo_server_thread_*" functions.
526 *
527 * \param port If NULL is passed then an unused UDP port will be chosen by the
528 * system, its number may be retrieved with lo_server_thread_get_port()
529 * so it can be passed to clients. Otherwise a decimal port number, service
530 * name or UNIX domain socket path may be passed.
531 * \param err_h An error callback function that will be called if there is an
532 * error in messge reception or server creation. Pass NULL if you do not want
533 * error handling.
534 */
535 lo_server lo_server_new(const char *port, lo_err_handler err_h);
536
537 /**
538 * \brief Create a new server instance, specifying protocol.
539 *
540 * Using lo_server_recv(), lo_servers block until they receive OSC
541 * messages. If you want non-blocking behaviour see
542 * lo_server_recv_noblock() or the \ref lo_server_thread_new
543 * "lo_server_thread_*" functions.
544 *
545 * \param port If using UDP then NULL may be passed to find an unused port.
546 * Otherwise a decimal port number orservice name or may be passed.
547 * If using UNIX domain sockets then a socket path should be passed here.
548 * \param proto The protocol to use, should be one of LO_UDP, LO_TCP or LO_UNIX.
549 * \param err_h An error callback function that will be called if there is an
550 * error in messge reception or server creation. Pass NULL if you do not want
551 * error handling.
552 */
553 lo_server lo_server_new_with_proto(const char *port, int proto,
554 lo_err_handler err_h);
555
556 /**
557 * \brief Create a new server instance, and join a UDP multicast group.
558 *
559 * \param group The multicast group to join. See documentation on IP
560 * multicast for the acceptable address range; e.g., http://tldp.org/HOWTO/Multicast-HOWTO-2.html
561 * \param port If using UDP then NULL may be passed to find an unused port.
562 * Otherwise a decimal port number or service name or may be passed.
563 * If using UNIX domain sockets then a socket path should be passed here.
564 * \param err_h An error callback function that will be called if there is an
565 * error in messge reception or server creation. Pass NULL if you do not want
566 * error handling.
567 */
568 lo_server lo_server_new_multicast(const char *group, const char *port,
569 lo_err_handler err_h);
570
571 /**
572 * \brief Free up memory used by the lo_server object
573 */
574 void lo_server_free(lo_server s);
575
576 /**
577 * \brief Wait for an OSC message to be received
578 *
579 * \param s The server to wait for connections on.
580 * \param timeout A timeout in milliseconds to wait for the incoming packet.
581 * a value of 0 will return immediately.
582 *
583 * The return value is 1 if there is a message waiting or 0 if
584 * there is no message. If there is a message waiting you can now
585 * call lo_server_recv() to receive that message.
586 */
587 int lo_server_wait(lo_server s, int timeout);
588
589 /**
590 * \brief Look for an OSC message waiting to be received
591 *
592 * \param s The server to wait for connections on.
593 * \param timeout A timeout in milliseconds to wait for the incoming packet.
594 * a value of 0 will return immediately.
595 *
596 * The return value is the number of bytes in the received message or 0 if
597 * there is no message. The message will be dispatched to a matching method
598 * if one is found.
599 */
600 int lo_server_recv_noblock(lo_server s, int timeout);
601
602 /**
603 * \brief Block, waiting for an OSC message to be received
604 *
605 * The return value is the number of bytes in the received message. The message
606 * will be dispatched to a matching method if one is found.
607 */
608 int lo_server_recv(lo_server s);
609
610 /**
611 * \brief Add an OSC method to the specifed server.
612 *
613 * \param s The server the method is to be added to.
614 * \param path The OSC path to register the method to. If NULL is passed the
615 * method will match all paths.
616 * \param typespec The typespec the method accepts. Incoming messages with
617 * similar typespecs (e.g. ones with numerical types in the same position) will
618 * be coerced to the typespec given here.
619 * \param h The method handler callback function that will be called if a
620 * matching message is received
621 * \param user_data A value that will be passed to the callback function, h,
622 * when its invoked matching from this method.
623 */
624 lo_method lo_server_add_method(lo_server s, const char *path,
625 const char *typespec, lo_method_handler h,
626 void *user_data);
627
628 /**
629 * \brief Delete an OSC method from the specifed server.
630 *
631 * \param s The server the method is to be removed from.
632 * \param path The OSC path of the method to delete. If NULL is passed the
633 * method will match the generic handler.
634 * \param typespec The typespec the method accepts.
635 */
636 void lo_server_del_method(lo_server s, const char *path,
637 const char *typespec);
638
639 /**
640 * \brief Return the file descriptor of the server socket.
641 *
642 * If the server protocol supports exposing the server's underlying
643 * receive mechanism for monitoring with select() or poll(), this function
644 * returns the file descriptor needed, otherwise, it returns -1.
645 *
646 * WARNING: when using this function beware that not all OSC packets that are
647 * received are dispatched immediately. lo_server_events_pending() and
648 * lo_server_next_event_delay() can be used to tell if there are pending
649 * events and how long before you should attempt to receive them.
650 */
651 int lo_server_get_socket_fd(lo_server s);
652
653 /**
654 * \brief Return the port number that the server has bound to.
655 *
656 * Useful when NULL is passed for the port number and you wish to know how to
657 * address the server.
658 */
659 int lo_server_get_port(lo_server s);
660
661 /**
662 * \brief Return the protocol that the server is using.
663 *
664 * Returned value will be one of LO_UDP, LO_TCP or LO_UNIX.
665 */
666 int lo_server_get_protocol(lo_server s);
667
668 /**
669 * \brief Return an OSC URL that can be used to contact the server.
670 *
671 * The return value should be free()'d when it is no longer needed.
672 */
673 char *lo_server_get_url(lo_server s);
674
675 /**
676 * \brief Return true if there are scheduled events (eg. from bundles)
677 * waiting to be dispatched by the server
678 */
679 int lo_server_events_pending(lo_server s);
680
681 /**
682 * \brief Return the time in seconds until the next scheduled event.
683 *
684 * If the delay is greater than 100 seconds then it will return 100.0.
685 */
686 double lo_server_next_event_delay(lo_server s);
687
688 /**
689 * \brief Return the protocol portion of an OSC URL, eg. udp, tcp.
690 *
691 * This library uses OSC URLs of the form: osc.prot://hostname:port/path if the
692 * prot part is missing, UDP is assumed.
693 *
694 * The return value should be free()'d when it is no longer needed.
695 */
696 char *lo_url_get_protocol(const char *url);
697
698 /**
699 * \brief Return the protocol ID of an OSC URL.
700 *
701 * This library uses OSC URLs of the form: osc.prot://hostname:port/path if the
702 * prot part is missing, UDP is assumed.
703 * Returned value will be one of LO_UDP, LO_TCP, LO_UNIX or -1.
704 *
705 * \return An integer specifying the protocol. Return -1 when the protocol is
706 * not supported by liblo.
707 *
708 */
709 int lo_url_get_protocol_id(const char *url);
710
711 /**
712 * \brief Return the hostname portion of an OSC URL.
713 *
714 * The return value should be free()'d when it is no longer needed.
715 */
716 char *lo_url_get_hostname(const char *url);
717
718 /**
719 * \brief Return the port portion of an OSC URL.
720 *
721 * The return value should be free()'d when it is no longer needed.
722 */
723 char *lo_url_get_port(const char *url);
724
725 /**
726 * \brief Return the path portion of an OSC URL.
727 *
728 * The return value should be free()'d when it is no longer needed.
729 */
730 char *lo_url_get_path(const char *url);
731
732 /* utility functions */
733
734 /**
735 * \brief A function to calculate the amount of OSC message space required by a
736 * C char *.
737 *
738 * Returns the storage size in bytes, which will always be a multiple of four.
739 */
740 int lo_strsize(const char *s);
741
742 /**
743 * \brief A function to calculate the amount of OSC message space required by a
744 * lo_blob object.
745 *
746 * Returns the storage size in bytes, which will always be a multiple of four.
747 */
748 uint32_t lo_blobsize(lo_blob b);
749
750 /**
751 * \brief Test a string against an OSC pattern glob
752 *
753 * \param str The string to test
754 * \param p The pattern to test against
755 */
756 int lo_pattern_match(const char *str, const char *p);
757
758 /** \internal \brief the real send function (don't call directly) */
759 int lo_send_internal(lo_address t, const char *file, const int line,
760 const char *path, const char *types, ...);
761 /** \internal \brief the real send_timestamped function (don't call directly) */
762 int lo_send_timestamped_internal(lo_address t, const char *file, const int line,
763 lo_timetag ts, const char *path, const char *types, ...);
764 /** \internal \brief the real lo_send_from() function (don't call directly) */
765 int lo_send_from_internal(lo_address targ, lo_server from, const char *file,
766 const int line, const lo_timetag ts,
767 const char *path, const char *types, ...);
768
769
770 /** \brief Find the time difference between two timetags
771 *
772 * Returns a - b in seconds.
773 */
774 double lo_timetag_diff(lo_timetag a, lo_timetag b);
775
776 /** \brief Return a timetag for the current time
777 *
778 * On exit the timetag pointed to by t is filled with the OSC
779 * representation of this instant in time.
780 */
781 void lo_timetag_now(lo_timetag *t);
782
783 /**
784 * \brief Return the storage size, in bytes, of the given argument.
785 */
786 size_t lo_arg_size(lo_type type, void *data);
787
788 /**
789 * \brief Given a raw OSC message, return the message path.
790 *
791 * \param data A pointer to the raw OSC message data.
792 * \param size The size of data in bytes (total buffer bytes).
793 *
794 * Returns the message path or NULL if an error occurs.
795 * Do not free() the returned pointer.
796 */
797 char *lo_get_path(void *data, ssize_t size);
798
799 /**
800 * \brief Convert the specified argument to host byte order where necessary.
801 *
802 * \param type The OSC type of the data item (eg. LO_FLOAT).
803 * \param data A pointer to the data item to be converted. It is changed
804 * in-place.
805 */
806 void lo_arg_host_endian(lo_type type, void *data);
807
808 /**
809 * \brief Convert the specified argument to network byte order where necessary.
810 *
811 * \param type The OSC type of the data item (eg. LO_FLOAT).
812 * \param data A pointer to the data item to be converted. It is changed
813 * in-place.
814 */
815 void lo_arg_network_endian(lo_type type, void *data);
816
817 /** @} */
818
819 /* prettyprinters */
820
821 /**
822 * \defgroup pp Prettyprinting functions
823 *
824 * These functions all print an ASCII representation of their argument to
825 * stdout. Useful for debugging.
826 * @{
827 */
828
829 /** \brief Pretty-print a lo_bundle object. */
830 void lo_bundle_pp(lo_bundle b);
831
832 /** \brief Pretty-print a lo_message object. */
833 void lo_message_pp(lo_message m);
834
835 /** \brief Pretty-print a set of typed arguments.
836 * \param type A type string in the form provided to lo_send().
837 * \param data An OSC data pointer, like that provided in the
838 * lo_method_handler.
839 */
840 void lo_arg_pp(lo_type type, void *data);
841
842 /** \brief Pretty-print a lo_server object. */
843 void lo_server_pp(lo_server s);
844
845 /** \brief Pretty-print a lo_method object. */
846 void lo_method_pp(lo_method m);
847
848 /** \brief Pretty-print a lo_method object, but prepend a given prefix
849 * to all field names. */
850 void lo_method_pp_prefix(lo_method m, const char *p);
851
852 /** \brief Pretty-print a lo_server_thread object. */
853 void lo_server_thread_pp(lo_server_thread st);
854 /** @} */
855
856 #ifdef __cplusplus
857 }
858 #endif
859
860 #endif