.TH "lo_serverthread.h" 3 "Version 0.34" "liblo" \" -*- nroff -*-
.ad l
.nh
.SH NAME
lo_serverthread.h
.SH SYNOPSIS
.br
.PP
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBlo_server_thread\fP \fBlo_server_thread_new\fP (const char *port, \fBlo_err_handler\fP err_h)"
.br
.RI "Create a new server thread to handle incoming OSC messages\&. "
.ti -1c
.RI "\fBlo_server_thread\fP \fBlo_server_thread_new_multicast\fP (const char *group, const char *port, \fBlo_err_handler\fP err_h)"
.br
.RI "Create a new server thread to handle incoming OSC messages, and join a UDP multicast group\&. "
.ti -1c
.RI "\fBlo_server_thread\fP \fBlo_server_thread_new_multicast_iface\fP (const char *group, const char *port, const char *iface, const char *ip, \fBlo_err_handler\fP err_h)"
.br
.RI "Create a new server thread instance, and join a UDP multicast group, optionally specifying which network interface to use\&. Note that usually only one of iface or ip are specified\&. "
.ti -1c
.RI "\fBlo_server_thread\fP \fBlo_server_thread_new_with_proto\fP (const char *port, int proto, \fBlo_err_handler\fP err_h)"
.br
.RI "Create a new server thread to handle incoming OSC messages, specifying protocol\&. "
.ti -1c
.RI "\fBlo_server_thread\fP \fBlo_server_thread_new_from_url\fP (const char *url, \fBlo_err_handler\fP err_h)"
.br
.RI "Create a new server thread, taking port and the optional multicast group IP from an URL string\&. "
.ti -1c
.RI "\fBlo_server_thread\fP \fBlo_server_thread_new_from_config\fP (\fBlo_server_config\fP *config)"
.br
.RI "Create a new server thread, using a configuration struct\&. "
.ti -1c
.RI "void \fBlo_server_thread_free\fP (\fBlo_server_thread\fP st)"
.br
.RI "Free memory taken by a server thread\&. "
.ti -1c
.RI "\fBlo_method\fP \fBlo_server_thread_add_method\fP (\fBlo_server_thread\fP st, const char *path, const char *typespec, \fBlo_method_handler\fP h, const void *user_data)"
.br
.RI "Add an OSC method to the specifed server thread\&. "
.ti -1c
.RI "void \fBlo_server_thread_del_method\fP (\fBlo_server_thread\fP st, const char *path, const char *typespec)"
.br
.RI "Delete an OSC method from the specifed server thread\&. "
.ti -1c
.RI "int \fBlo_server_thread_del_lo_method\fP (\fBlo_server_thread\fP st, \fBlo_method\fP m)"
.br
.RI "Delete an OSC method from the specified server thread\&. "
.ti -1c
.RI "void \fBlo_server_thread_set_callbacks\fP (\fBlo_server_thread\fP st, \fBlo_server_thread_init_callback\fP init, \fBlo_server_thread_cleanup_callback\fP cleanup, void *user_data)"
.br
.RI "Set an init and/or a cleanup function to the specifed server thread\&. "
.ti -1c
.RI "int \fBlo_server_thread_start\fP (\fBlo_server_thread\fP st)"
.br
.RI "Start the server thread\&. "
.ti -1c
.RI "int \fBlo_server_thread_stop\fP (\fBlo_server_thread\fP st)"
.br
.RI "Stop the server thread\&. "
.ti -1c
.RI "int \fBlo_server_thread_get_port\fP (\fBlo_server_thread\fP st)"
.br
.RI "Return the port number that the server thread has bound to\&. "
.ti -1c
.RI "char * \fBlo_server_thread_get_url\fP (\fBlo_server_thread\fP st)"
.br
.RI "Return a URL describing the address of the server thread\&. "
.ti -1c
.RI "\fBlo_server\fP \fBlo_server_thread_get_server\fP (\fBlo_server_thread\fP st)"
.br
.RI "Return the \fBlo_server\fP for a \fBlo_server_thread\fP\&. "
.ti -1c
.RI "int \fBlo_server_thread_events_pending\fP (\fBlo_server_thread\fP st)"
.br
.RI "Return true if there are scheduled events (eg\&. from bundles) waiting to be dispatched by the thread\&. "
.ti -1c
.RI "void \fBlo_server_thread_pp\fP (\fBlo_server_thread\fP st)"
.br
.RI "Pretty-print a \fBlo_server_thread\fP object\&. "
.in -1c
.SH "Detailed Description"
.PP 
The liblo headerfile declaring thread-related functions\&. 
.PP
Definition in file \fBlo_serverthread\&.h\fP\&.
.SH "Function Documentation"
.PP 
.SS "\fBlo_method\fP lo_server_thread_add_method (\fBlo_server_thread\fP st, const char * path, const char * typespec, \fBlo_method_handler\fP h, const void * user_data)"

