CSL 5.2

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

- File List
- File Members

lo.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2004 Steve Harris
3 *
4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public License
6 * as published by the Free Software Foundation; either version 2.1
7 * of the License, or (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU Lesser General Public License for more details.
13 *
14 * $Id$
15 */
16
17 #ifndef LO_H
18 #define LO_H
19
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23
24 /**
25 * \file lo.h The liblo main headerfile and high-level API functions.
26 */
27
28 #include "lo/lo_endian.h"
29 #include "lo/lo_types.h"
30 #include "lo/lo_osc_types.h"
31 #include "lo/lo_errors.h"
32 #include "lo/lo_lowlevel.h"
33
34 /**
35 * \defgroup liblo High-level OSC API
36 *
37 * Defines the high-level API functions necessary to implement OSC support.
38 * Should be adequate for most applications, but if you require lower level
39 * control you can use the functions defined in lo_lowlevel.h
40 * @{
41 */
42
43 /**
44 * \brief Declare an OSC destination, given IP address and port number.
45 * Same as lo_address_new_with_proto(), but using UDP.
46 *
47 * \param host An IP address or number, or NULL for the local machine.
48 * \param port a decimal port number or service name.
49 *
50 * The lo_address object may be used as the target of OSC messages.
51 *
52 * Note: if you wish to receive replies from the target of this address, you
53 * must first create a lo_server_thread or lo_server object which will receive
54 * the replies. The last lo_server(_thread) object creted will be the receiver.
55 */
56 lo_address lo_address_new(const char *host, const char *port);
57
58 /**
59 * \brief Declare an OSC destination, given IP address and port number,
60 * specifying protocol.
61 *
62 * \param proto The protocol to use, must be one of LO_UDP, LO_TCP or LO_UNIX.
63 * \param host An IP address or number, or NULL for the local machine.
64 * \param port a decimal port number or service name.
65 *
66 * The lo_address object may be used as the target of OSC messages.
67 *
68 * Note: if you wish to receive replies from the target of this address, you
69 * must first create a lo_server_thread or lo_server object which will receive
70 * the replies. The last lo_server(_thread) object creted will be the receiver.
71 */
72 lo_address lo_address_new_with_proto(int proto, const char *host, const char *port);
73
74 /**
75 * \brief Create a lo_address object from an OSC URL.
76 *
77 * example: \c "osc.udp://localhost:4444/my/path/"
78 */
79 lo_address lo_address_new_from_url(const char *url);
80
81 /**
82 * \brief Free the memory used by the lo_address object
83 */
84 void lo_address_free(lo_address t);
85
86 /**
87 * \brief Set the Time-to-Live value for a given target address.
88 *
89 * This is required for sending multicast UDP messages. A value of 1
90 * (the usual case) keeps the message within the subnet, while 255
91 * means a global, unrestricted scope.
92 *
93 * \param t An OSC address.
94 * \param ttl An integer specifying the scope of a multicast UDP message.
95 */
96 void lo_address_set_ttl(lo_address t, int ttl);
97
98 /**
99 * \brief Get the Time-to-Live value for a given target address.
100 *
101 * \param t An OSC address.
102 * \return An integer specifying the scope of a multicast UDP message.
103 */
104 int lo_address_get_ttl(lo_address t);
105
106 /**
107 * \brief Send a OSC formatted message to the address specified.
108 *
109 * \param targ The target OSC address
110 * \param path The OSC path the message will be delivered to
111 * \param type The types of the data items in the message, types are defined in
112 * lo_osc_types.h
113 * \param ... The data values to be transmitted. The types of the arguments
114 * passed here must agree with the types specified in the type parameter.
115 *
116 * example:
117 * \code
118 * lo_send(t, "/foo/bar", "ff", 0.1f, 23.0f);
119 * \endcode
120 *
121 * \return -1 on failure.
122 */
123 int lo_send(lo_address targ, const char *path, const char *type, ...);
124
125 /**
126 * \brief Send a OSC formatted message to the address specified,
127 * from the same socket as the specificied server.
128 *
129 * \param targ The target OSC address
130 * \param from The server to send message from (can be NULL to use new socket)
131 * \param ts The OSC timetag timestamp at which the message will be processed
132 * (can be LO_TT_IMMEDIATE if you don't want to attach a timetag)
133 * \param path The OSC path the message will be delivered to
134 * \param type The types of the data items in the message, types are defined in
135 * lo_osc_types.h
136 * \param ... The data values to be transmitted. The types of the arguments
137 * passed here must agree with the types specified in the type parameter.
138 *
139 * example:
140 * \code
141 * serv = lo_server_new(NULL, err);
142 * lo_server_add_method(serv, "/reply", "ss", reply_handler, NULL);
143 * lo_send_from(t, serv, LO_TT_IMMEDIATE, "/foo/bar", "ff", 0.1f, 23.0f);
144 * \endcode
145 *
146 * \return on success, the number of bytes sent, or -1 on failure.
147 */
148 int lo_send_from(lo_address targ, lo_server from, lo_timetag ts,
149 const char *path, const char *type, ...);
150
151 /**
152 * \brief Send a OSC formatted message to the address specified, scheduled to
153 * be dispatch at some time in the future.
154 *
155 * \param targ The target OSC address
156 * \param ts The OSC timetag timestamp at which the message will be processed
157 * \param path The OSC path the message will be delivered to
158 * \param type The types of the data items in the message, types are defined in
159 * lo_osc_types.h
160 * \param ... The data values to be transmitted. The types of the arguments
161 * passed here must agree with the types specified in the type parameter.
162 *
163 * example:
164 * \code
165 * lo_timetag now;<br>
166 * lo_timetag_now(&now);<br>
167 * lo_send_timestamped(t, now, "/foo/bar", "ff", 0.1f, 23.0f);
168 * \endcode
169 *
170 * \return on success, the number of bytes sent, or -1 on failure.
171 */
172 int lo_send_timestamped(lo_address targ, lo_timetag ts, const char *path,
173 const char *type, ...);
174
175 /**
176 * \brief Return the error number from the last failed lo_send() or
177 * lo_address_new() call
178 */
179 int lo_address_errno(lo_address a);
180
181 /**
182 * \brief Return the error string from the last failed lo_send() or
183 * lo_address_new() call
184 */
185 const char *lo_address_errstr(lo_address a);
186
187 /**
188 * \brief Create a new server thread to handle incoming OSC
189 * messages.
190 *
191 * Server threads take care of the message reception and dispatch by
192 * transparently creating a system thread to handle incoming messages.
193 * Use this if you do not want to handle the threading yourself.
194 *
195 * \param port If NULL is passed then an unused port will be chosen by the
196 * system, its number may be retrieved with lo_server_thread_get_port()
197 * so it can be passed to clients. Otherwise a decimal port number, service
198 * name or UNIX domain socket path may be passed.
199 * \param err_h A function that will be called in the event of an error being
200 * raised. The function prototype is defined in lo_types.h
201 */
202 lo_server_thread lo_server_thread_new(const char *port, lo_err_handler err_h);
203
204 /**
205 * \brief Create a new server thread to handle incoming OSC
206 * messages, and join a UDP multicast group.
207 *
208 * Server threads take care of the message reception and dispatch by
209 * transparently creating a system thread to handle incoming messages.
210 * Use this if you do not want to handle the threading yourself.
211 *
212 * \param group The multicast group to join. See documentation on IP
213 * multicast for the acceptable address range; e.g., http://tldp.org/HOWTO/Multicast-HOWTO-2.html
214 * \param port If NULL is passed then an unused port will be chosen by the
215 * system, its number may be retrieved with lo_server_thread_get_port()
216 * so it can be passed to clients. Otherwise a decimal port number, service
217 * name or UNIX domain socket path may be passed.
218 * \param err_h A function that will be called in the event of an error being
219 * raised. The function prototype is defined in lo_types.h
220 */
221 lo_server_thread lo_server_thread_new_multicast(const char *group, const char *port,
222 lo_err_handler err_h);
223
224 /**
225 * \brief Create a new server thread to handle incoming OSC
226 * messages, specifying protocol.
227 *
228 * Server threads take care of the message reception and dispatch by
229 * transparently creating a system thread to handle incoming messages.
230 * Use this if you do not want to handle the threading yourself.
231 *
232 * \param port If NULL is passed then an unused port will be chosen by the
233 * system, its number may be retrieved with lo_server_thread_get_port()
234 * so it can be passed to clients. Otherwise a decimal port number, service
235 * name or UNIX domain socket path may be passed.
236 * \param proto The protocol to use, should be one of LO_UDP, LO_TCP or LO_UNIX.
237 * \param err_h A function that will be called in the event of an error being
238 * raised. The function prototype is defined in lo_types.h
239 */
240 lo_server_thread lo_server_thread_new_with_proto(const char *port, int proto,
241 lo_err_handler err_h);
242
243 /**
244 * \brief Free memory taken by a server thread
245 *
246 * Frees the memory, and, if currently running will stop the associated thread.
247 */
248 void lo_server_thread_free(lo_server_thread st);
249
250 /**
251 * \brief Add an OSC method to the specifed server thread.
252 *
253 * \param st The server thread the method is to be added to.
254 * \param path The OSC path to register the method to. If NULL is passed the
255 * method will match all paths.
256 * \param typespec The typespec the method accepts. Incoming messages with
257 * similar typespecs (e.g. ones with numerical types in the same position) will
258 * be coerced to the typespec given here.
259 * \param h The method handler callback function that will be called it a
260 * matching message is received
261 * \param user_data A value that will be passed to the callback function, h,
262 * when its invoked matching from this method.
263 */
264 lo_method lo_server_thread_add_method(lo_server_thread st, const char *path,
265 const char *typespec, lo_method_handler h,
266 void *user_data);
267 /**
268 * \brief Delete an OSC method from the specifed server thread.
269 *
270 * \param st The server thread the method is to be removed from.
271 * \param path The OSC path of the method to delete. If NULL is passed the
272 * method will match the generic handler.
273 * \param typespec The typespec the method accepts.
274 */
275 void lo_server_thread_del_method(lo_server_thread st, const char *path,
276 const char *typespec);
277
278 /**
279 * \brief Start the server thread
280 *
281 * \param st the server thread to start.
282 * \return Less than 0 on failure, 0 on success.
283 */
284 int lo_server_thread_start(lo_server_thread st);
285
286 /**
287 * \brief Stop the server thread
288 *
289 * \param st the server thread to start.
290 * \return Less than 0 on failure, 0 on success.
291 */
292 int lo_server_thread_stop(lo_server_thread st);
293
294 /**
295 * \brief Return the port number that the server thread has bound to.
296 */
297 int lo_server_thread_get_port(lo_server_thread st);
298
299 /**
300 * \brief Return a URL describing the address of the server thread.
301 *
302 * Return value must be free()'d to reclaim memory.
303 */
304 char *lo_server_thread_get_url(lo_server_thread st);
305
306 /**
307 * \brief Return the lo_server for a lo_server_thread
308 *
309 * This function is useful for passing a thread's lo_server
310 * to lo_send_from().
311 */
312 lo_server lo_server_thread_get_server(lo_server_thread st);
313
314 /** \brief Return true if there are scheduled events (eg. from bundles) waiting
315 * to be dispatched by the thread */
316 int lo_server_thread_events_pending(lo_server_thread st);
317
318 /**
319 * \brief Create a new OSC blob type.
320 *
321 * \param size The amount of space to allocate in the blob structure.
322 * \param data The data that will be used to initialise the blob, should be
323 * size bytes long.
324 */
325 lo_blob lo_blob_new(int32_t size, const void *data);
326
327 /**
328 * \brief Free the memory taken by a blob
329 */
330 void lo_blob_free(lo_blob b);
331
332 /**
333 * \brief Return the amount of valid data in a lo_blob object.
334 *
335 * If you want to know the storage size, use lo_arg_size().
336 */
337 uint32_t lo_blob_datasize(lo_blob b);
338
339 /**
340 * \brief Return a pointer to the start of the blob data to allow contents to
341 * be changed.
342 */
343 void *lo_blob_dataptr(lo_blob b);
344
345 /** @} */
346
347 #include "lo/lo_macros.h"
348
349 #ifdef __cplusplus
350 }
351 #endif
352
353 #endif