.TH "liblo" 3 "Version 0.36" "liblo" \" -*- nroff -*-
.ad l
.nh
.SH NAME
liblo \- High-level OSC API
.SH SYNOPSIS
.br
.PP
.SS "Data Structures"
.in +1c
.ti -1c
.RI "struct \fBlo_timetag\fP"
.br
.RI "A structure to store OSC TimeTag values\&. "
.ti -1c
.RI "union \fBlo_arg\fP"
.br
.RI "Union used to read values from incoming messages\&. "
.in -1c
.SS "Macros"
.in +1c
.ti -1c
.RI "#define \fBLO_TT_IMMEDIATE\fP ((\fBlo_timetag\fP){0U,1U})"
.br
.RI "A timetag constant representing "now"\&. "
.in -1c
.SS "Enumerations"
.in +1c
.ti -1c
.RI "enum \fBlo_element_type\fP { \fBLO_ELEMENT_MESSAGE\fP = 1, \fBLO_ELEMENT_BUNDLE\fP = 2 }"
.br
.RI "An enumeration of bundle element types liblo can handle\&. "
.ti -1c
.RI "enum \fBlo_type\fP { \fBLO_INT32\fP = 'i', \fBLO_FLOAT\fP = 'f', \fBLO_STRING\fP = 's', \fBLO_BLOB\fP = 'b', \fBLO_INT64\fP = 'h', \fBLO_TIMETAG\fP = 't', \fBLO_DOUBLE\fP = 'd', \fBLO_SYMBOL\fP = 'S', \fBLO_CHAR\fP = 'c', \fBLO_MIDI\fP = 'm', \fBLO_TRUE\fP = 'T', \fBLO_FALSE\fP = 'F', \fBLO_NIL\fP = 'N', \fBLO_INFINITUM\fP = 'I' }"
.br
.RI "An enumeration of the OSC types liblo can send and receive\&. "
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.RI "\fBlo_address\fP \fBlo_address_new\fP (const char *host, const char *port)"
.br
.RI "Declare an OSC destination, given IP address and port number\&. Same as \fBlo_address_new_with_proto()\fP, but using UDP\&. "
.ti -1c
.RI "\fBlo_address\fP \fBlo_address_new_with_proto\fP (int proto, const char *host, const char *port)"
.br
.RI "Declare an OSC destination, given IP address and port number, specifying protocol\&. "
.ti -1c
.RI "\fBlo_address\fP \fBlo_address_new_from_url\fP (const char *url)"
.br
.RI "Create a \fBlo_address\fP object from an OSC URL\&. "
.ti -1c
.RI "void \fBlo_address_free\fP (\fBlo_address\fP t)"
.br
.RI "Free the memory used by the \fBlo_address\fP object\&. "
.ti -1c
.RI "void \fBlo_address_set_ttl\fP (\fBlo_address\fP t, int ttl)"
.br
.RI "Set the Time-to-Live value for a given target address\&. "
.ti -1c
.RI "int \fBlo_address_get_ttl\fP (\fBlo_address\fP t)"
.br
.RI "Get the Time-to-Live value for a given target address\&. "
.ti -1c
.RI "int \fBlo_send\fP (\fBlo_address\fP targ, const char *path, const char *type,\&.\&.\&.)"
.br
.RI "Send a OSC formatted message to the address specified\&. "
.ti -1c
.RI "int \fBlo_send_from\fP (\fBlo_address\fP targ, \fBlo_server\fP from, \fBlo_timetag\fP ts, const char *path, const char *type,\&.\&.\&.)"
.br
.RI "Send a OSC formatted message to the address specified, from the same socket as the specified server\&. "
.ti -1c
.RI "int \fBlo_send_timestamped\fP (\fBlo_address\fP targ, \fBlo_timetag\fP ts, const char *path, const char *type,\&.\&.\&.)"
.br
.RI "Send a OSC formatted message to the address specified, scheduled to be dispatch at some time in the future\&. "
.ti -1c
.RI "int \fBlo_address_errno\fP (\fBlo_address\fP a)"
.br
.RI "Return the error number from the last failed \fBlo_send()\fP or \fBlo_address_new()\fP call\&. "
.ti -1c
.RI "const char * \fBlo_address_errstr\fP (\fBlo_address\fP a)"
.br
.RI "Return the error string from the last failed \fBlo_send()\fP or \fBlo_address_new()\fP call\&. "
.ti -1c
.RI "\fBlo_blob\fP \fBlo_blob_new\fP (int32_t size, const void *data)"
.br
.RI "Create a new OSC blob type\&. "
.ti -1c
.RI "void \fBlo_blob_free\fP (\fBlo_blob\fP b)"
.br
.RI "Free the memory taken by a blob\&. "
.ti -1c
.RI "uint32_t \fBlo_blob_datasize\fP (\fBlo_blob\fP b)"
.br
.RI "Return the amount of valid data in a \fBlo_blob\fP object\&. "
.ti -1c
.RI "void * \fBlo_blob_dataptr\fP (\fBlo_blob\fP b)"
.br
.RI "Return a pointer to the start of the blob data to allow contents to be changed\&. "
.ti -1c
.RI "void \fBlo_version\fP (char *verstr, int verstr_size, int *major, int *minor, char *extra, int extra_size, int *lt_major, int *lt_minor, int *lt_bug)"
.br
.RI "Get information on the version of liblo current in use\&. "
.in -1c
.SH "Detailed Description"
.PP
Defines the high-level API functions necessary to implement OSC support\&. Should be adequate for most applications, but if you require lower level control you can use the functions defined in \fBlo_lowlevel\&.h\fP
.SH "Macro Definition Documentation"
.PP
.SS "#define LO_TT_IMMEDIATE ((\fBlo_timetag\fP){0U,1U})"
.PP
A timetag constant representing "now"\&.
.PP
Definition at line \fB151\fP of file \fBlo_osc_types\&.h\fP\&.
.PP
Referenced by \fBlo::immediate()\fP\&.
.SH "Enumeration Type Documentation"
.PP
.SS "enum \fBlo_element_type\fP"
.PP
An enumeration of bundle element types liblo can handle\&. The element of a bundle can either be a message or an other bundle\&.
.PP
\fBEnumerator\fP
.in +1c
.TP
\f(BILO_ELEMENT_MESSAGE \fP
bundle element is a message
.TP
\f(BILO_ELEMENT_BUNDLE \fP
bundle element is a bundle
.PP
Definition at line \fB48\fP of file \fBlo_osc_types\&.h\fP\&.
.SS "enum \fBlo_type\fP"
.PP
An enumeration of the OSC types liblo can send and receive\&. The value of the enumeration is the typechar used to tag messages and to specify arguments with \fBlo_send()\fP\&.
.PP
\fBEnumerator\fP
.in +1c
.TP
\f(BILO_INT32 \fP
32 bit signed integer\&.
.TP
\f(BILO_FLOAT \fP
32 bit IEEE-754 float\&.
.TP
\f(BILO_STRING \fP
Standard C, NULL terminated string\&.
.TP
\f(BILO_BLOB \fP
OSC binary blob type\&. Accessed using the lo_blob_*() functions\&.
.TP
\f(BILO_INT64 \fP
64 bit signed integer\&.
.TP
\f(BILO_TIMETAG \fP
OSC TimeTag type, represented by the \fBlo_timetag\fP structure\&.
.TP
\f(BILO_DOUBLE \fP
64 bit IEEE-754 double\&.
.TP
\f(BILO_SYMBOL \fP
Standard C, NULL terminated, string\&. Used in systems which distinguish strings and symbols\&.
.TP
\f(BILO_CHAR \fP
Standard C, 8 bit, char variable\&.
.TP
\f(BILO_MIDI \fP
A 4 byte MIDI packet\&.
.TP
\f(BILO_TRUE \fP
Sybol representing the value True\&.
.TP
\f(BILO_FALSE \fP
Sybol representing the value False\&.
.TP
\f(BILO_NIL \fP
Sybol representing the value Nil\&.
.TP
\f(BILO_INFINITUM \fP
Sybol representing the value Infinitum\&.
.PP
Definition at line \fB61\fP of file \fBlo_osc_types\&.h\fP\&.
.SH "Function Documentation"
.PP
.SS "int lo_address_errno (\fBlo_address\fP a)"
.PP
Return the error number from the last failed \fBlo_send()\fP or \fBlo_address_new()\fP call\&.
.SS "const char * lo_address_errstr (\fBlo_address\fP a)"
.PP
Return the error string from the last failed \fBlo_send()\fP or \fBlo_address_new()\fP call\&.
.SS "void lo_address_free (\fBlo_address\fP t)"
.PP
Free the memory used by the \fBlo_address\fP object\&.
.SS "int lo_address_get_ttl (\fBlo_address\fP t)"
.PP
Get the Time-to-Live value for a given target address\&.
.PP
\fBParameters\fP
.RS 4
\fIt\fP An OSC address\&.
.RE
.PP
\fBReturns\fP
.RS 4
An integer specifying the scope of a multicast UDP message\&.
.RE
.PP
.SS "\fBlo_address\fP lo_address_new (const char * host, const char * port)"
.PP
Declare an OSC destination, given IP address and port number\&. Same as \fBlo_address_new_with_proto()\fP, but using UDP\&.
.PP
\fBParameters\fP
.RS 4
\fIhost\fP An IP address or number, or NULL for the local machine\&.
.br
\fIport\fP a decimal port number or service name\&.
.RE
.PP
The \fBlo_address\fP object may be used as the target of OSC messages\&.
.PP
Note: if you wish to receive replies from the target of this address, you must either supply a \fBlo_server\fP by using \fBlo_send_from()\fP or \fBlo_send_message_from()\fP to send your message, otherwise the last \fBlo_server\fP or \fBlo_server_thread\fP that was created will be used as the reply socket\&. The remote receiver may get the reply address by calling \fBlo_message_get_source()\fP in the message handler\&. See \fBexample_tcp_echo_server\&.c\fP for an example of how to establish bidirectional communication\&.
.SS "\fBlo_address\fP lo_address_new_from_url (const char * url)"
.PP
Create a \fBlo_address\fP object from an OSC URL\&. example: \fR"osc\&.udp://localhost:4444/my/path/"\fP
.SS "\fBlo_address\fP lo_address_new_with_proto (int proto, const char * host, const char * port)"
.PP
Declare an OSC destination, given IP address and port number, specifying protocol\&.
.PP
\fBParameters\fP
.RS 4
\fIproto\fP The protocol to use, must be one of LO_UDP, LO_TCP or LO_UNIX\&.
.br
\fIhost\fP An IP address or number, or NULL for the local machine\&.
.br
\fIport\fP a decimal port number or service name\&.
.RE
.PP
The \fBlo_address\fP object may be used as the target of OSC messages\&.
.PP
Note: if you wish to receive replies from the target of this address, you must first create a \fBlo_server_thread\fP or \fBlo_server\fP object which will receive the replies\&. The last \fBlo_server(_thread)\fP object created will be the receiver\&.
.SS "void lo_address_set_ttl (\fBlo_address\fP t, int ttl)"
.PP
Set the Time-to-Live value for a given target address\&. This is required for sending multicast UDP messages\&. A value of 1 (the usual case) keeps the message within the subnet, while 255 means a global, unrestricted scope\&.
.PP
\fBParameters\fP
.RS 4
\fIt\fP An OSC address\&.
.br
\fIttl\fP An integer specifying the scope of a multicast UDP message\&.
.RE
.PP
.SS "void * lo_blob_dataptr (\fBlo_blob\fP b)"
.PP
Return a pointer to the start of the blob data to allow contents to be changed\&. If the size is 0, this will return a NULL-pointer\&.
.SS "uint32_t lo_blob_datasize (\fBlo_blob\fP b)"
.PP
Return the amount of valid data in a \fBlo_blob\fP object\&. If you want to know the storage size, use \fBlo_arg_size()\fP\&.
.SS "void lo_blob_free (\fBlo_blob\fP b)"
.PP
Free the memory taken by a blob\&.
.SS "\fBlo_blob\fP lo_blob_new (int32_t size, const void * data)"
.PP
Create a new OSC blob type\&.
.PP
\fBParameters\fP
.RS 4
\fIsize\fP The amount of space to allocate in the blob structure\&.
.br
\fIdata\fP The data that will be used to initialise the blob, should be size bytes long\&.
.RE
.PP
.SS "int lo_send (\fBlo_address\fP targ, const char * path, const char * type, \&.\&.\&.)"
.PP
Send a OSC formatted message to the address specified\&.
.PP
\fBParameters\fP
.RS 4
\fItarg\fP The target OSC address
.br
\fIpath\fP The OSC path the message will be delivered to
.br
\fItype\fP The types of the data items in the message, types are defined in \fBlo_osc_types\&.h\fP
.br
\fI\&.\&.\&.\fP The data values to be transmitted\&. The types of the arguments passed here must agree with the types specified in the type parameter\&.
.RE
.PP
example:
.PP
.nf
lo_send(t, "/foo/bar", "ff", 0\&.1f, 23\&.0f);
.fi
.PP
.PP
\fBReturns\fP
.RS 4
-1 on failure\&.
.RE
.PP
.SS "int lo_send_from (\fBlo_address\fP targ, \fBlo_server\fP from, \fBlo_timetag\fP ts, const char * path, const char * type, \&.\&.\&.)"
.PP
Send a OSC formatted message to the address specified, from the same socket as the specified server\&. If a liblo server is receiving this message, it can reply by getting the server's address by calling \fBlo_message_get_source()\fP in the message handler, passing the \fBlo_message\fP provided as an argument to the \fBlo_method_handler\fP\&. By this mechanism bidirectional communication can be established by setting up a \fBlo_server\fP or \fBlo_server_thread\fP on both sides\&.
.PP
\fBParameters\fP
.RS 4
\fItarg\fP The target OSC address
.br
\fIfrom\fP The server to send message from (can be NULL to use new socket)
.br
\fIts\fP The OSC timetag timestamp at which the message will be processed (can be LO_TT_IMMEDIATE if you don't want to attach a timetag)
.br
\fIpath\fP The OSC path the message will be delivered to
.br
\fItype\fP The types of the data items in the message, types are defined in \fBlo_osc_types\&.h\fP
.br
\fI\&.\&.\&.\fP The data values to be transmitted\&. The types of the arguments passed here must agree with the types specified in the type parameter\&.
.RE
.PP
example:
.PP
.nf
serv = lo_server_new(NULL, err);
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);
.fi
.PP
.PP
See \fBexample_tcp_echo_server\&.c\fP for an example of how to use \fBlo_message_get_source()\fP as described\&.
.PP
\fBReturns\fP
.RS 4
on success, the number of bytes sent, or -1 on failure\&.
.RE
.PP
.SS "int lo_send_timestamped (\fBlo_address\fP targ, \fBlo_timetag\fP ts, const char * path, const char * type, \&.\&.\&.)"
.PP
Send a OSC formatted message to the address specified, scheduled to be dispatch at some time in the future\&.
.PP
\fBParameters\fP
.RS 4
\fItarg\fP The target OSC address
.br
\fIts\fP The OSC timetag timestamp at which the message will be processed
.br
\fIpath\fP The OSC path the message will be delivered to
.br
\fItype\fP The types of the data items in the message, types are defined in \fBlo_osc_types\&.h\fP
.br
\fI\&.\&.\&.\fP The data values to be transmitted\&. The types of the arguments passed here must agree with the types specified in the type parameter\&.
.RE
.PP
example:
.PP
.nf
lo_timetag now;
lo_timetag_now(&now);
lo_send_timestamped(t, now, "/foo/bar", "ff", 0\&.1f, 23\&.0f);
.fi
.PP
.PP
\fBReturns\fP
.RS 4
on success, the number of bytes sent, or -1 on failure\&.
.RE
.PP
.SS "void lo_version (char * verstr, int verstr_size, int * major, int * minor, char * extra, int extra_size, int * lt_major, int * lt_minor, int * lt_bug)"
.PP
Get information on the version of liblo current in use\&. All parameters are optional and can be given the value of 0 if that information is not desired\&. For example, to get just the version as a string, call lo_version(str, size, 0, 0, 0, 0, 0, 0, 0);
.PP
The "lt" fields, called the ABI version, corresponds to libtool's versioning system for binary interface compatibility, and is not related to the library version number\&. This information is usually encoded in the filename of the shared library\&.
.PP
Typically the string returned in 'verstr' should correspond with $major\&.$minor$extra, e\&.g\&., "0\&.28rc"\&. If no 'extra' information is present, e\&.g\&., "0\&.28", extra will given the null string\&.
.PP
\fBParameters\fP
.RS 4
\fIverstr\fP A buffer to receive a string describing the library version\&.
.br
\fIverstr_size\fP Size of the buffer pointed to by string\&.
.br
\fImajor\fP Location to receive the library major version\&.
.br
\fIminor\fP Location to receive the library minor version\&.
.br
\fIextra\fP Location to receive the library version extra string\&.
.br
\fIextra_size\fP Size of the buffer pointed to by extra\&.
.br
\fIlt_major\fP Location to receive the ABI major version\&.
.br
\fIlt_minor\fP Location to receive the ABI minor version\&.
.br
\fIlt_bug\fP Location to receive the ABI 'bugfix' version\&.
.RE
.PP
.PP
Referenced by \fBlo::version()\fP\&.
.SH "Author"
.PP
Generated automatically by Doxygen for liblo from the source code\&.