/usr/include/lo/lo_lowlevel.h is in liblo-dev 0.28-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 | /*
* Copyright (C) 2014 Steve Harris et al. (see AUTHORS)
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation; either version 2.1
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* $Id$
*/
#ifndef LO_LOWLEVEL_H
#define LO_LOWLEVEL_H
#include "lo/lo_osc_types.h"
/**
* \file lo_lowlevel.h The liblo headerfile defining the low-level API
* functions.
*/
#ifdef __cplusplus
extern "C" {
#endif
#include <stdarg.h>
#include <sys/types.h>
#ifdef _MSC_VER
#define ssize_t SSIZE_T
#define uint32_t unsigned __int32
#else
#include <stdint.h>
#endif
#include "lo/lo_types.h"
#include "lo/lo_errors.h"
/**
* \defgroup liblolowlevel Low-level OSC API
*
* Use these functions if you require more precise control over OSC message
* contruction or handling that what is provided in the high-level functions
* described in liblo.
* @{
*/
/**
* \brief Type used to represent numerical values in conversions between OSC
* types.
*/
typedef long double lo_hires;
/**
* \brief Send a lo_message object to target targ
*
* 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
* \ref lo_message_add_int32 "lo_message_add*()" functions.
*/
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
*
* 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
* \ref lo_message_add_int32 "lo_message_add*()" functions.
*
* \param targ The address to send the message to
* \param serv The server socket to send the message from
* (can be NULL to use new socket)
* \param path The path to send the message to
* \param msg The bundle itself
*/
int lo_send_message_from(lo_address targ, lo_server serv,
const char *path, lo_message msg);
/**
* \brief Send a lo_bundle object to address targ
*
* Bundles are constructed with the
* lo_bundle_new() and lo_bundle_add_message() functions.
*/
int lo_send_bundle(lo_address targ, lo_bundle b);
/**
* \brief Send a lo_bundle object to address targ from address of serv
*
* Bundles are constructed with the
* lo_bundle_new() and lo_bundle_add_message() functions.
*
* \param targ The address to send the bundle to
* \param serv The server socket to send the bundle from
* (can be NULL to use new socket)
* \param b The bundle itself
*/
int lo_send_bundle_from(lo_address targ, lo_server serv, lo_bundle b);
/**
* \brief Create a new lo_message object
*/
lo_message lo_message_new();
/**
* \brief Add one to a message's reference count.
*
* Messages are reference counted. If a message is multiply referenced,
* the message's counter should be incremented. It is automatically
* decremented by lo_message_free lo_message_free_recursive, with
* lo_message_free_recursive being the preferable method.
*/
void lo_message_incref(lo_message m);
/**
* \brief Create a new lo_message object by cloning an already existing one
*/
lo_message lo_message_clone(lo_message m);
/**
* \brief Free memory allocated by lo_message_new() and any subsequent
* \ref lo_message_add_int32 lo_message_add*() calls.
*/
void lo_message_free(lo_message m);
/**
* \brief Append a number of arguments to a message.
*
* The data will be added in OSC byteorder (bigendian).
*
* \param m The message to be extended.
* \param types The types of the data items in the message, types are defined in
* lo_types_common.h
* \param ... The data values to be transmitted. The types of the arguments
* passed here must agree with the types specified in the type parameter.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add(lo_message m, const char *types, ...);
/** \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,
const char *types, ...);
/**
* \brief Append a varargs list to a message.
*
* The data will be added in OSC byteorder (bigendian).
* IMPORTANT: args list must be terminated with LO_ARGS_END, or this call will
* fail. This is used to do simple error checking on the sizes of parameters
* passed.
*
* \param m The message to be extended.
* \param types The types of the data items in the message, types are defined in
* lo_types_common.h
* \param ap The va_list created by a C function declared with an
* ellipsis (...) argument, and pre-initialised with
* "va_start(ap)". The types of the arguments passed here must agree
* with the types specified in the type parameter.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add_varargs(lo_message m, const char *types, va_list ap);
/** \internal \brief the real message_add_varargs function (don't call directly) */
int lo_message_add_varargs_internal(lo_message m, const char *types, va_list ap,
const char *file, const int line);
/**
* \brief Append a data item and typechar of the specified type to a message.
*
* The data will be added in OSC byteorder (bigendian).
*
* \param m The message to be extended.
* \param a The data item.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add_int32(lo_message m, int32_t a);
/**
* \brief Append a data item and typechar of the specified type to a message.
* See lo_message_add_int32() for details.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add_float(lo_message m, float a);
/**
* \brief Append a data item and typechar of the specified type to a message.
* See lo_message_add_int32() for details.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add_string(lo_message m, const char *a);
/**
* \brief Append a data item and typechar of the specified type to a message.
* See lo_message_add_int32() for details.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add_blob(lo_message m, lo_blob a);
/**
* \brief Append a data item and typechar of the specified type to a message.
* See lo_message_add_int32() for details.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add_int64(lo_message m, int64_t a);
/**
* \brief Append a data item and typechar of the specified type to a message.
* See lo_message_add_int32() for details.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add_timetag(lo_message m, lo_timetag a);
/**
* \brief Append a data item and typechar of the specified type to a message.
* See lo_message_add_int32() for details.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add_double(lo_message m, double a);
/**
* \brief Append a data item and typechar of the specified type to a message.
* See lo_message_add_int32() for details.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add_symbol(lo_message m, const char *a);
/**
* \brief Append a data item and typechar of the specified type to a message.
* See lo_message_add_int32() for details.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add_char(lo_message m, char a);
/**
* \brief Append a data item and typechar of the specified type to a message.
* See lo_message_add_int32() for details.
*
* \return Less than 0 on failure, 0 on success.
*/
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 message.
* See lo_message_add_int32() for details.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add_true(lo_message m);
/**
* \brief Append a data item and typechar of the specified type to a message.
* See lo_message_add_int32() for details.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add_false(lo_message m);
/**
* \brief Append a data item and typechar of the specified type to a message.
* See lo_message_add_int32() for details.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add_nil(lo_message m);
/**
* \brief Append a data item and typechar of the specified type to a message.
* See lo_message_add_int32() for details.
*
* \return Less than 0 on failure, 0 on success.
*/
int lo_message_add_infinitum(lo_message m);
/**
* \brief Returns the source (lo_address) of an incoming message.
*
* Returns NULL if the message is outgoing. Do not free the returned address.
*/
lo_address lo_message_get_source(lo_message m);
/**
* \brief Returns the timestamp (lo_timetag *) of a bundled incoming message.
*
* 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.
*
* The result is valid until further data is added with lo_message_add*().
*/
char *lo_message_get_types(lo_message m);
/**
* \brief Return the message argument count.
*
* The result is valid until further data is added with lo_message_add*().
*/
int lo_message_get_argc(lo_message m);
/**
* \brief Return the message arguments. Do not free the returned data.
*
* The result is valid until further data is added with lo_message_add*().
*/
lo_arg **lo_message_get_argv(lo_message m);
/**
* \brief Return the length of a message in bytes.
*
* \param m The message to be sized
* \param path The path the message will be sent to
*/
size_t lo_message_length(lo_message m, const char *path);
/**
* \brief Serialise the lo_message object to an area of memory and return a
* pointer to the serialised form. Opposite of lo_message_deserialise().
*
* \param m The message to be serialised
* \param path The path the message will be sent to
* \param to The address to serialise to, memory will be allocated if to is
* NULL.
* \param size If this pointer is non-NULL the size of the memory area
* will be written here
*
* The returned form is suitable to be sent over a low level OSC transport,
* having the correct endianess and bit-packed structure.
*/
void *lo_message_serialise(lo_message m, const char *path, void *to,
size_t *size);
/**
* \brief Deserialise a raw OSC message and return a new lo_message object.
* Opposite of lo_message_serialise().
*
* \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
* \param result If this pointer is non-NULL, the result or error code will
* be written here.
*
* Returns a new lo_message, or NULL if deserialisation fails.
* Use lo_message_free() to free the resulting object.
*/
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
*
* Returned value must not be modified or free'd. Value will be a dotted quad,
* colon'd IPV6 address, or resolvable name.
*/
const char *lo_address_get_hostname(lo_address a);
/**
* \brief Return the port/service name of a lo_address object
*
* Returned value must not be modified or free'd. Value will be a service name
* or ASCII representation of the port number.
*/
const char *lo_address_get_port(lo_address a);
/**
* \brief Return the protocol of a lo_address object
*
* Returned value will be one of LO_UDP, LO_TCP or LO_UNIX.
*/
int lo_address_get_protocol(lo_address a);
/**
* \brief Return a URL representing an OSC address
*
* Returned value must be free'd.
*/
char *lo_address_get_url(lo_address a);
/**
* \brief 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.
*
* \param t An OSC address.
* \param ttl An integer specifying the scope of a multicast UDP message.
*/
void lo_address_set_ttl(lo_address t, int ttl);
/**
* \brief Get the Time-to-Live value for a given target address.
*
* \param t An OSC address.
* \return An integer specifying the scope of a multicast UDP message.
*/
int lo_address_get_ttl(lo_address t);
/**
* \brief Set the network interface to use for a given target address.
*
* The caller should specify either the iface or ip variable. The IP,
* if specified, should match the same network family as the OSC
* address. (That is, should correctly correspond to IPv4 or IPv6.)
* Typically the assigned network interface will only be used in the
* case of sending multicast messages. It is recommended to use the
* if_nameindex POSIX function to get a list of network interface
* names.
*
* \param t An OSC address.
* \param iface The name of a network interface on the local system.
* \param ip The IP address of a network interface on the local system.
* \return 0 if the interface was successfully identified, or non-zero
* otherwise.
*/
int lo_address_set_iface(lo_address t, const char *iface, const char *ip);
/**
* \brief Get the name of the network interface assigned to an OSC address.
*
* \param t An OSC address.
* \return A string pointer or 0 if no interface has been assigned.
* Caller should not modify the provided string. It is a
* legal pointer until the next call to lo_address_set_iface
* or lo_address_free.
*/
const char* lo_address_get_iface(lo_address t);
/**
* \brief Set the TCP_NODELAY flag on outgoing TCP connections.
* \param t The address to set this flag for.
* \param enable Non-zero to set the flag, zero to unset it.
* \return the previous value of this flag.
*/
int lo_address_set_tcp_nodelay(lo_address t, int enable);
/**
* \brief Set outgoing stream connections (e.g., TCP) to be
* transmitted using the SLIP packetizing protocol.
* \param t The address to set this flag for.
* \param enable Non-zero to set the flag, zero to unset it.
* \return the previous value of this flag.
*/
int lo_address_set_stream_slip(lo_address t, int enable);
/**
* \brief Create a new bundle object.
*
* OSC Bundles encapsulate one or more OSC messages and may include a timestamp
* indicating when the bundle should be dispatched.
*
* \param tt The timestamp when the bundle should be handled by the receiver.
* Pass LO_TT_IMMEDIATE if you want the receiving server to dispatch
* the bundle as soon as it receives it.
*/
lo_bundle lo_bundle_new(lo_timetag tt);
/**
* \brief Add one to a bundle's reference count.
*
* Bundles are reference counted. If a bundle is multiply referenced,
* the bundle's counter should be incremented. It is automatically
* decremented by lo_bundle_free lo_bundle_free_recursive, with
* lo_bundle_free_recursive being the preferable method.
*/
void lo_bundle_incref(lo_bundle b);
/**
* \brief Adds an OSC message to an existing bundle.
*
* The message passed is appended to the list of messages in the bundle to be
* dispatched to 'path'.
*
* \return 0 if successful, less than 0 otherwise.
*/
int lo_bundle_add_message(lo_bundle b, const char *path, lo_message m);
/**
* \brief Adds an OSC bundle to an existing bundle.
*
* The child bundle passed is appended to the list of child bundles|messages in the parent bundle to be
* dispatched.
*
* \return 0 if successful, less than 0 otherwise.
*/
int lo_bundle_add_bundle(lo_bundle b, lo_bundle n);
/**
* \brief Return the length of a bundle in bytes.
*
* Includes the marker and typetag length.
*
* \param b The bundle to be sized
*/
size_t lo_bundle_length(lo_bundle b);
/**
* \brief Return the number of top-level elements in a bundle.
*
* \param b The bundle to be counted.
*/
unsigned int lo_bundle_count(lo_bundle b);
/**
* \brief Gets the element type contained within a bundle.
*
* Returns a lo_element_type at a given index within a bundle.
* \return The requested lo_element_type if successful, otherwise 0.
*/
lo_element_type lo_bundle_get_type(lo_bundle b, int index);
/**
* \brief Gets a nested bundle contained within a bundle.
*
* Returns a lo_bundle at a given index within a bundle.
*
* \return The requested lo_bundle if successful, otherwise 0.
*/
lo_bundle lo_bundle_get_bundle(lo_bundle b, int index);
/**
* \brief Gets a message contained within a bundle.
*
* Returns a lo_message at a given index within a bundle, and
* optionally the path associated with that message.
*
* \return The requested lo_message if successful, otherwise 0.
*/
lo_message lo_bundle_get_message(lo_bundle b, int index,
const char **path);
/**
* \brief Get the timestamp associated with a bundle.
*
* \param b The bundle for which the timestamp should be returned.
*
* \return The timestamp of the bundle as a lo_timetag.
*/
lo_timetag lo_bundle_get_timestamp(lo_bundle b);
/**
* \brief Serialise the bundle object to an area of memory and return a
* pointer to the serialised form.
*
* \param b The bundle to be serialised
* \param to The address to serialise to, memory will be allocated if to is
* NULL.
* \param size If this pointer is non-NULL the size of the memory area
* will be written here
*
* The returned form is suitable to be sent over a low level OSC transport,
* having the correct endianess and bit-packed structure.
*/
void *lo_bundle_serialise(lo_bundle b, void *to, size_t *size);
/**
* \brief Frees the memory taken by a bundle object.
*
* \param b The bundle to be freed.
*/
void lo_bundle_free(lo_bundle b);
/**
* \brief Frees the memory taken by a bundle object and its messages and nested bundles recursively.
*
* \param b The bundle, which may contain messages and nested bundles, to be freed.
*/
void lo_bundle_free_recursive(lo_bundle b);
/**
* \brief Obsolete, use lo_bundle_free_recursive instead.
*
* \param b The bundle, which may contain messages and nested bundles, to be freed.
*/
void lo_bundle_free_messages(lo_bundle b);
/**
* \brief Return true if the type specified has a numerical value, such as
* LO_INT32, LO_FLOAT etc.
*
* \param a The type to be tested.
*/
int lo_is_numerical_type(lo_type a);
/**
* \brief Return true if the type specified has a textual value, such as
* LO_STRING or LO_SYMBOL.
*
* \param a The type to be tested.
*/
int lo_is_string_type(lo_type a);
/**
* \brief Attempt to convert one OSC type to another.
*
* 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 converted
* to the other type. This is done automatically if a received message matches
* the path, but not the exact types, and is coercible (ie. all numerical
* types in numerical positions).
*
* On failure no translation occurs and false is returned.
*
* \param type_to The type of the destination variable.
* \param to A pointer to the destination variable.
* \param type_from The type of 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);
/**
* \brief Return the numerical value of the given argument with the
* maximum native system precision.
*/
lo_hires lo_hires_val(lo_type type, lo_arg *p);
/**
* \brief Create a new server instance.
*
* Using lo_server_recv(), lo_servers block until they receive OSC
* messages. If you want non-blocking behaviour see
* 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
* 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
* name or UNIX domain socket path may be passed.
* \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 want
* error handling.
*/
lo_server lo_server_new(const char *port, lo_err_handler err_h);
/**
* \brief Create a new server instance, specifying protocol.
*
* Using lo_server_recv(), lo_servers block until they receive OSC
* messages. If you want non-blocking behaviour see
* 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.
* Otherwise a decimal port number orservice name or may be passed.
* 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 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 want
* error handling.
*/
lo_server lo_server_new_with_proto(const char *port, int proto,
lo_err_handler err_h);
/**
* \brief Create a new server instance, and join a UDP multicast group.
*
* \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
* \param port 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.
* \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 want
* error handling.
*/
lo_server lo_server_new_multicast(const char *group, const char *port,
lo_err_handler err_h);
/**
* \brief Create a new server 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.
*
* \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
* \param port 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.
* \param iface A string specifying the name of a network interface to
* use, or zero if not specified.
* \param ip A string specifying the IP address of a network interface
* to use, or zero if not specified.
* \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 want
* error handling.
*/
lo_server lo_server_new_multicast_iface(const char *group, const char *port,
const char *iface, const char *ip,
lo_err_handler err_h);
/**
* \brief Create a new server instance, taking port and the optional
* multicast group IP from an URL string.
*
* \param url The URL to specify the server parameters.
* \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 want
* error handling.
* \return A new lo_server instance.
*/
lo_server lo_server_new_from_url(const char *url,
lo_err_handler err_h);
/**
* \brief Enables or disables type coercion during message dispatch.
* \param server The server to toggle this option for.
* \param enable Non-zero to enable, or zero to disable type coercion.
* \return The previous value of this option.
*/
int lo_server_enable_coercion(lo_server server, int enable);
/**
* \brief Free up memory used by the lo_server object
*/
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
*
* \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 the number of bytes in the received message or 0 if
* there is no message. The message will be dispatched to a matching method
* if one is found.
*/
int lo_server_recv_noblock(lo_server s, int timeout);
/**
* \brief Block, waiting for an OSC message to be received
*
* The return value is the number of bytes in the received message. The message
* will be dispatched to a matching method if one is found.
*/
int lo_server_recv(lo_server s);
/**
* \brief Add an OSC method to the specifed server.
*
* \param s The server the method is to be added to.
* \param path The OSC path to register the method to. If NULL is passed the
* method will match all paths.
* \param typespec 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.
* \param h The method handler callback function that will be called if a
* matching message is received
* \param user_data A value that will be passed to the callback function, h,
* when its invoked matching from this method.
*/
lo_method lo_server_add_method(lo_server s, const char *path,
const char *typespec, lo_method_handler h,
void *user_data);
/**
* \brief Delete an OSC method from the specifed server.
*
* \param s The server the method is to be removed from.
* \param path The OSC path of the method to delete. If NULL is passed the
* method will match the generic handler.
* \param typespec The typespec the method accepts.
*/
void lo_server_del_method(lo_server s, const char *path,
const char *typespec);
/**
* \brief Add bundle notification handlers to the specified server.
*
* \param s The server the method is to be added to.
* \param sh The callback function that will be called before the messages
* of a bundle are dispatched
* \param eh The callback function that will be called after the messages
* of a bundle are dispatched
* \param user_data A value that will be passed to the user_data parameter
* of both callback functions.
*/
int lo_server_add_bundle_handlers(lo_server s,
lo_bundle_start_handler sh,
lo_bundle_end_handler eh,
void *user_data);
/**
* \brief Return the file descriptor of the server socket.
*
* If the server protocol supports exposing the server's underlying
* receive mechanism for monitoring with select() or poll(), this function
* returns the file descriptor needed, otherwise, it returns -1.
*
* WARNING: when using this function beware that not all OSC packets that are
* received are dispatched immediately. lo_server_events_pending() and
* 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.
*/
int lo_server_get_socket_fd(lo_server s);
/**
* \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
* address the server.
*/
int lo_server_get_port(lo_server s);
/**
* \brief Return the protocol that the server is using.
*
* Returned value will be one of LO_UDP, LO_TCP or LO_UNIX.
*/
int lo_server_get_protocol(lo_server s);
/**
* \brief Return an OSC URL that can be used to contact the server.
*
* The return value should be free()'d when it is no longer needed.
*/
char *lo_server_get_url(lo_server s);
/**
* \brief Toggle event queue.
* If queueing is enabled, timetagged messages that are sent in
* advance of the current time will be put on an internal queue, and
* they will be dispatched at the indicated time. By default,
* queueing is enabled. Use this function to disable it, if it is
* desired to have a server process messages immediately. In that
* case, use lo_message_get_timestamp() to get the message timestamp
* from within a method handler.
* \param s A liblo server
* \param queue_enabled Zero to disable queue, non-zero to enable.
* \param dispatch_remaining If non-zero, previously queued messages
* will be immediately dispatched when queue
* is disabled.
* \return The previous state of queue behaviour. Zero if queueing
* was previously disabled, non-zero otherwise.
*/
int lo_server_enable_queue(lo_server s, int queue_enabled,
int dispatch_remaining);
/**
* \brief Return true if there are scheduled events (eg. from bundles)
* waiting to be dispatched by the server
*/
int lo_server_events_pending(lo_server s);
/**
* \brief Return the time in seconds until the next scheduled event.
*
* If the delay is greater than 100 seconds then it will return 100.0.
*/
double lo_server_next_event_delay(lo_server s);
/**
* \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
* prot part is missing, UDP is assumed.
*
* The return value should be free()'d when it is no longer needed.
*/
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.
*
* The return value should be free()'d when it is no longer needed.
*/
char *lo_url_get_hostname(const char *url);
/**
* \brief Return the port portion of an OSC URL.
*
* The return value should be free()'d when it is no longer needed.
*/
char *lo_url_get_port(const char *url);
/**
* \brief Return the path portion of an OSC URL.
*
* The return value should be free()'d when it is no longer needed.
*/
char *lo_url_get_path(const char *url);
/* utility functions */
/**
* \brief A function to calculate the amount of OSC message space required by a
* C char *.
*
* Returns the storage size in bytes, which will always be a multiple of four.
*/
int lo_strsize(const char *s);
/**
* \brief A function to calculate the amount of OSC message space required by a
* lo_blob object.
*
* Returns the storage size in bytes, which will always be a multiple of four.
*/
uint32_t lo_blobsize(lo_blob b);
/**
* \brief Test a string against an OSC pattern glob
*
* \param str The string to test
* \param p The pattern to test against
*/
int lo_pattern_match(const char *str, const char *p);
/** \internal \brief the real send function (don't call directly) */
int lo_send_internal(lo_address t, const char *file, const int line,
const char *path, const char *types, ...);
/** \internal \brief the real send_timestamped function (don't call directly) */
int lo_send_timestamped_internal(lo_address t, const char *file, const int line,
lo_timetag ts, const char *path, const char *types, ...);
/** \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,
const int line, const lo_timetag ts,
const char *path, const char *types, ...);
/** \brief Find the time difference between two timetags
*
* Returns a - b in seconds.
*/
double lo_timetag_diff(lo_timetag a, lo_timetag b);
/** \brief Return a timetag for the current time
*
* On exit the timetag pointed to by t is filled with the OSC
* representation of this instant in time.
*/
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 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_network_endian(lo_type type, void *data);
/** @} */
/* prettyprinters */
/**
* \defgroup pp Prettyprinting functions
*
* These functions all print an ASCII representation of their argument to
* stdout. Useful for debugging.
* @{
*/
/** \brief Pretty-print a lo_bundle object. */
void lo_bundle_pp(lo_bundle b);
/** \brief Pretty-print a lo_message object. */
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);
/** \brief Pretty-print a lo_server object. */
void lo_server_pp(lo_server s);
/** \brief Pretty-print a lo_method object. */
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);
/** @} */
#ifdef __cplusplus
}
#endif
#endif
|