| lo.h | | lo.h | |
| /* | | /* | |
| * Copyright (C) 2004 Steve Harris | | * Copyright (C) 2004 Steve Harris | |
| * | | * | |
|
| * This program is free software; you can redistribute it and/or modify | | * This program is free software; you can redistribute it and/or | |
| * it under the terms of the GNU General Public License as published by | | * modify it under the terms of the GNU Lesser General Public License | |
| * the Free Software Foundation; either version 2 of the License, or | | * as published by the Free Software Foundation; either version 2.1 | |
| * (at your option) any later version. | | * of the License, or (at your option) any later version. | |
| * | | * | |
| * This program is distributed in the hope that it will be useful, | | * This program is distributed in the hope that it will be useful, | |
| * but WITHOUT ANY WARRANTY; without even the implied warranty of | | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
|
| * GNU General Public License for more details. | | * GNU Lesser General Public License for more details. | |
| * | | * | |
| * $Id$ | | * $Id$ | |
| */ | | */ | |
| | | | |
| #ifndef LO_H | | #ifndef LO_H | |
| #define LO_H | | #define LO_H | |
| | | | |
| #ifdef __cplusplus | | #ifdef __cplusplus | |
| extern "C" { | | extern "C" { | |
| #endif | | #endif | |
| | | | |
| skipping to change at line 37 | | skipping to change at line 37 | |
| | | | |
| #include "lo/lo_endian.h" | | #include "lo/lo_endian.h" | |
| #include "lo/lo_types.h" | | #include "lo/lo_types.h" | |
| #include "lo/lo_osc_types.h" | | #include "lo/lo_osc_types.h" | |
| #include "lo/lo_errors.h" | | #include "lo/lo_errors.h" | |
| #include "lo/lo_lowlevel.h" | | #include "lo/lo_lowlevel.h" | |
| | | | |
| /** | | /** | |
| * \defgroup liblo High-level OSC API | | * \defgroup liblo High-level OSC API | |
| * | | * | |
|
| * Defines the high-level API functions neccesary to implement OSC support. | | * Defines the high-level API functions necessary to implement OSC support. | |
| * Should be adequate for most applications, but ig you require lower level | | * Should be adequate for most applications, but if you require lower level | |
| * control you can use the functions defined in lo_lowlevel.h. | | * control you can use the functions defined in lo_lowlevel.h | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * \brief Declare an OSC destination, given IP address and port number. | | * \brief Declare an OSC destination, given IP address and port number. | |
|
| | | * Same as lo_address_new_with_proto(), but using UDP. | |
| * | | * | |
| * \param host An IP address or number, or NULL for the local machine. | | * \param host An IP address or number, or NULL for the local machine. | |
| * \param port a decimal port number or service name. | | * \param port a decimal port number or service name. | |
| * | | * | |
| * The lo_address object may be used as the target of OSC messages. | | * The lo_address object may be used as the target of OSC messages. | |
| * | | * | |
| * Note: if you wish to receive replies from the target of this address, yo
u | | * Note: if you wish to receive replies from the target of this address, yo
u | |
| * must first create a lo_server_thread or lo_server object which will rece
ive | | * must first create a lo_server_thread or lo_server object which will rece
ive | |
| * the replies. The last lo_server(_thread) object creted will be the recei
ver. | | * the replies. The last lo_server(_thread) object creted will be the recei
ver. | |
| */ | | */ | |
| lo_address lo_address_new(const char *host, const char *port); | | lo_address lo_address_new(const char *host, const char *port); | |
| | | | |
| /** | | /** | |
|
| | | * \brief Declare an OSC destination, given IP address and port number, | |
| | | * specifying protocol. | |
| | | * | |
| | | * \param proto The protocol to use, must be one of LO_UDP, LO_TCP or LO_UN | |
| | | IX. | |
| | | * \param host An IP address or number, or NULL for the local machine. | |
| | | * \param port a decimal port number or service name. | |
| | | * | |
| | | * The lo_address object may be used as the target of OSC messages. | |
| | | * | |
| | | * Note: if you wish to receive replies from the target of this address, yo | |
| | | u | |
| | | * must first create a lo_server_thread or lo_server object which will rece | |
| | | ive | |
| | | * the replies. The last lo_server(_thread) object creted will be the recei | |
| | | ver. | |
| | | */ | |
| | | lo_address lo_address_new_with_proto(int proto, const char *host, const cha | |
| | | r *port); | |
| | | | |
| | | /** | |
| * \brief Create a lo_address object from an OSC URL. | | * \brief Create a lo_address object from an OSC URL. | |
| * | | * | |
|
| * example: osc.udp://localhost:4444/my/path/ | | * example: \c "osc.udp://localhost:4444/my/path/" | |
| */ | | */ | |
| lo_address lo_address_new_from_url(const char *url); | | lo_address lo_address_new_from_url(const char *url); | |
| | | | |
| /** | | /** | |
| * \brief Free the memory used by the lo_address object | | * \brief Free the memory used by the lo_address object | |
| */ | | */ | |
| void lo_address_free(lo_address t); | | void lo_address_free(lo_address t); | |
| | | | |
| /** | | /** | |
| * \brief Set the Time-to-Live value for a given target address. | | * \brief Set the Time-to-Live value for a given target address. | |
| | | | |
| skipping to change at line 95 | | skipping to change at line 112 | |
| * \return An integer specifying the scope of a multicast UDP message. | | * \return An integer specifying the scope of a multicast UDP message. | |
| */ | | */ | |
| int lo_address_get_ttl(lo_address t); | | int lo_address_get_ttl(lo_address t); | |
| | | | |
| /** | | /** | |
| * \brief Send a OSC formatted message to the address specified. | | * \brief Send a OSC formatted message to the address specified. | |
| * | | * | |
| * \param targ The target OSC address | | * \param targ The target OSC address | |
| * \param path The OSC path the message will be delivered to | | * \param path The OSC path the message will be delivered to | |
| * \param type The types of the data items in the message, types are define
d in | | * \param type The types of the data items in the message, types are define
d in | |
|
| * lo_types_common.h | | * lo_osc_types.h | |
| * \param ... The data values to be transmitted. The types of the arguments | | * \param ... The data values to be transmitted. The types of the arguments | |
| * passed here must agree with the types specified in the type parameter. | | * passed here must agree with the types specified in the type parameter. | |
| * | | * | |
|
| * example:<br> | | * example: | |
| | | * \code | |
| * lo_send(t, "/foo/bar", "ff", 0.1f, 23.0f); | | * lo_send(t, "/foo/bar", "ff", 0.1f, 23.0f); | |
|
| | | * \endcode | |
| * | | * | |
|
| * returns -1 on failure. | | * \return -1 on failure. | |
| */ | | */ | |
| int lo_send(lo_address targ, const char *path, const char *type, ...); | | int lo_send(lo_address targ, const char *path, const char *type, ...); | |
| | | | |
| /** | | /** | |
| * \brief Send a OSC formatted message to the address specified, | | * \brief Send a OSC formatted message to the address specified, | |
| * from the same socket as the specificied server. | | * from the same socket as the specificied server. | |
| * | | * | |
| * \param targ The target OSC address | | * \param targ The target OSC address | |
| * \param from The server to send message from (can be NULL to use new so
cket) | | * \param from The server to send message from (can be NULL to use new so
cket) | |
| * \param ts The OSC timetag timestamp at which the message will be proce
ssed | | * \param ts The OSC timetag timestamp at which the message will be proce
ssed | |
| * (can be LO_TT_IMMEDIATE if you don't want to attach a timetag) | | * (can be LO_TT_IMMEDIATE if you don't want to attach a timetag) | |
| * \param path The OSC path the message will be delivered to | | * \param path The OSC path the message will be delivered to | |
| * \param type The types of the data items in the message, types are define
d in | | * \param type The types of the data items in the message, types are define
d in | |
|
| * lo_types_common.h | | * lo_osc_types.h | |
| * \param ... The data values to be transmitted. The types of the arguments | | * \param ... The data values to be transmitted. The types of the arguments | |
| * passed here must agree with the types specified in the type parameter. | | * passed here must agree with the types specified in the type parameter. | |
| * | | * | |
|
| * example:<br> | | * example: | |
| * serv = lo_server_new(NULL, err);<br> | | * \code | |
| | | * serv = lo_server_new(NULL, err); | |
| * lo_server_add_method(serv, "/reply", "ss", reply_handler, NULL); | | * lo_server_add_method(serv, "/reply", "ss", reply_handler, NULL); | |
| * lo_send_from(t, serv, LO_TT_IMMEDIATE, "/foo/bar", "ff", 0.1f, 23.0f); | | * lo_send_from(t, serv, LO_TT_IMMEDIATE, "/foo/bar", "ff", 0.1f, 23.0f); | |
|
| | | * \endcode | |
| * | | * | |
|
| * on success returns the number of bytes sent, returns -1 on failure. | | * \return on success, the number of bytes sent, or -1 on failure. | |
| */ | | */ | |
| int lo_send_from(lo_address targ, lo_server from, lo_timetag ts, | | int lo_send_from(lo_address targ, lo_server from, lo_timetag ts, | |
| const char *path, const char *type, ...); | | const char *path, const char *type, ...); | |
| | | | |
| /** | | /** | |
| * \brief Send a OSC formatted message to the address specified, scheduled
to | | * \brief Send a OSC formatted message to the address specified, scheduled
to | |
| * be dispatch at some time in the future. | | * be dispatch at some time in the future. | |
| * | | * | |
| * \param targ The target OSC address | | * \param targ The target OSC address | |
| * \param ts The OSC timetag timestamp at which the message will be process
ed | | * \param ts The OSC timetag timestamp at which the message will be process
ed | |
| * \param path The OSC path the message will be delivered to | | * \param path The OSC path the message will be delivered to | |
| * \param type The types of the data items in the message, types are define
d in | | * \param type The types of the data items in the message, types are define
d in | |
|
| * lo_types_common.h | | * lo_osc_types.h | |
| * \param ... The data values to be transmitted. The types of the arguments | | * \param ... The data values to be transmitted. The types of the arguments | |
| * passed here must agree with the types specified in the type parameter. | | * passed here must agree with the types specified in the type parameter. | |
| * | | * | |
|
| * example:<br> | | * example: | |
| | | * \code | |
| * lo_timetag now;<br> | | * lo_timetag now;<br> | |
| * lo_timetag_now(&now);<br> | | * lo_timetag_now(&now);<br> | |
| * lo_send_timestamped(t, now, "/foo/bar", "ff", 0.1f, 23.0f); | | * lo_send_timestamped(t, now, "/foo/bar", "ff", 0.1f, 23.0f); | |
|
| | | * \endcode | |
| * | | * | |
|
| * on success returns the number of bytes sent, returns -1 on failure. | | * \return on success, the number of bytes sent, or -1 on failure. | |
| */ | | */ | |
| int lo_send_timestamped(lo_address targ, lo_timetag ts, const char *path, | | int lo_send_timestamped(lo_address targ, lo_timetag ts, const char *path, | |
| const char *type, ...); | | const char *type, ...); | |
| | | | |
| /** | | /** | |
|
| * \brief Return the error number from the last failed lo_send or | | * \brief Return the error number from the last failed lo_send() or | |
| * lo_address_new call | | * lo_address_new() call | |
| */ | | */ | |
| int lo_address_errno(lo_address a); | | int lo_address_errno(lo_address a); | |
| | | | |
| /** | | /** | |
|
| * \brief Return the error string from the last failed lo_send or | | * \brief Return the error string from the last failed lo_send() or | |
| * lo_address_new call | | * lo_address_new() call | |
| */ | | */ | |
| const char *lo_address_errstr(lo_address a); | | const char *lo_address_errstr(lo_address a); | |
| | | | |
| /** | | /** | |
| * \brief Create a new server thread to handle incoming OSC | | * \brief Create a new server thread to handle incoming OSC | |
| * messages. | | * messages. | |
| * | | * | |
| * Server threads take care of the message reception and dispatch by | | * Server threads take care of the message reception and dispatch by | |
|
| * transparently creating a systme thread to handle incoming messages. | | * transparently creating a system thread to handle incoming messages. | |
| * Use this if you do not want to handle the threading yourself. | | * Use this if you do not want to handle the threading yourself. | |
| * | | * | |
| * \param port If NULL is passed then an unused port will be chosen by the | | * \param port If NULL is passed then an unused port will be chosen by the | |
|
| * system, its number may be retreived with lo_server_thread_get_port() | | * system, its number may be retrieved with lo_server_thread_get_port() | |
| * so it can be passed to clients. Otherwise a decimal port number, service | | * so it can be passed to clients. Otherwise a decimal port number, service | |
| * name or UNIX domain socket path may be passed. | | * name or UNIX domain socket path may be passed. | |
| * \param err_h A function that will be called in the event of an error bei
ng | | * \param err_h A function that will be called in the event of an error bei
ng | |
| * raised. The function prototype is defined in lo_types.h | | * raised. The function prototype is defined in lo_types.h | |
| */ | | */ | |
| lo_server_thread lo_server_thread_new(const char *port, lo_err_handler err_
h); | | lo_server_thread lo_server_thread_new(const char *port, lo_err_handler err_
h); | |
| | | | |
| /** | | /** | |
| * \brief Create a new server thread to handle incoming OSC | | * \brief Create a new server thread to handle incoming OSC | |
| * messages, and join a UDP multicast group. | | * messages, and join a UDP multicast group. | |
|
| | | * | |
| * Server threads take care of the message reception and dispatch by | | * Server threads take care of the message reception and dispatch by | |
| * transparently creating a system thread to handle incoming messages. | | * transparently creating a system thread to handle incoming messages. | |
| * Use this if you do not want to handle the threading yourself. | | * Use this if you do not want to handle the threading yourself. | |
| * | | * | |
| * \param group The multicast group to join. See documentation on IP | | * \param group The multicast group to join. See documentation on IP | |
| * multicast for the acceptable address range; e.g., http://tldp.org/HOWTO/
Multicast-HOWTO-2.html | | * multicast for the acceptable address range; e.g., http://tldp.org/HOWTO/
Multicast-HOWTO-2.html | |
| * \param port If NULL is passed then an unused port will be chosen by the | | * \param port If NULL is passed then an unused port will be chosen by the | |
| * system, its number may be retrieved with lo_server_thread_get_port() | | * system, its number may be retrieved with lo_server_thread_get_port() | |
| * so it can be passed to clients. Otherwise a decimal port number, service | | * so it can be passed to clients. Otherwise a decimal port number, service | |
| * name or UNIX domain socket path may be passed. | | * name or UNIX domain socket path may be passed. | |
| | | | |
| skipping to change at line 205 | | skipping to change at line 229 | |
| * raised. The function prototype is defined in lo_types.h | | * raised. The function prototype is defined in lo_types.h | |
| */ | | */ | |
| lo_server_thread lo_server_thread_new_multicast(const char *group, const ch
ar *port, | | lo_server_thread lo_server_thread_new_multicast(const char *group, const ch
ar *port, | |
| lo_err_handler err_h); | | lo_err_handler err_h); | |
| | | | |
| /** | | /** | |
| * \brief Create a new server thread to handle incoming OSC | | * \brief Create a new server thread to handle incoming OSC | |
| * messages, specifying protocol. | | * messages, specifying protocol. | |
| * | | * | |
| * Server threads take care of the message reception and dispatch by | | * Server threads take care of the message reception and dispatch by | |
|
| * transparently creating a systme thread to handle incoming messages. | | * transparently creating a system thread to handle incoming messages. | |
| * Use this if you do not want to handle the threading yourself. | | * Use this if you do not want to handle the threading yourself. | |
| * | | * | |
| * \param port If NULL is passed then an unused port will be chosen by the | | * \param port If NULL is passed then an unused port will be chosen by the | |
|
| * system, its number may be retreived with lo_server_thread_get_port() | | * system, its number may be retrieved with lo_server_thread_get_port() | |
| * so it can be passed to clients. Otherwise a decimal port number, service | | * so it can be passed to clients. Otherwise a decimal port number, service | |
| * name or UNIX domain socket path may be passed. | | * name or UNIX domain socket path may be passed. | |
| * \param proto The protocol to use, should be one of LO_UDP, LO_TCP or LO_
UNIX. | | * \param proto The protocol to use, should be one of LO_UDP, LO_TCP or LO_
UNIX. | |
| * \param err_h A function that will be called in the event of an error bei
ng | | * \param err_h A function that will be called in the event of an error bei
ng | |
| * raised. The function prototype is defined in lo_types.h | | * raised. The function prototype is defined in lo_types.h | |
| */ | | */ | |
| lo_server_thread lo_server_thread_new_with_proto(const char *port, int prot
o, | | lo_server_thread lo_server_thread_new_with_proto(const char *port, int prot
o, | |
| lo_err_handler err_h); | | lo_err_handler err_h); | |
| | | | |
| /** | | /** | |
| | | | |
| skipping to change at line 258 | | skipping to change at line 282 | |
| * method will match the generic handler. | | * method will match the generic handler. | |
| * \param typespec The typespec the method accepts. | | * \param typespec The typespec the method accepts. | |
| */ | | */ | |
| void lo_server_thread_del_method(lo_server_thread st, const char *path, | | void lo_server_thread_del_method(lo_server_thread st, const char *path, | |
| const char *typespec); | | const char *typespec); | |
| | | | |
| /** | | /** | |
| * \brief Start the server thread | | * \brief Start the server thread | |
| * | | * | |
| * \param st the server thread to start. | | * \param st the server thread to start. | |
|
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_server_thread_start(lo_server_thread st); | | int lo_server_thread_start(lo_server_thread st); | |
| | | | |
| /** | | /** | |
| * \brief Stop the server thread | | * \brief Stop the server thread | |
| * | | * | |
| * \param st the server thread to start. | | * \param st the server thread to start. | |
|
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_server_thread_stop(lo_server_thread st); | | int lo_server_thread_stop(lo_server_thread st); | |
| | | | |
| /** | | /** | |
| * \brief Return the port number that the server thread has bound to. | | * \brief Return the port number that the server thread has bound to. | |
| */ | | */ | |
| int lo_server_thread_get_port(lo_server_thread st); | | int lo_server_thread_get_port(lo_server_thread st); | |
| | | | |
| /** | | /** | |
| * \brief Return a URL describing the address of the server thread. | | * \brief Return a URL describing the address of the server thread. | |
| * | | * | |
| * Return value must be free()'d to reclaim memory. | | * Return value must be free()'d to reclaim memory. | |
| | | | |
| skipping to change at line 295 | | skipping to change at line 321 | |
| */ | | */ | |
| lo_server lo_server_thread_get_server(lo_server_thread st); | | lo_server lo_server_thread_get_server(lo_server_thread st); | |
| | | | |
| /** \brief Return true if there are scheduled events (eg. from bundles) wai
ting | | /** \brief Return true if there are scheduled events (eg. from bundles) wai
ting | |
| * to be dispatched by the thread */ | | * to be dispatched by the thread */ | |
| int lo_server_thread_events_pending(lo_server_thread st); | | int lo_server_thread_events_pending(lo_server_thread st); | |
| | | | |
| /** | | /** | |
| * \brief Create a new OSC blob type. | | * \brief Create a new OSC blob type. | |
| * | | * | |
|
| * \param size The ammount of space to allocate in the blob structure. | | * \param size The amount of space to allocate in the blob structure. | |
| * \param data The data that will be used to initialise the blob, should be | | * \param data The data that will be used to initialise the blob, should be | |
| * size bytes long. | | * size bytes long. | |
| */ | | */ | |
| lo_blob lo_blob_new(int32_t size, const void *data); | | lo_blob lo_blob_new(int32_t size, const void *data); | |
| | | | |
| /** | | /** | |
| * \brief Free the memory taken by a blob | | * \brief Free the memory taken by a blob | |
| */ | | */ | |
| void lo_blob_free(lo_blob b); | | void lo_blob_free(lo_blob b); | |
| | | | |
| /** | | /** | |
|
| * \brief Return the ammount of valid data in a lo blob object. | | * \brief Return the amount of valid data in a lo_blob object. | |
| * | | * | |
| * If you want to know the storage size, use lo_arg_size(). | | * If you want to know the storage size, use lo_arg_size(). | |
| */ | | */ | |
| uint32_t lo_blob_datasize(lo_blob b); | | uint32_t lo_blob_datasize(lo_blob b); | |
| | | | |
| /** | | /** | |
| * \brief Return a pointer to the start of the blob data to allow contents
to | | * \brief Return a pointer to the start of the blob data to allow contents
to | |
| * be changed. | | * be changed. | |
| */ | | */ | |
| void *lo_blob_dataptr(lo_blob b); | | void *lo_blob_dataptr(lo_blob b); | |
| | | | |
End of changes. 31 change blocks. |
| 31 lines changed or deleted | | 62 lines changed or added | |
|
| lo_lowlevel.h | | lo_lowlevel.h | |
| /* | | /* | |
| * Copyright (C) 2004 Steve Harris | | * Copyright (C) 2004 Steve Harris | |
| * | | * | |
|
| * This program is free software; you can redistribute it and/or modify | | * This program is free software; you can redistribute it and/or | |
| * it under the terms of the GNU General Public License as published by | | * modify it under the terms of the GNU Lesser General Public License | |
| * the Free Software Foundation; either version 2 of the License, or | | * as published by the Free Software Foundation; either version 2.1 | |
| * (at your option) any later version. | | * of the License, or (at your option) any later version. | |
| * | | * | |
| * This program is distributed in the hope that it will be useful, | | * This program is distributed in the hope that it will be useful, | |
| * but WITHOUT ANY WARRANTY; without even the implied warranty of | | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
|
| * GNU General Public License for more details. | | * GNU Lesser General Public License for more details. | |
| * | | * | |
| * $Id$ | | * $Id$ | |
| */ | | */ | |
| | | | |
| #ifndef LO_LOWLEVEL_H | | #ifndef LO_LOWLEVEL_H | |
| #define LO_LOWLEVEL_H | | #define LO_LOWLEVEL_H | |
| | | | |
| #include "lo/lo_osc_types.h" | | #include "lo/lo_osc_types.h" | |
| | | | |
|
| | | /** | |
| | | * \file lo_lowlevel.h The liblo headerfile defining the low-level API | |
| | | * functions. | |
| | | */ | |
| | | | |
| #ifdef __cplusplus | | #ifdef __cplusplus | |
| extern "C" { | | extern "C" { | |
| #endif | | #endif | |
| | | | |
| #include <stdarg.h> | | #include <stdarg.h> | |
|
| | | #ifdef _MSC_VER | |
| | | #define ssize_t SSIZE_T | |
| | | #define uint32_t unsigned __int32 | |
| | | #else | |
| #include <stdint.h> | | #include <stdint.h> | |
|
| | | #endif | |
| | | | |
| #include "lo/lo_types.h" | | #include "lo/lo_types.h" | |
| #include "lo/lo_errors.h" | | #include "lo/lo_errors.h" | |
| | | | |
| /** | | /** | |
| * \defgroup liblolowlevel Low-level OSC API | | * \defgroup liblolowlevel Low-level OSC API | |
| * | | * | |
|
| * Use these functions if you require more precices control over OSC messag
e | | * Use these functions if you require more precise control over OSC message | |
| * contruction or handling that what is provided in the high-level function
s | | * contruction or handling that what is provided in the high-level function
s | |
| * described in liblo. | | * described in liblo. | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * \brief Type used to represent numerical values in conversions between OS
C | | * \brief Type used to represent numerical values in conversions between OS
C | |
| * types. | | * types. | |
| */ | | */ | |
| typedef long double lo_hires; | | typedef long double lo_hires; | |
| | | | |
| /** | | /** | |
|
| * \brief send a lo_message object to target targ | | * \brief Send a lo_message object to target targ | |
| * | | * | |
|
| * This is slightly more efficient than lo_send if you want to send a lot o
f | | * This is slightly more efficient than lo_send() if you want to send a lot
of | |
| * similar messages. The messages are constructed with the lo_message_new()
and | | * similar messages. The messages are constructed with the lo_message_new()
and | |
|
| * lo_message_add*() functions. | | * \ref lo_message_add_int32 "lo_message_add*()" functions. | |
| */ | | */ | |
| int lo_send_message(lo_address targ, const char *path, lo_message msg); | | int lo_send_message(lo_address targ, const char *path, lo_message msg); | |
| | | | |
| /** | | /** | |
|
| * \brief send a lo_message object to target targ from address of serv | | * \brief Send a lo_message object to target targ from address of serv | |
| * | | * | |
|
| * This is slightly more efficient than lo_send if you want to send a lot o
f | | * This is slightly more efficient than lo_send() if you want to send a lot
of | |
| * similar messages. The messages are constructed with the lo_message_new()
and | | * similar messages. The messages are constructed with the lo_message_new()
and | |
|
| * lo_message_add*() functions. | | * \ref lo_message_add_int32 "lo_message_add*()" functions. | |
| * | | * | |
| * \param targ The address to send the message to | | * \param targ The address to send the message to | |
| * \param serv The server socket to send the message from | | * \param serv The server socket to send the message from | |
| * (can be NULL to use new socket) | | * (can be NULL to use new socket) | |
| * \param path The path to send the message to | | * \param path The path to send the message to | |
| * \param msg The bundle itself | | * \param msg The bundle itself | |
| */ | | */ | |
| int lo_send_message_from(lo_address targ, lo_server serv, | | int lo_send_message_from(lo_address targ, lo_server serv, | |
| const char *path, lo_message msg); | | const char *path, lo_message msg); | |
| | | | |
| /** | | /** | |
|
| * \brief send a lo_bundle object to address targ | | * \brief Send a lo_bundle object to address targ | |
| * | | * | |
| * Bundles are constructed with the | | * Bundles are constructed with the | |
| * lo_bundle_new() and lo_bundle_add_message() functions. | | * lo_bundle_new() and lo_bundle_add_message() functions. | |
| */ | | */ | |
| int lo_send_bundle(lo_address targ, lo_bundle b); | | int lo_send_bundle(lo_address targ, lo_bundle b); | |
| | | | |
| /** | | /** | |
|
| * \brief send a lo_bundle object to address targ from address of serv | | * \brief Send a lo_bundle object to address targ from address of serv | |
| * | | * | |
| * Bundles are constructed with the | | * Bundles are constructed with the | |
| * lo_bundle_new() and lo_bundle_add_message() functions. | | * lo_bundle_new() and lo_bundle_add_message() functions. | |
| * | | * | |
| * \param targ The address to send the bundle to | | * \param targ The address to send the bundle to | |
| * \param serv The server socket to send the bundle from | | * \param serv The server socket to send the bundle from | |
| * (can be NULL to use new socket) | | * (can be NULL to use new socket) | |
| * \param b The bundle itself | | * \param b The bundle itself | |
| */ | | */ | |
| int lo_send_bundle_from(lo_address targ, lo_server serv, lo_bundle b); | | int lo_send_bundle_from(lo_address targ, lo_server serv, lo_bundle b); | |
| | | | |
| /** | | /** | |
| * \brief Create a new lo_message object | | * \brief Create a new lo_message object | |
| */ | | */ | |
| lo_message lo_message_new(); | | lo_message lo_message_new(); | |
| | | | |
| /** | | /** | |
|
| * \brief Free memory allocated by lo_message_new and any subsequent | | * \brief Free memory allocated by lo_message_new() and any subsequent | |
| * lo_message_add*() calls. | | * \ref lo_message_add_int32 lo_message_add*() calls. | |
| */ | | */ | |
| void lo_message_free(lo_message m); | | void lo_message_free(lo_message m); | |
| | | | |
| /** | | /** | |
| * \brief Append a number of arguments to a message. | | * \brief Append a number of arguments to a message. | |
| * | | * | |
| * The data will be added in OSC byteorder (bigendian). | | * The data will be added in OSC byteorder (bigendian). | |
| * | | * | |
| * \param m The message to be extended. | | * \param m The message to be extended. | |
| * \param types The types of the data items in the message, types are defin
ed in | | * \param types The types of the data items in the message, types are defin
ed in | |
| * lo_types_common.h | | * lo_types_common.h | |
| * \param ... The data values to be transmitted. The types of the arguments | | * \param ... The data values to be transmitted. The types of the arguments | |
| * passed here must agree with the types specified in the type parameter. | | * passed here must agree with the types specified in the type parameter. | |
| * | | * | |
| * \return Less than 0 on failure, 0 on success. | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
| int lo_message_add(lo_message m, const char *types, ...); | | int lo_message_add(lo_message m, const char *types, ...); | |
| | | | |
|
| /** \brief the real message_add function (don't call directly) */ | | /** \internal \brief the real message_add function (don't call directly) */ | |
| int lo_message_add_internal(lo_message m, const char *file, const int line
, | | int lo_message_add_internal(lo_message m, const char *file, const int line
, | |
| const char *types, ...); | | const char *types, ...); | |
| | | | |
| /** | | /** | |
| * \brief Append a varargs list to a message. | | * \brief Append a varargs list to a message. | |
| * | | * | |
| * The data will be added in OSC byteorder (bigendian). | | * The data will be added in OSC byteorder (bigendian). | |
| * IMPORTANT: args list must be terminated with LO_ARGS_END, or this call w
ill | | * IMPORTANT: args list must be terminated with LO_ARGS_END, or this call w
ill | |
| * fail. This is used to do simple error checking on the sizes of paramete
rs | | * fail. This is used to do simple error checking on the sizes of paramete
rs | |
| * passed. | | * passed. | |
| | | | |
| skipping to change at line 143 | | skipping to change at line 153 | |
| * lo_types_common.h | | * lo_types_common.h | |
| * \param ap The va_list created by a C function declared with an | | * \param ap The va_list created by a C function declared with an | |
| * ellipsis (...) argument, and pre-initialised with | | * ellipsis (...) argument, and pre-initialised with | |
| * "va_start(ap)". The types of the arguments passed here must agree | | * "va_start(ap)". The types of the arguments passed here must agree | |
| * with the types specified in the type parameter. | | * with the types specified in the type parameter. | |
| * | | * | |
| * \return Less than 0 on failure, 0 on success. | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
| int lo_message_add_varargs(lo_message m, const char *types, va_list ap); | | int lo_message_add_varargs(lo_message m, const char *types, va_list ap); | |
| | | | |
|
| /** \brief the real message_add_varargs function (don't call directly) */ | | /** \internal \brief the real message_add_varargs function (don't call dire
ctly) */ | |
| int lo_message_add_varargs_internal(lo_message m, const char *types, va_lis
t ap, | | int lo_message_add_varargs_internal(lo_message m, const char *types, va_lis
t ap, | |
| const char *file, const int line); | | const char *file, const int line); | |
| | | | |
| /** | | /** | |
| * \brief Append a data item and typechar of the specified type to a messag
e. | | * \brief Append a data item and typechar of the specified type to a messag
e. | |
| * | | * | |
| * The data will be added in OSC byteorder (bigendian). | | * The data will be added in OSC byteorder (bigendian). | |
| * | | * | |
| * \param m The message to be extended. | | * \param m The message to be extended. | |
| * \param a The data item. | | * \param a The data item. | |
|
| | | * | |
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_message_add_int32(lo_message m, int32_t a); | | int lo_message_add_int32(lo_message m, int32_t a); | |
| | | | |
| /** | | /** | |
| * \brief Append a data item and typechar of the specified type to a messa
ge. | | * \brief Append a data item and typechar of the specified type to a messa
ge. | |
| * See lo_message_add_int32() for details. | | * See lo_message_add_int32() for details. | |
|
| | | * | |
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_message_add_float(lo_message m, float a); | | int lo_message_add_float(lo_message m, float a); | |
| | | | |
| /** | | /** | |
| * \brief Append a data item and typechar of the specified type to a messa
ge. | | * \brief Append a data item and typechar of the specified type to a messa
ge. | |
| * See lo_message_add_int32() for details. | | * See lo_message_add_int32() for details. | |
|
| | | * | |
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_message_add_string(lo_message m, const char *a); | | int lo_message_add_string(lo_message m, const char *a); | |
| | | | |
| /** | | /** | |
| * \brief Append a data item and typechar of the specified type to a messa
ge. | | * \brief Append a data item and typechar of the specified type to a messa
ge. | |
| * See lo_message_add_int32() for details. | | * See lo_message_add_int32() for details. | |
|
| | | * | |
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_message_add_blob(lo_message m, lo_blob a); | | int lo_message_add_blob(lo_message m, lo_blob a); | |
| | | | |
| /** | | /** | |
| * \brief Append a data item and typechar of the specified type to a messa
ge. | | * \brief Append a data item and typechar of the specified type to a messa
ge. | |
| * See lo_message_add_int32() for details. | | * See lo_message_add_int32() for details. | |
|
| | | * | |
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_message_add_int64(lo_message m, int64_t a); | | int lo_message_add_int64(lo_message m, int64_t a); | |
| | | | |
| /** | | /** | |
| * \brief Append a data item and typechar of the specified type to a messa
ge. | | * \brief Append a data item and typechar of the specified type to a messa
ge. | |
| * See lo_message_add_int32() for details. | | * See lo_message_add_int32() for details. | |
|
| | | * | |
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_message_add_timetag(lo_message m, lo_timetag a); | | int lo_message_add_timetag(lo_message m, lo_timetag a); | |
| | | | |
| /** | | /** | |
| * \brief Append a data item and typechar of the specified type to a messa
ge. | | * \brief Append a data item and typechar of the specified type to a messa
ge. | |
| * See lo_message_add_int32() for details. | | * See lo_message_add_int32() for details. | |
|
| | | * | |
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_message_add_double(lo_message m, double a); | | int lo_message_add_double(lo_message m, double a); | |
| | | | |
| /** | | /** | |
| * \brief Append a data item and typechar of the specified type to a messa
ge. | | * \brief Append a data item and typechar of the specified type to a messa
ge. | |
| * See lo_message_add_int32() for details. | | * See lo_message_add_int32() for details. | |
|
| | | * | |
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_message_add_symbol(lo_message m, const char *a); | | int lo_message_add_symbol(lo_message m, const char *a); | |
| | | | |
| /** | | /** | |
| * \brief Append a data item and typechar of the specified type to a messa
ge. | | * \brief Append a data item and typechar of the specified type to a messa
ge. | |
| * See lo_message_add_int32() for details. | | * See lo_message_add_int32() for details. | |
|
| | | * | |
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_message_add_char(lo_message m, char a); | | int lo_message_add_char(lo_message m, char a); | |
| | | | |
| /** | | /** | |
| * \brief Append a data item and typechar of the specified type to a messa
ge. | | * \brief Append a data item and typechar of the specified type to a messa
ge. | |
| * See lo_message_add_int32() for details. | | * See lo_message_add_int32() for details. | |
|
| | | * | |
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_message_add_midi(lo_message m, uint8_t a[4]); | | int lo_message_add_midi(lo_message m, uint8_t a[4]); | |
| | | | |
| /** | | /** | |
| * \brief Append a data item and typechar of the specified type to a messa
ge. | | * \brief Append a data item and typechar of the specified type to a messa
ge. | |
| * See lo_message_add_int32() for details. | | * See lo_message_add_int32() for details. | |
|
| | | * | |
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_message_add_true(lo_message m); | | int lo_message_add_true(lo_message m); | |
| | | | |
| /** | | /** | |
| * \brief Append a data item and typechar of the specified type to a messa
ge. | | * \brief Append a data item and typechar of the specified type to a messa
ge. | |
| * See lo_message_add_int32() for details. | | * See lo_message_add_int32() for details. | |
|
| | | * | |
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_message_add_false(lo_message m); | | int lo_message_add_false(lo_message m); | |
| | | | |
| /** | | /** | |
| * \brief Append a data item and typechar of the specified type to a messa
ge. | | * \brief Append a data item and typechar of the specified type to a messa
ge. | |
| * See lo_message_add_int32() for details. | | * See lo_message_add_int32() for details. | |
|
| | | * | |
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_message_add_nil(lo_message m); | | int lo_message_add_nil(lo_message m); | |
| | | | |
| /** | | /** | |
| * \brief Append a data item and typechar of the specified type to a messa
ge. | | * \brief Append a data item and typechar of the specified type to a messa
ge. | |
| * See lo_message_add_int32() for details. | | * See lo_message_add_int32() for details. | |
|
| | | * | |
| | | * \return Less than 0 on failure, 0 on success. | |
| */ | | */ | |
|
| void lo_message_add_infinitum(lo_message m); | | int lo_message_add_infinitum(lo_message m); | |
| | | | |
| /** | | /** | |
| * \brief Returns the source (lo_address) of an incoming message. | | * \brief Returns the source (lo_address) of an incoming message. | |
| * | | * | |
| * Returns NULL if the message is outgoing. Do not free the returned addres
s. | | * Returns NULL if the message is outgoing. Do not free the returned addres
s. | |
| */ | | */ | |
| lo_address lo_message_get_source(lo_message m); | | lo_address lo_message_get_source(lo_message m); | |
| | | | |
| /** | | /** | |
|
| | | * \brief Returns the timestamp (lo_timetag *) of a bundled incoming messa | |
| | | ge. | |
| | | * | |
| | | * Returns LO_TT_IMMEDIATE if the message is outgoing, or did not arrive | |
| | | * contained in a bundle. Do not free the returned timetag. | |
| | | */ | |
| | | lo_timetag lo_message_get_timestamp(lo_message m); | |
| | | | |
| | | /** | |
| * \brief Return the message type tag string. | | * \brief Return the message type tag string. | |
| * | | * | |
| * The result is valid until further data is added with lo_message_add*(). | | * The result is valid until further data is added with lo_message_add*(). | |
| */ | | */ | |
| char *lo_message_get_types(lo_message m); | | char *lo_message_get_types(lo_message m); | |
| | | | |
| /** | | /** | |
| * \brief Return the message argument count. | | * \brief Return the message argument count. | |
| * | | * | |
| * The result is valid until further data is added with lo_message_add*(). | | * The result is valid until further data is added with lo_message_add*(). | |
| | | | |
| skipping to change at line 304 | | skipping to change at line 350 | |
| * \param size The size of data in bytes | | * \param size The size of data in bytes | |
| * \param result If this pointer is non-NULL, the result or error code will | | * \param result If this pointer is non-NULL, the result or error code will | |
| * be written here. | | * be written here. | |
| * | | * | |
| * Returns a new lo_message, or NULL if deserialisation fails. | | * Returns a new lo_message, or NULL if deserialisation fails. | |
| * Use lo_message_free() to free the resulting object. | | * Use lo_message_free() to free the resulting object. | |
| */ | | */ | |
| lo_message lo_message_deserialise(void *data, size_t size, int *result); | | lo_message lo_message_deserialise(void *data, size_t size, int *result); | |
| | | | |
| /** | | /** | |
|
| | | * \brief Dispatch a raw block of memory containing an OSC message. | |
| | | * | |
| | | * This is useful when a raw block of memory is available that is | |
| | | * structured as OSC, and you wish to use liblo to dispatch the | |
| | | * message to a handler function as if it had been received over the | |
| | | * network. | |
| | | * | |
| | | * \param s The lo_server to use for dispatching. | |
| | | * \param data Pointer to the raw OSC message data in network transmission | |
| | | form | |
| | | * (network byte order where appropriate). | |
| | | * \param size The size of data in bytes | |
| | | * | |
| | | * Returns the number of bytes used if successful, or less than 0 otherwise | |
| | | . | |
| | | */ | |
| | | int lo_server_dispatch_data(lo_server s, void *data, size_t size); | |
| | | | |
| | | /** | |
| * \brief Return the hostname of a lo_address object | | * \brief Return the hostname of a lo_address object | |
| * | | * | |
|
| * Returned value most not be modified or free'd. Value will be a dotted qu
ad, | | * Returned value must not be modified or free'd. Value will be a dotted qu
ad, | |
| * colon'd IPV6 address, or resolvable name. | | * colon'd IPV6 address, or resolvable name. | |
| */ | | */ | |
| const char *lo_address_get_hostname(lo_address a); | | const char *lo_address_get_hostname(lo_address a); | |
| | | | |
| /** | | /** | |
| * \brief Return the port/service name of a lo_address object | | * \brief Return the port/service name of a lo_address object | |
| * | | * | |
|
| * Returned value most not be modified or free'd. Value will be a service n
ame | | * Returned value must not be modified or free'd. Value will be a service n
ame | |
| * or ASCII representation of the port number. | | * or ASCII representation of the port number. | |
| */ | | */ | |
| const char *lo_address_get_port(lo_address a); | | const char *lo_address_get_port(lo_address a); | |
| | | | |
| /** | | /** | |
| * \brief Return the protocol of a lo_address object | | * \brief Return the protocol of a lo_address object | |
| * | | * | |
| * Returned value will be one of LO_UDP, LO_TCP or LO_UNIX. | | * Returned value will be one of LO_UDP, LO_TCP or LO_UNIX. | |
| */ | | */ | |
| int lo_address_get_protocol(lo_address a); | | int lo_address_get_protocol(lo_address a); | |
| | | | |
| skipping to change at line 356 | | skipping to change at line 419 | |
| * \brief Get the Time-to-Live value for a given target address. | | * \brief Get the Time-to-Live value for a given target address. | |
| * | | * | |
| * \param t An OSC address. | | * \param t An OSC address. | |
| * \return An integer specifying the scope of a multicast UDP message. | | * \return An integer specifying the scope of a multicast UDP message. | |
| */ | | */ | |
| int lo_address_get_ttl(lo_address t); | | int lo_address_get_ttl(lo_address t); | |
| | | | |
| /** | | /** | |
| * \brief Create a new bundle object. | | * \brief Create a new bundle object. | |
| * | | * | |
|
| * OSC Bundles ecapsulate one or more OSC messages and may include a timest
amp | | * OSC Bundles encapsulate one or more OSC messages and may include a times
tamp | |
| * indicating when the bundle should be dispatched. | | * indicating when the bundle should be dispatched. | |
| * | | * | |
| * \param tt The timestamp when the bundle should be handled by the receive
r. | | * \param tt The timestamp when the bundle should be handled by the receive
r. | |
| * Pass LO_TT_IMMEDIATE if you want the receiving server to dispa
tch | | * Pass LO_TT_IMMEDIATE if you want the receiving server to dispa
tch | |
| * the bundle as soon as it receives it. | | * the bundle as soon as it receives it. | |
| */ | | */ | |
| lo_bundle lo_bundle_new(lo_timetag tt); | | lo_bundle lo_bundle_new(lo_timetag tt); | |
| | | | |
| /** | | /** | |
| * \brief Adds an OSC message to an existing bundle. | | * \brief Adds an OSC message to an existing bundle. | |
| * | | * | |
|
| * The message passsed is appended to the list of messages in the bundle to
be | | * The message passed is appended to the list of messages in the bundle to
be | |
| * dispatched to 'path'. | | * dispatched to 'path'. | |
|
| | | * | |
| | | * \return 0 if successful, less than 0 otherwise. | |
| */ | | */ | |
|
| void lo_bundle_add_message(lo_bundle b, const char *path, lo_message m); | | int lo_bundle_add_message(lo_bundle b, const char *path, lo_message m); | |
| | | | |
| /** | | /** | |
| * \brief Return the length of a bundle in bytes. | | * \brief Return the length of a bundle in bytes. | |
| * | | * | |
| * Includes the marker and typetage length. | | * Includes the marker and typetage length. | |
| * | | * | |
| * \param b The bundle to be sized | | * \param b The bundle to be sized | |
| */ | | */ | |
| size_t lo_bundle_length(lo_bundle b); | | size_t lo_bundle_length(lo_bundle b); | |
| | | | |
| | | | |
| skipping to change at line 412 | | skipping to change at line 477 | |
| void lo_bundle_free(lo_bundle b); | | void lo_bundle_free(lo_bundle b); | |
| | | | |
| /** | | /** | |
| * \brief Frees the memory taken by a bundle object and messages in the bu
ndle. | | * \brief Frees the memory taken by a bundle object and messages in the bu
ndle. | |
| * | | * | |
| * \param b The bundle, which may contain messages, to be freed. | | * \param b The bundle, which may contain messages, to be freed. | |
| */ | | */ | |
| void lo_bundle_free_messages(lo_bundle b); | | void lo_bundle_free_messages(lo_bundle b); | |
| | | | |
| /** | | /** | |
|
| * \brief return true if the type specified has a numerical value, such as | | * \brief Return true if the type specified has a numerical value, such as | |
| * LO_INT32, LO_FLOAT etc. | | * LO_INT32, LO_FLOAT etc. | |
| * | | * | |
| * \param a The type to be tested. | | * \param a The type to be tested. | |
| */ | | */ | |
| int lo_is_numerical_type(lo_type a); | | int lo_is_numerical_type(lo_type a); | |
| | | | |
| /** | | /** | |
|
| * \brief return true if the type specified has a textual value, such as | | * \brief Return true if the type specified has a textual value, such as | |
| * LO_STRING or LO_SYMBOL. | | * LO_STRING or LO_SYMBOL. | |
| * | | * | |
| * \param a The type to be tested. | | * \param a The type to be tested. | |
| */ | | */ | |
| int lo_is_string_type(lo_type a); | | int lo_is_string_type(lo_type a); | |
| | | | |
| /** | | /** | |
|
| * \brief attempt to convert one OSC type to another. | | * \brief Attempt to convert one OSC type to another. | |
| * | | * | |
| * Numerical types (eg LO_INT32, LO_FLOAT etc.) may be converted to other | | * Numerical types (eg LO_INT32, LO_FLOAT etc.) may be converted to other | |
| * numerical types and string types (LO_STRING and LO_SYMBOL) may be conver
ted | | * numerical types and string types (LO_STRING and LO_SYMBOL) may be conver
ted | |
| * to the other type. This is done automatically if a received message matc
hes | | * to the other type. This is done automatically if a received message matc
hes | |
| * the path, but not the exact types, and is coercible (ie. all numerical | | * the path, but not the exact types, and is coercible (ie. all numerical | |
| * types in numerical positions). | | * types in numerical positions). | |
| * | | * | |
| * On failure no translation occurs and false is returned. | | * On failure no translation occurs and false is returned. | |
| * | | * | |
| * \param type_to The type of the destination variable. | | * \param type_to The type of the destination variable. | |
| * \param to A pointer to the destination variable. | | * \param to A pointer to the destination variable. | |
| * \param type_from The type of the source variable. | | * \param type_from The type of the source variable. | |
| * \param from A pointer to the source variable. | | * \param from A pointer to the source variable. | |
| */ | | */ | |
| int lo_coerce(lo_type type_to, lo_arg *to, lo_type type_from, lo_arg *from)
; | | int lo_coerce(lo_type type_to, lo_arg *to, lo_type type_from, lo_arg *from)
; | |
| | | | |
| /** | | /** | |
|
| * \brief return the numerical value of the given argument with the | | * \brief Return the numerical value of the given argument with the | |
| * maximum native system precision. | | * maximum native system precision. | |
| */ | | */ | |
| lo_hires lo_hires_val(lo_type type, lo_arg *p); | | lo_hires lo_hires_val(lo_type type, lo_arg *p); | |
| | | | |
| /** | | /** | |
| * \brief Create a new server instance. | | * \brief Create a new server instance. | |
| * | | * | |
|
| * lo_servers block until they receive OSC messages. if you want non-blocki | | * Using lo_server_recv(), lo_servers block until they receive OSC | |
| ng | | * messages. If you want non-blocking behaviour see | |
| * behaviour see the lo_server_thread_* functions. | | * lo_server_recv_noblock() or the \ref lo_server_thread_new | |
| | | * "lo_server_thread_*" functions. | |
| * | | * | |
| * \param port If NULL is passed then an unused UDP port will be chosen by
the | | * \param port If NULL is passed then an unused UDP port will be chosen by
the | |
|
| * system, its number may be retreived with lo_server_thread_get_port() | | * system, its number may be retrieved with lo_server_thread_get_port() | |
| * so it can be passed to clients. Otherwise a decimal port number, service | | * so it can be passed to clients. Otherwise a decimal port number, service | |
| * name or UNIX domain socket path may be passed. | | * name or UNIX domain socket path may be passed. | |
| * \param err_h An error callback function that will be called if there is
an | | * \param err_h An error callback function that will be called if there is
an | |
| * error in messge reception or server creation. Pass NULL if you do not wa
nt | | * error in messge reception or server creation. Pass NULL if you do not wa
nt | |
| * error handling. | | * error handling. | |
| */ | | */ | |
| lo_server lo_server_new(const char *port, lo_err_handler err_h); | | lo_server lo_server_new(const char *port, lo_err_handler err_h); | |
| | | | |
| /** | | /** | |
| * \brief Create a new server instance, specifying protocol. | | * \brief Create a new server instance, specifying protocol. | |
| * | | * | |
|
| * lo_servers block until they receive OSC messages. if you want non-blocki | | * Using lo_server_recv(), lo_servers block until they receive OSC | |
| ng | | * messages. If you want non-blocking behaviour see | |
| * behaviour see the lo_server_thread_* functions. | | * lo_server_recv_noblock() or the \ref lo_server_thread_new | |
| | | * "lo_server_thread_*" functions. | |
| * | | * | |
| * \param port If using UDP then NULL may be passed to find an unused port. | | * \param port If using UDP then NULL may be passed to find an unused port. | |
| * Otherwise a decimal port number orservice name or may be passed. | | * Otherwise a decimal port number orservice name or may be passed. | |
| * If using UNIX domain sockets then a socket path should be passed here. | | * If using UNIX domain sockets then a socket path should be passed here. | |
| * \param proto The protocol to use, should be one of LO_UDP, LO_TCP or LO_
UNIX. | | * \param proto The protocol to use, should be one of LO_UDP, LO_TCP or LO_
UNIX. | |
| * \param err_h An error callback function that will be called if there is
an | | * \param err_h An error callback function that will be called if there is
an | |
| * error in messge reception or server creation. Pass NULL if you do not wa
nt | | * error in messge reception or server creation. Pass NULL if you do not wa
nt | |
| * error handling. | | * error handling. | |
| */ | | */ | |
| lo_server lo_server_new_with_proto(const char *port, int proto, | | lo_server lo_server_new_with_proto(const char *port, int proto, | |
| | | | |
| skipping to change at line 505 | | skipping to change at line 574 | |
| */ | | */ | |
| lo_server lo_server_new_multicast(const char *group, const char *port, | | lo_server lo_server_new_multicast(const char *group, const char *port, | |
| lo_err_handler err_h); | | lo_err_handler err_h); | |
| | | | |
| /** | | /** | |
| * \brief Free up memory used by the lo_server object | | * \brief Free up memory used by the lo_server object | |
| */ | | */ | |
| void lo_server_free(lo_server s); | | void lo_server_free(lo_server s); | |
| | | | |
| /** | | /** | |
|
| | | * \brief Wait for an OSC message to be received | |
| | | * | |
| | | * \param s The server to wait for connections on. | |
| | | * \param timeout A timeout in milliseconds to wait for the incoming packet | |
| | | . | |
| | | * a value of 0 will return immediately. | |
| | | * | |
| | | * The return value is 1 if there is a message waiting or 0 if | |
| | | * there is no message. If there is a message waiting you can now | |
| | | * call lo_server_recv() to receive that message. | |
| | | */ | |
| | | int lo_server_wait(lo_server s, int timeout); | |
| | | | |
| | | /** | |
| * \brief Look for an OSC message waiting to be received | | * \brief Look for an OSC message waiting to be received | |
| * | | * | |
| * \param s The server to wait for connections on. | | * \param s The server to wait for connections on. | |
| * \param timeout A timeout in milliseconds to wait for the incoming packet
. | | * \param timeout A timeout in milliseconds to wait for the incoming packet
. | |
|
| * a value of 0 will return immediatly. | | * a value of 0 will return immediately. | |
| * | | * | |
|
| * The return value is the number of bytes in the received message or 0 is | | * The return value is the number of bytes in the received message or 0 if | |
| * there is no message. The message will be dispatched to a matching method | | * there is no message. The message will be dispatched to a matching method | |
| * if one is found. | | * if one is found. | |
| */ | | */ | |
| int lo_server_recv_noblock(lo_server s, int timeout); | | int lo_server_recv_noblock(lo_server s, int timeout); | |
| | | | |
| /** | | /** | |
| * \brief Block, waiting for an OSC message to be received | | * \brief Block, waiting for an OSC message to be received | |
| * | | * | |
| * The return value is the number of bytes in the received message. The mes
sage | | * The return value is the number of bytes in the received message. The mes
sage | |
| * will be dispatched to a matching method if one is found. | | * will be dispatched to a matching method if one is found. | |
| | | | |
| skipping to change at line 562 | | skipping to change at line 644 | |
| const char *typespec); | | const char *typespec); | |
| | | | |
| /** | | /** | |
| * \brief Return the file descriptor of the server socket. | | * \brief Return the file descriptor of the server socket. | |
| * | | * | |
| * If the server protocol supports exposing the server's underlying | | * If the server protocol supports exposing the server's underlying | |
| * receive mechanism for monitoring with select() or poll(), this function | | * receive mechanism for monitoring with select() or poll(), this function | |
| * returns the file descriptor needed, otherwise, it returns -1. | | * returns the file descriptor needed, otherwise, it returns -1. | |
| * | | * | |
| * WARNING: when using this function beware that not all OSC packets that a
re | | * WARNING: when using this function beware that not all OSC packets that a
re | |
|
| * received are dispatched immediatly. lo_server_events_pending() and | | * received are dispatched immediately. lo_server_events_pending() and | |
| * lo_server_next_event_delay() can be used to tell if there are pending | | * lo_server_next_event_delay() can be used to tell if there are pending | |
| * events and how long before you should attempt to receive them. | | * events and how long before you should attempt to receive them. | |
| */ | | */ | |
| int lo_server_get_socket_fd(lo_server s); | | int lo_server_get_socket_fd(lo_server s); | |
| | | | |
| /** | | /** | |
| * \brief Return the port number that the server has bound to. | | * \brief Return the port number that the server has bound to. | |
| * | | * | |
| * Useful when NULL is passed for the port number and you wish to know how
to | | * Useful when NULL is passed for the port number and you wish to know how
to | |
| * address the server. | | * address the server. | |
| | | | |
| skipping to change at line 586 | | skipping to change at line 668 | |
| /** | | /** | |
| * \brief Return the protocol that the server is using. | | * \brief Return the protocol that the server is using. | |
| * | | * | |
| * Returned value will be one of LO_UDP, LO_TCP or LO_UNIX. | | * Returned value will be one of LO_UDP, LO_TCP or LO_UNIX. | |
| */ | | */ | |
| int lo_server_get_protocol(lo_server s); | | int lo_server_get_protocol(lo_server s); | |
| | | | |
| /** | | /** | |
| * \brief Return an OSC URL that can be used to contact the server. | | * \brief Return an OSC URL that can be used to contact the server. | |
| * | | * | |
|
| * The return value should bee free()'d when it is no longer needed. | | * The return value should be free()'d when it is no longer needed. | |
| */ | | */ | |
| char *lo_server_get_url(lo_server s); | | char *lo_server_get_url(lo_server s); | |
| | | | |
| /** | | /** | |
| * \brief Return true if there are scheduled events (eg. from bundles) | | * \brief Return true if there are scheduled events (eg. from bundles) | |
| * waiting to be dispatched by the server | | * waiting to be dispatched by the server | |
| */ | | */ | |
| int lo_server_events_pending(lo_server s); | | int lo_server_events_pending(lo_server s); | |
| | | | |
| /** | | /** | |
| | | | |
| skipping to change at line 609 | | skipping to change at line 691 | |
| * If the delay is greater than 100 seconds then it will return 100.0. | | * If the delay is greater than 100 seconds then it will return 100.0. | |
| */ | | */ | |
| double lo_server_next_event_delay(lo_server s); | | double lo_server_next_event_delay(lo_server s); | |
| | | | |
| /** | | /** | |
| * \brief Return the protocol portion of an OSC URL, eg. udp, tcp. | | * \brief Return the protocol portion of an OSC URL, eg. udp, tcp. | |
| * | | * | |
| * This library uses OSC URLs of the form: osc.prot://hostname:port/path if
the | | * This library uses OSC URLs of the form: osc.prot://hostname:port/path if
the | |
| * prot part is missing, UDP is assumed. | | * prot part is missing, UDP is assumed. | |
| * | | * | |
|
| * The return value should bee free()'d when it is no longer needed. | | * The return value should be free()'d when it is no longer needed. | |
| */ | | */ | |
| char *lo_url_get_protocol(const char *url); | | char *lo_url_get_protocol(const char *url); | |
| | | | |
| /** | | /** | |
|
| | | * \brief Return the protocol ID of an OSC URL. | |
| | | * | |
| | | * This library uses OSC URLs of the form: osc.prot://hostname:port/path if | |
| | | the | |
| | | * prot part is missing, UDP is assumed. | |
| | | * Returned value will be one of LO_UDP, LO_TCP, LO_UNIX or -1. | |
| | | * | |
| | | * \return An integer specifying the protocol. Return -1 when the protocol | |
| | | is | |
| | | * not supported by liblo. | |
| | | * | |
| | | */ | |
| | | int lo_url_get_protocol_id(const char *url); | |
| | | | |
| | | /** | |
| * \brief Return the hostname portion of an OSC URL. | | * \brief Return the hostname portion of an OSC URL. | |
| * | | * | |
|
| * The return value should bee free()'d when it is no longer needed. | | * The return value should be free()'d when it is no longer needed. | |
| */ | | */ | |
| char *lo_url_get_hostname(const char *url); | | char *lo_url_get_hostname(const char *url); | |
| | | | |
| /** | | /** | |
| * \brief Return the port portion of an OSC URL. | | * \brief Return the port portion of an OSC URL. | |
| * | | * | |
|
| * The return value should bee free()'d when it is no longer needed. | | * The return value should be free()'d when it is no longer needed. | |
| */ | | */ | |
| char *lo_url_get_port(const char *url); | | char *lo_url_get_port(const char *url); | |
| | | | |
| /** | | /** | |
| * \brief Return the path portion of an OSC URL. | | * \brief Return the path portion of an OSC URL. | |
| * | | * | |
|
| * The return value should bee free()'d when it is no longer needed. | | * The return value should be free()'d when it is no longer needed. | |
| */ | | */ | |
| char *lo_url_get_path(const char *url); | | char *lo_url_get_path(const char *url); | |
| | | | |
| /* utility functions */ | | /* utility functions */ | |
| | | | |
| /** | | /** | |
| * \brief A function to calculate the amount of OSC message space required
by a | | * \brief A function to calculate the amount of OSC message space required
by a | |
| * C char *. | | * C char *. | |
| * | | * | |
|
| * Returns the storage size in bytes, will always be a multiple of four. | | * Returns the storage size in bytes, which will always be a multiple of fo
ur. | |
| */ | | */ | |
| int lo_strsize(const char *s); | | int lo_strsize(const char *s); | |
| | | | |
| /** | | /** | |
| * \brief A function to calculate the amount of OSC message space required
by a | | * \brief A function to calculate the amount of OSC message space required
by a | |
| * lo_blob object. | | * lo_blob object. | |
| * | | * | |
|
| * Returns the storage size in bytes, will always be a multiple of four. | | * Returns the storage size in bytes, which will always be a multiple of fo
ur. | |
| */ | | */ | |
| uint32_t lo_blobsize(lo_blob b); | | uint32_t lo_blobsize(lo_blob b); | |
| | | | |
| /** | | /** | |
| * \brief Test a string against an OSC pattern glob | | * \brief Test a string against an OSC pattern glob | |
| * | | * | |
|
| * \param str The tring to test | | * \param str The string to test | |
| * \param p The pattern to test against | | * \param p The pattern to test against | |
| */ | | */ | |
| int lo_pattern_match(const char *str, const char *p); | | int lo_pattern_match(const char *str, const char *p); | |
| | | | |
|
| /** \brief the real send function (don't call directly) */ | | /** \internal \brief the real send function (don't call directly) */ | |
| int lo_send_internal(lo_address t, const char *file, const int line, | | int lo_send_internal(lo_address t, const char *file, const int line, | |
| const char *path, const char *types, ...); | | const char *path, const char *types, ...); | |
|
| /** \brief the real send_timestamped function (don't call directly) */ | | /** \internal \brief the real send_timestamped function (don't call directl
y) */ | |
| int lo_send_timestamped_internal(lo_address t, const char *file, const int
line, | | int lo_send_timestamped_internal(lo_address t, const char *file, const int
line, | |
| lo_timetag ts, const char *path, const char *types, ...); | | lo_timetag ts, const char *path, const char *types, ...); | |
|
| /** \brief the real lo_send_from function (don't call directly) */ | | /** \internal \brief the real lo_send_from() function (don't call directly)
*/ | |
| int lo_send_from_internal(lo_address targ, lo_server from, const char *file
, | | int lo_send_from_internal(lo_address targ, lo_server from, const char *file
, | |
| const int line, const lo_timetag ts, | | const int line, const lo_timetag ts, | |
| const char *path, const char *types, ...); | | const char *path, const char *types, ...); | |
| | | | |
| /** \brief Find the time difference between two timetags | | /** \brief Find the time difference between two timetags | |
| * | | * | |
| * Returns a - b in seconds. | | * Returns a - b in seconds. | |
| */ | | */ | |
| double lo_timetag_diff(lo_timetag a, lo_timetag b); | | double lo_timetag_diff(lo_timetag a, lo_timetag b); | |
| | | | |
| /** \brief Return a timetag for the current time | | /** \brief Return a timetag for the current time | |
| * | | * | |
|
| * On exit the timetag pointed to by t is filled with the OSC represenation | | * On exit the timetag pointed to by t is filled with the OSC | |
| * of this instant in time. | | * representation of this instant in time. | |
| */ | | */ | |
| void lo_timetag_now(lo_timetag *t); | | void lo_timetag_now(lo_timetag *t); | |
| | | | |
|
| | | /** | |
| | | * \brief Return the storage size, in bytes, of the given argument. | |
| | | */ | |
| | | size_t lo_arg_size(lo_type type, void *data); | |
| | | | |
| | | /** | |
| | | * \brief Given a raw OSC message, return the message path. | |
| | | * | |
| | | * \param data A pointer to the raw OSC message data. | |
| | | * \param size The size of data in bytes (total buffer bytes). | |
| | | * | |
| | | * Returns the message path or NULL if an error occurs. | |
| | | * Do not free() the returned pointer. | |
| | | */ | |
| | | char *lo_get_path(void *data, ssize_t size); | |
| | | | |
| | | /** | |
| | | * \brief Convert the specified argument to host byte order where necessary | |
| | | . | |
| | | * | |
| | | * \param type The OSC type of the data item (eg. LO_FLOAT). | |
| | | * \param data A pointer to the data item to be converted. It is changed | |
| | | * in-place. | |
| | | */ | |
| | | void lo_arg_host_endian(lo_type type, void *data); | |
| | | | |
| | | /** | |
| | | * \brief Convert the specified argument to network byte order where necess | |
| | | ary. | |
| | | * | |
| | | * \param type The OSC type of the data item (eg. LO_FLOAT). | |
| | | * \param data A pointer to the data item to be converted. It is changed | |
| | | * in-place. | |
| | | */ | |
| | | void lo_arg_network_endian(lo_type type, void *data); | |
| | | | |
| /** @} */ | | /** @} */ | |
| | | | |
| /* prettyprinters */ | | /* prettyprinters */ | |
| | | | |
| /** | | /** | |
| * \defgroup pp Prettyprinting functions | | * \defgroup pp Prettyprinting functions | |
| * | | * | |
|
| * These functions all print an ASCII representation of thier argument to | | * These functions all print an ASCII representation of their argument to | |
| * stdout. Useful for debugging. | | * stdout. Useful for debugging. | |
| * @{ | | * @{ | |
| */ | | */ | |
|
| | | | |
| | | /** \brief Pretty-print a lo_bundle object. */ | |
| void lo_bundle_pp(lo_bundle b); | | void lo_bundle_pp(lo_bundle b); | |
|
| | | | |
| | | /** \brief Pretty-print a lo_message object. */ | |
| void lo_message_pp(lo_message m); | | void lo_message_pp(lo_message m); | |
|
| | | | |
| | | /** \brief Pretty-print a set of typed arguments. | |
| | | * \param type A type string in the form provided to lo_send(). | |
| | | * \param data An OSC data pointer, like that provided in the | |
| | | * lo_method_handler. | |
| | | */ | |
| void lo_arg_pp(lo_type type, void *data); | | void lo_arg_pp(lo_type type, void *data); | |
|
| | | | |
| | | /** \brief Pretty-print a lo_server object. */ | |
| void lo_server_pp(lo_server s); | | void lo_server_pp(lo_server s); | |
|
| | | | |
| | | /** \brief Pretty-print a lo_method object. */ | |
| void lo_method_pp(lo_method m); | | void lo_method_pp(lo_method m); | |
|
| | | | |
| | | /** \brief Pretty-print a lo_method object, but prepend a given prefix | |
| | | * to all field names. */ | |
| void lo_method_pp_prefix(lo_method m, const char *p); | | void lo_method_pp_prefix(lo_method m, const char *p); | |
|
| | | | |
| | | /** \brief Pretty-print a lo_server_thread object. */ | |
| void lo_server_thread_pp(lo_server_thread st); | | void lo_server_thread_pp(lo_server_thread st); | |
| /** @} */ | | /** @} */ | |
| | | | |
| #ifdef __cplusplus | | #ifdef __cplusplus | |
| } | | } | |
| #endif | | #endif | |
| | | | |
| #endif | | #endif | |
| | | | |
End of changes. 86 change blocks. |
| 65 lines changed or deleted | | 219 lines changed or added | |
|