.PP
Add an OSC method to the specifed server thread\&. 
.PP
\fBParameters\fP
.RS 4
\fIst\fP The server thread the method is to be added to\&. 
.br
\fIpath\fP The OSC path to register the method to\&. If NULL is passed the method will match all paths\&. 
.br
\fItypespec\fP The typespec the method accepts\&. Incoming messages with similar typespecs (e\&.g\&. ones with numerical types in the same position) will be coerced to the typespec given here\&. 
.br
\fIh\fP The method handler callback function that will be called it a matching message is received 
.br
\fIuser_data\fP A value that will be passed to the callback function, h, when its invoked matching from this method\&. 
.RE
.PP

.SS "int lo_server_thread_del_lo_method (\fBlo_server_thread\fP st, \fBlo_method\fP m)"

.PP
Delete an OSC method from the specified server thread\&. 
.PP
\fBParameters\fP
.RS 4
\fIst\fP The server thread the method is to be removed from\&. 
.br
\fIm\fP The \fBlo_method\fP identifier returned from lo_server_add_method for the method to delete from the server\&. 
.RE
.PP
\fBReturns\fP
.RS 4
Non-zero if it was not found in the list of methods for the server\&. 
.RE
.PP

.SS "void lo_server_thread_del_method (\fBlo_server_thread\fP st, const char * path, const char * typespec)"

.PP
Delete an OSC method from the specifed server thread\&. 
.PP
\fBParameters\fP
.RS 4
\fIst\fP The server thread the method is to be removed from\&. 
.br
\fIpath\fP The OSC path of the method to delete\&. If NULL is passed the method will match the generic handler\&. 
.br
\fItypespec\fP The typespec the method accepts\&. 
.RE
.PP

.SS "int lo_server_thread_events_pending (\fBlo_server_thread\fP st)"

.PP
Return true if there are scheduled events (eg\&. from bundles) waiting to be dispatched by the thread\&. 
.SS "void lo_server_thread_free (\fBlo_server_thread\fP st)"

.PP
Free memory taken by a server thread\&. Frees the memory, and, if currently running will stop the associated thread\&. 
.SS "int lo_server_thread_get_port (\fBlo_server_thread\fP st)"

.PP
Return the port number that the server thread has bound to\&. 
.SS "\fBlo_server\fP lo_server_thread_get_server (\fBlo_server_thread\fP st)"

.PP
Return the \fBlo_server\fP for a \fBlo_server_thread\fP\&. This function is useful for passing a thread's \fBlo_server\fP to \fBlo_send_from()\fP\&. 
.SS "char * lo_server_thread_get_url (\fBlo_server_thread\fP st)"

.PP
Return a URL describing the address of the server thread\&. Return value must be free()'d to reclaim memory\&. 
.SS "\fBlo_server_thread\fP lo_server_thread_new (const char * port, \fBlo_err_handler\fP err_h)"

.PP
Create a new server thread to handle incoming OSC messages\&. Server threads take care of the message reception and dispatch by transparently creating a system thread to handle incoming messages\&. Use this if you do not want to handle the threading yourself\&.

.PP
\fBParameters\fP
.RS 4
\fIport\fP If NULL is passed then an unused port will be chosen by the system, its number may be retrieved with \fBlo_server_thread_get_port()\fP so it can be passed to clients\&. Otherwise a decimal port number, service name or UNIX domain socket path may be passed\&. 
.br
\fIerr_h\fP A function that will be called in the event of an error being raised\&. The function prototype is defined in \fBlo_types\&.h\fP 
.RE
.PP

.SS "\fBlo_server_thread\fP lo_server_thread_new_from_config (\fBlo_server_config\fP * config)"

.PP
Create a new server thread, using a configuration struct\&. 
.PP
\fBParameters\fP
.RS 4
\fIconfig\fP A pre-initialized config struct\&. A pointer to it will not be kept\&. 
.RE
.PP
\fBReturns\fP
.RS 4
A new \fBlo_server_thread\fP instance\&. 
.RE
.PP

.SS "\fBlo_server_thread\fP lo_server_thread_new_from_url (const char * url, \fBlo_err_handler\fP err_h)"

.PP
Create a new server thread, taking port and the optional multicast group IP from an URL string\&. 
.PP
\fBParameters\fP
.RS 4
\fIurl\fP The URL to specify the server parameters\&. 
.br
\fIerr_h\fP 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 want error handling\&. 
.RE
.PP
\fBReturns\fP
.RS 4
A new \fBlo_server_thread\fP instance\&. 
.RE
.PP

.SS "\fBlo_server_thread\fP lo_server_thread_new_multicast (const char * group, const char * port, \fBlo_err_handler\fP err_h)"

.PP
Create a new server thread to handle incoming OSC messages, and join a UDP multicast group\&. Server threads take care of the message reception and dispatch by transparently creating a system thread to handle incoming messages\&. Use this if you do not want to handle the threading yourself\&.

.PP
\fBParameters\fP
.RS 4
\fIgroup\fP 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 
.br
\fIport\fP If NULL is passed then an unused port will be chosen by the system, its number may be retrieved with \fBlo_server_thread_get_port()\fP so it can be passed to clients\&. Otherwise a decimal port number, service name or UNIX domain socket path may be passed\&. 
.br
\fIerr_h\fP A function that will be called in the event of an error being raised\&. The function prototype is defined in \fBlo_types\&.h\fP 
.RE
.PP

.SS "\fBlo_server_thread\fP lo_server_thread_new_multicast_iface (const char * group, const char * port, const char * iface, const char * ip, \fBlo_err_handler\fP err_h)"

.PP
Create a new server thread instance, and join a UDP multicast group, optionally specifying which network interface to use\&. Note that usually only one of iface or ip are specified\&. 
.PP
\fBParameters\fP
.RS 4
\fIgroup\fP 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 
.br
\fIport\fP If using UDP then NULL may be passed to find an unused port\&. Otherwise a decimal port number or service name or may be passed\&. If using UNIX domain sockets then a socket path should be passed here\&. 
.br
\fIiface\fP A string specifying the name of a network interface to use, or zero if not specified\&. 
.br
\fIip\fP A string specifying the IP address of a network interface to use, or zero if not specified\&. 
.br
\fIerr_h\fP 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 want error handling\&. 
.RE
.PP

.SS "\fBlo_server_thread\fP lo_server_thread_new_with_proto (const char * port, int proto, \fBlo_err_handler\fP err_h)"

.PP
Create a new server thread to handle incoming OSC messages, specifying protocol\&. Server threads take care of the message reception and dispatch by transparently creating a system thread to handle incoming messages\&. Use this if you do not want to handle the threading yourself\&.

.PP
\fBParameters\fP
.RS 4
\fIport\fP If NULL is passed then an unused port will be chosen by the system, its number may be retrieved with \fBlo_server_thread_get_port()\fP so it can be passed to clients\&. Otherwise a decimal port number, service name or UNIX domain socket path may be passed\&. 
.br
\fIproto\fP The protocol to use, should be one of LO_UDP, LO_TCP or LO_UNIX\&. 
.br
\fIerr_h\fP A function that will be called in the event of an error being raised\&. The function prototype is defined in \fBlo_types\&.h\fP 
.RE
.PP

.SS "void lo_server_thread_pp (\fBlo_server_thread\fP st)"

.PP
Pretty-print a \fBlo_server_thread\fP object\&. 
.SS "void lo_server_thread_set_callbacks (\fBlo_server_thread\fP st, \fBlo_server_thread_init_callback\fP init, \fBlo_server_thread_cleanup_callback\fP cleanup, void * user_data)"

.PP
Set an init and/or a cleanup function to the specifed server thread\&. To have any effect, it must be called before the server thread is started\&.

.PP
\fBParameters\fP
.RS 4
\fIst\fP The server thread to which the method is to be added\&. 
.br
\fIinit\fP The init function to be called just after thread start\&. May be NULL\&. 
.br
\fIcleanup\fP The cleanup function to be called just before thread exit\&. May be NULL\&. 
.br
\fIuser_data\fP A value that will be passed to the callback functions\&. 
.RE
.PP

.SS "int lo_server_thread_start (\fBlo_server_thread\fP st)"

.PP
Start the server thread\&. 
.PP
\fBParameters\fP
.RS 4
\fIst\fP the server thread to start\&. 
.RE
.PP
\fBReturns\fP
.RS 4
Less than 0 on failure, 0 on success\&. 
.RE
.PP

.SS "int lo_server_thread_stop (\fBlo_server_thread\fP st)"

.PP
Stop the server thread\&. 
.PP
\fBParameters\fP
.RS 4
\fIst\fP the server thread to start\&. 
.RE
.PP
\fBReturns\fP
.RS 4
Less than 0 on failure, 0 on success\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for liblo from the source code\&.