cosc.h File Reference

OSC library for C99 or C++11. More...

#include <stdint.h>

Go to the source code of this file.

Classes
struct	cosc_64bits
	Used when 64-bit types are not available. More...
union	cosc_value
	A value. More...
struct	cosc_message
	A message. More...
struct	cosc_level
	Used to manage the levels of a serial. More...
struct	cosc_serial
	A serial. More...

Macros
#define	COSC_API
	Used to declare linkage for functions.
#define	COSC_TYPE_INT32   int32_t
	Used to typedef cosc_int32.
#define	COSC_TYPE_UINT32   uint32_t
	Used to typedef cosc_uint32.
#define	COSC_TYPE_INT64   int64_t
	Used to typedef cosc_int64.
#define	COSC_TYPE_UINT64   uint64_t
	Used to typedef cosc_uint64.
#define	COSC_TYPE_FLOAT32   float
	Used to typedef cosc_float32.
#define	COSC_TYPE_FLOAT64   double
	Used to typedef cosc_float64.
#define	COSC_INT32MAX   2147483647
	Maximum value of a signed 32-bit integer.
#define	COSC_INT32MIN   ((-2147483647)-1)
	Minimum value of a signed 32-bit integer.
#define	COSC_UINT32MAX   4294967295
	Minimum value of an unsigned 32-bit integer.
#define	COSC_INT64MAX   9223372036854775807LL
	Maximum value of a signed 64-bit integer.
#define	COSC_INT64MIN   ((-9223372036854775807LL)-1)
	Minimum value of a signed 64-bit integer.
#define	COSC_UINT64MAX   18446744073709551615ULL
	Minimum value of an unsigned 32-bit integer.
#define	COSC_64BITS_INIT(hi_, lo_)
	Helper initializer when defining cosc_64bits structs.
#define	COSC_64BITS_SET(bits_, hi_, lo_)
	Helper to set the members of a cosc_64bits struct.
#define	COSC_64BITS_HI(bits_)
	Helper to access the high member of a cosc_64bits struct.
#define	COSC_64BITS_LO(bits_)
	Helper to access the low member of a cosc_64bits struct.
#define	COSC_INT64_INIT_ZERO   0
	Initializer cosc_int64 or cosc_uint64 as zero.
#define	COSC_INT64_SET_ZERO(ptr)
	Set cosc_int64 or cosc_uint64 as zero.
#define	COSC_FLOAT64_INIT_ZERO   0
	Initializer cosc_float64 or cosc_ufloat64 as zero.
#define	COSC_FLOAT64_SET_ZERO(ptr)
	Set cosc_float64 or cosc_ufloat64 as zero.
#define	COSC_SIZE_MAX   2147483644
	The maximum 4 byte aligned size that fits in a signed 32-bit integer.
#define	COSC_PADMUST(sz)
	Get the required zero pad size for strings that require a zero terminator and 4 byte alignment.
#define	COSC_PAD(sz)
	Get the required zero pad size for 4 byte alignment.
#define	COSC_LEVEL_TYPE_BUNDLE   'B'
	The level type is a bundle.
#define	COSC_LEVEL_TYPE_MESSAGE   'M'
	The level type is a message.
#define	COSC_LEVEL_TYPE_BLOB   'b'
	The level type is a blob.
#define	COSC_SERIAL_PSIZE   1
	Tell the serial that the first bundle or message is prefixed with a packet size.
#define	COSC_EOVERRUN   -2
	Buffer overrun.
#define	COSC_ESIZEMAX   -3
	Size exceeds COSC_SIZE_MAX.
#define	COSC_ETYPE   -4
	Invalid type.
#define	COSC_EPSIZE   -5
	Invalid packet size.
#define	COSC_EINVAL   -6
	Invalid argument or operation.
#define	COSC_ELEVELMAX   -7
	Writer or reader reached maximum level.
#define	COSC_ELEVELTYPE   -8
	Invalid operation for the current level type.
#define	COSC_EPSIZEFLAG   -9
	Trying to chain multiple bundles or messages without packet size flag.
#define	COSC_EMSGTYPE   -10
	Trying to write or read a message member of the wrong or invalid type.
#define	COSC_SERIAL_ISWRITER(serial_)
	Macro to check if a serial is a writer.
#define	COSC_SERIAL_ISREADER(serial_)
	Macro to check if a serial is a reader.

Typedefs
typedef COSC_TYPE_UINT32	cosc_uint32
	Unsigned 32-bit integer.
typedef COSC_TYPE_INT32	cosc_int32
	Signed 32-bit integer.
typedef COSC_TYPE_INT64	cosc_int64
	Signed 64-bit integer.
typedef COSC_TYPE_UINT64	cosc_uint64
	Unsigned 64-bit integer.
typedef COSC_TYPE_FLOAT32	cosc_float32
	32-bit floating point.
typedef COSC_TYPE_FLOAT64	cosc_float64
	64-bit floating point.

Functions
COSC_API cosc_int32	cosc_feature_int64 (void)
	Feature test for 64-bit integer support.
COSC_API cosc_int32	cosc_feature_float32 (void)
	Feature test for 32-bit float support.
COSC_API cosc_int32	cosc_feature_float64 (void)
	Feature test for 64-bit float support.
COSC_API cosc_int32	cosc_feature_swap (void)
	Feature test for endian swapping.
COSC_API cosc_int32	cosc_feature_array (void)
	Feature test for array support.
COSC_API cosc_int32	cosc_feature_pattern (void)
	Feature test for pattern support.
COSC_API cosc_int32	cosc_feature_timetag (void)
	Feature test for timetag conversion support.
COSC_API cosc_int32	cosc_feature_fltconv (void)
	Feature test for float conversion support.
COSC_API cosc_int32	cosc_feature_writer (void)
	Feature test for writer support.
COSC_API cosc_int32	cosc_feature_reader (void)
	Feature test for reader support.
COSC_API cosc_int32	cosc_big_endian (void)
	If big endian was detected when building this function returns non-zero, otherwise zero.
COSC_API cosc_int32	cosc_address_char_validate (cosc_int32 c)
	Check if an address character is valid.
COSC_API cosc_int32	cosc_address_validate (const char *address, cosc_int32 address_n, cosc_int32 *invalid)
	Scan address for invalid characters.
COSC_API cosc_int32	cosc_typetag_char_validate (cosc_int32 c)
	Check if an typetag character is valid.
COSC_API cosc_int32	cosc_typetag_validate (const char *typetag, cosc_int32 typetag_n, cosc_int32 *invalid)
	Scan typetag for invalid characters.
COSC_API cosc_int32	cosc_typetag_payload (char *s, cosc_int32 s_n, const char *typetag, cosc_int32 typetag_n, cosc_int32 *array_members)
	Scan typetag for types with payload, ignoring the comma prefix, array syntax and types T, F, N and I.
COSC_API cosc_int32	cosc_pattern_char_validate (cosc_int32 c)
	Check if an pattern character is valid.
COSC_API cosc_int32	cosc_pattern_validate (const char *s, cosc_int32 s_n, cosc_int32 *invalid)
	Scan matching pattern for invalid characters.
COSC_API cosc_int32	cosc_pattern_match (const char *s, cosc_int32 s_n, const char *pattern, cosc_int32 pattern_n)
	Match an address or typetag.
COSC_API cosc_int32	cosc_signature_match (const void *buffer, cosc_int32 size, const char *apattern, cosc_int32 apattern_n, const char *tpattern, cosc_int32 tpattern_n, cosc_int32 prefix)
	Match an address and typetag.
COSC_API cosc_uint32	cosc_timetag_to_time (cosc_uint64 timetag, cosc_uint32 *nanos)
	Convert a timetag to seconds and nanoseconds.
COSC_API cosc_uint64	cosc_time_to_timetag (cosc_uint32 seconds, cosc_uint32 nanos)
	Convert time to a timetag.
COSC_API cosc_float32	cosc_float64_to_float32 (cosc_float64 value)
	Convert a 64-bit float to a 32-bit float.
COSC_API cosc_float64	cosc_float32_to_float64 (cosc_float32 value)
	Convert a 32-bit float to a 64-bit float.
COSC_API cosc_int32	cosc_write_uint32 (void *buffer, cosc_int32 size, cosc_uint32 value)
	Write a 32-bit, big endian unsigned integer.
COSC_API cosc_int32	cosc_read_uint32 (const void *buffer, cosc_int32 size, cosc_uint32 *value)
	Read a 32-bit big endian unsigned integer.
COSC_API cosc_int32	cosc_write_int32 (void *buffer, cosc_int32 size, cosc_int32 value)
	Write a 32-bit big endian signed integer.
COSC_API cosc_int32	cosc_read_int32 (const void *buffer, cosc_int32 size, cosc_int32 *value)
	Read a 32-bit big endian signed integer.
COSC_API cosc_int32	cosc_write_float32 (void *buffer, cosc_int32 size, cosc_float32 value)
	Write a 32-bit big endian floating point.
COSC_API cosc_int32	cosc_read_float32 (const void *buffer, cosc_int32 size, cosc_float32 *value)
	Read a 32-bit big endian floating point.
COSC_API cosc_int32	cosc_write_uint64 (void *buffer, cosc_int32 size, cosc_uint64 value)
	Write a 64-bit, big endian unsigned integer.
COSC_API cosc_int32	cosc_read_uint64 (const void *buffer, cosc_int32 size, cosc_uint64 *value)
	Read a 64-bit big endian unsigned integer.
COSC_API cosc_int32	cosc_write_int64 (void *buffer, cosc_int32 size, cosc_int64 value)
	Write a 64-bit big endian signed integer.
COSC_API cosc_int32	cosc_read_int64 (const void *buffer, cosc_int32 size, cosc_int64 *value)
	Read a 64-bit big endian signed integer.
COSC_API cosc_int32	cosc_write_float64 (void *buffer, cosc_int32 size, cosc_float64 value)
	Write a 64-bit big endian floating point.
COSC_API cosc_int32	cosc_read_float64 (const void *buffer, cosc_int32 size, cosc_float64 *value)
	Read a 64-bit big endian floating point.
COSC_API cosc_int32	cosc_write_string (void *buffer, cosc_int32 size, const char *value, cosc_int32 value_n, cosc_int32 *length)
	Write a string.
COSC_API cosc_int32	cosc_read_string (const void *buffer, cosc_int32 size, char *value, cosc_int32 value_n, cosc_int32 *length)
	Read a string.
COSC_API cosc_int32	cosc_write_blob (void *buffer, cosc_int32 size, const void *value, cosc_int32 value_n)
	Write a blob.
COSC_API cosc_int32	cosc_read_blob (const void *buffer, cosc_int32 size, void *value, cosc_int32 value_n, const void **data, cosc_int32 *data_size)
	Read a blob.
COSC_API cosc_int32	cosc_write_char (void *buffer, cosc_int32 size, cosc_int32 value)
	Write an ASCII character.
COSC_API cosc_int32	cosc_read_char (const void *buffer, cosc_int32 size, cosc_int32 *value)
	Read an ASCII character.
COSC_API cosc_int32	cosc_write_midi (void *buffer, cosc_int32 size, const unsigned char value[4])
	Write a MIDI message.
COSC_API cosc_int32	cosc_read_midi (const void *buffer, cosc_int32 size, unsigned char value[4])
	Read an ASCII character.
COSC_API cosc_int32	cosc_write_bundle (void *buffer, cosc_int32 size, cosc_uint64 timetag, cosc_int32 psize)
	Write an OSC bundle head.
COSC_API cosc_int32	cosc_read_bundle (const void *buffer, cosc_int32 size, cosc_uint64 *timetag, cosc_int32 *psize)
	Read an OSC bundle head.
COSC_API cosc_int32	cosc_write_signature (void *buffer, cosc_int32 size, const char *address, cosc_int32 address_n, const char *typetag, cosc_int32 typetag_n, cosc_int32 psize)
	Write an OSC message signature.
COSC_API cosc_int32	cosc_read_signature (const void *buffer, cosc_int32 size, const char **address, cosc_int32 *address_n, const char **typetag, cosc_int32 *typetag_n, cosc_int32 *psize)
	Read an OSC message signature.
COSC_API cosc_int32	cosc_write_value (void *buffer, cosc_int32 size, char type, const union cosc_value *value)
	Write an OSC value.
COSC_API cosc_int32	cosc_read_value (const void *buffer, cosc_int32 size, char type, union cosc_value *value)
	Read an OSC value.
COSC_API cosc_int32	cosc_write_values (void *buffer, cosc_int32 size, const char *types, cosc_int32 types_n, const union cosc_value *values, cosc_int32 values_n, cosc_int32 *value_count)
	Write OSC values.
COSC_API cosc_int32	cosc_read_values (const void *buffer, cosc_int32 size, const char *types, cosc_int32 types_n, union cosc_value *values, cosc_int32 values_n, cosc_int32 *value_count, cosc_int32 exit_early)
	Read OSC values.
COSC_API cosc_int32	cosc_write_message (void *buffer, cosc_int32 size, const struct cosc_message *message, cosc_int32 psize, cosc_int32 *value_count)
	Write an OSC message.
COSC_API cosc_int32	cosc_read_message (const void *buffer, cosc_int32 size, struct cosc_message *message, cosc_int32 *psize, cosc_int32 *value_count, cosc_int32 exit_early)
	Read an OSC message.
COSC_API cosc_int32	cosc_value_dump (char *s, cosc_int32 n, char type, const union cosc_value *value)
	Dump an OSC value to string.
COSC_API cosc_int32	cosc_message_dump (char *s, cosc_int32 n, const struct cosc_message *message)
	Dump an OSC message to string.
COSC_API cosc_int32	cosc_serial_get_buffer_size (const struct cosc_serial *serial)
	The maximum number of bytes that can be written/read to/from the buffer.
COSC_API cosc_int32	cosc_serial_get_size (const struct cosc_serial *serial)
	Get the number of written or read bytes.
COSC_API cosc_int32	cosc_serial_get_msgtype (const struct cosc_serial *serial)
	Get the current typetag type of a message level.
COSC_API void	cosc_serial_reset (struct cosc_serial *serial)
	Reset serial.
COSC_API void	cosc_writer_setup (struct cosc_serial *serial, void *buffer, cosc_int32 buffer_size, struct cosc_level *levels, cosc_int32 level_max, cosc_uint32 flags)
	Setup a serial for writing.
COSC_API cosc_int32	cosc_writer_start_bundle (struct cosc_serial *serial, cosc_uint64 timetag)
	Start a new bundle level.
COSC_API cosc_int32	cosc_writer_end_bundle (struct cosc_serial *serial)
	End a bundle level.
COSC_API cosc_int32	cosc_writer_start_message (struct cosc_serial *serial, const char *address, cosc_int32 address_n, const char *typetag, cosc_int32 typetag_n)
	Start a new message level.
COSC_API cosc_int32	cosc_writer_end_message (struct cosc_serial *serial)
	End a message level.
COSC_API cosc_int32	cosc_writer_start_blob (struct cosc_serial *serial)
	Start a new blob level.
COSC_API cosc_int32	cosc_writer_end_blob (struct cosc_serial *serial)
	End a blob level.
COSC_API cosc_int32	cosc_writer_uint32 (struct cosc_serial *serial, cosc_uint32 value)
	Write an unsigned 32-bit integer.
COSC_API cosc_int32	cosc_writer_int32 (struct cosc_serial *serial, cosc_int32 value)
	Write a signed 32-bit integer.
COSC_API cosc_int32	cosc_writer_float32 (struct cosc_serial *serial, cosc_float32 value)
	Write a 32-bit float.
COSC_API cosc_int32	cosc_writer_uint64 (struct cosc_serial *serial, cosc_uint64 value)
	Write an unsigned 64-bit integer.
COSC_API cosc_int32	cosc_writer_int64 (struct cosc_serial *serial, cosc_int64 value)
	Write a signed 64-bit integer.
COSC_API cosc_int32	cosc_writer_float64 (struct cosc_serial *serial, cosc_float64 value)
	Write a 64-bit float.
COSC_API cosc_int32	cosc_writer_string (struct cosc_serial *serial, const char *value, cosc_int32 value_n, cosc_int32 *length)
	Write a string.
COSC_API cosc_int32	cosc_writer_blob (struct cosc_serial *serial, const void *value, cosc_int32 value_n)
	Write a blob.
COSC_API cosc_int32	cosc_writer_char (struct cosc_serial *serial, cosc_int32 value)
	Write an ASCII character.
COSC_API cosc_int32	cosc_writer_midi (struct cosc_serial *serial, const unsigned char value[4])
	Write a MIDI message.
COSC_API cosc_int32	cosc_writer_value (struct cosc_serial *serial, cosc_int32 type, const union cosc_value *value)
	Write a value.
COSC_API cosc_int32	cosc_writer_message (struct cosc_serial *serial, const struct cosc_message *message, cosc_int32 *value_count)
	Write an OSC message.
COSC_API cosc_int32	cosc_writer_bytes (struct cosc_serial *serial, const void *value, cosc_int32 value_n)
	Write bytes to a started blob level.
COSC_API cosc_int32	cosc_writer_skip (struct cosc_serial *serial)
	Skip a value, if the value has payload it will be zeroes.
COSC_API cosc_int32	cosc_writer_repeat (struct cosc_serial *serial)
	Repeat typetag from the beginning of an array start, where the array starts with a '['.
COSC_API void	cosc_reader_setup (struct cosc_serial *serial, const void *buffer, cosc_int32 buffer_size, struct cosc_level *levels, cosc_int32 level_max, cosc_uint32 flags)
	Setup a serial for reading.
COSC_API cosc_int32	cosc_reader_peek_bundle (struct cosc_serial *serial, cosc_uint64 *timetag, cosc_int32 *psize)
	Check if the buffer has a bundle at the current read size.
COSC_API cosc_int32	cosc_reader_start_bundle (struct cosc_serial *serial, cosc_uint64 *timetag)
	Start a new bundle level.
COSC_API cosc_int32	cosc_reader_end_bundle (struct cosc_serial *serial)
	End a bundle level.
COSC_API cosc_int32	cosc_reader_start_message (struct cosc_serial *serial, const char **address, cosc_int32 *address_n, const char **typetag, cosc_int32 *typetag_n)
	Start a new message level.
COSC_API cosc_int32	cosc_reader_end_message (struct cosc_serial *serial, cosc_int32 exit_early)
	End a message level.
COSC_API cosc_int32	cosc_reader_start_blob (struct cosc_serial *serial, cosc_int32 *value_size)
	Start a new blob level.
COSC_API cosc_int32	cosc_reader_end_blob (struct cosc_serial *serial)
	End a blob level.
COSC_API cosc_int32	cosc_reader_uint32 (struct cosc_serial *serial, cosc_uint32 *value)
	Write an unsigned 32-bit integer.
COSC_API cosc_int32	cosc_reader_int32 (struct cosc_serial *serial, cosc_int32 *value)
	Write a signed 32-bit integer.
COSC_API cosc_int32	cosc_reader_float32 (struct cosc_serial *serial, cosc_float32 *value)
	Write a 32-bit float.
COSC_API cosc_int32	cosc_reader_uint64 (struct cosc_serial *serial, cosc_uint64 *value)
	Write an unsigned 64-bit integer.
COSC_API cosc_int32	cosc_reader_int64 (struct cosc_serial *serial, cosc_int64 *value)
	Write a signed 64-bit integer.
COSC_API cosc_int32	cosc_reader_float64 (struct cosc_serial *serial, cosc_float64 *value)
	Write a 64-bit float.
COSC_API cosc_int32	cosc_reader_string (struct cosc_serial *serial, char *value, cosc_int32 value_n, cosc_int32 *length)
	Write a string.
COSC_API cosc_int32	cosc_reader_blob (struct cosc_serial *serial, void *value, cosc_int32 value_n, const void **data, cosc_int32 *data_size)
	Write a blob.
COSC_API cosc_int32	cosc_reader_char (struct cosc_serial *serial, cosc_int32 *value)
	Write an ASCII character.
COSC_API cosc_int32	cosc_reader_midi (struct cosc_serial *serial, unsigned char value[4])
	Write a MIDI message.
COSC_API cosc_int32	cosc_reader_value (struct cosc_serial *serial, cosc_int32 type, union cosc_value *value)
	Read a value.
COSC_API cosc_int32	cosc_reader_message (struct cosc_serial *serial, struct cosc_message *message, cosc_int32 *value_count, cosc_int32 exit_early)
	Read an OSC message.
COSC_API cosc_int32	cosc_reader_bytes (struct cosc_serial *serial, void *value, cosc_int32 value_n)
	Read bytes to a started blob level.
COSC_API cosc_int32	cosc_reader_skip (struct cosc_serial *serial)
	Skip a value, if the value has payload it will be zeroes.
COSC_API cosc_int32	cosc_reader_repeat (struct cosc_serial *serial)
	Repeat typetag from the beginning of an array start, not including the starting '[' character.

Detailed Description

OSC library for C99 or C++11.

Copyright

Copyright 2025 Peter Gebauer (MIT license)

Build options

Defined at compile AND include time:

• COSC_NOSTDLIB for no use of the standard library. This will also remove the dump functions.
• COSC_NOPATTERN to remove the pattern matching functions.
• COSC_NOSWAP for no endian swapping.
• COSC_NOARRAY to remove the support for arrays.
• COSC_NOSTDINT to not include stdint.h (or cstdint if C++).
• COSC_NODUMP to remove the dump functions.
• COSC_NOTIMETAG to remove timetag conversion functions.
• COSC_NOFLTCONV to remove float conversion functions.
• COSC_NOWRITER to remove the writer functions.
• COSC_NOREADER to remove the reader functions.
• COSC_NOINT64 to typedef cosc_int64 and cosc_uint64 as cosc_64bits.
• COSC_NOFLOAT32 to typedef cosc_float32 as cosc_uint32.
• COSC_NOFLOAT64 to typedef cosc_float64 as cosc_64bits.

Type overrides (also at compile AND include time):

• COSC_TYPE_UINT32 used to override typedef cosc_uint32.
• COSC_TYPE_INT32 used to override typedef cosc_int32.
• COSC_TYPE_FLOAT32 used to override typedef cosc_float32.
• COSC_TYPE_UINT64 used to override typedef cosc_uint64.
• COSC_TYPE_INT64 used to override typedef cosc_int64.
• COSC_TYPE_FLOAT64 used to override typedef cosc_float64.

NOTE that type overrides will not work for types affected by COSC_NOINT64, COSC_FLOAT32 or COSC_NOFLOAT64 when those are defined.

License

Copyright 2025 Peter Gebauer
 
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files
(the "Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
 
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Macro Definition Documentation

COSC_64BITS_HI

#define COSC_64BITS_HI

(

bits_

)

Value:

((bits_)->w[0])

Helper to access the high member of a cosc_64bits struct.

Parameters

bits_

A pointer to the cosc_64bits struct.

COSC_64BITS_INIT

#define COSC_64BITS_INIT	(		hi_,
			lo_ )

Value:

{{(hi_), (lo_)}}

Helper initializer when defining cosc_64bits structs.

Parameters

hi_	The 32 most significant bits.
lo_	The 32 least significant bits.

Returns

Object initializer code.

COSC_64BITS_LO

#define COSC_64BITS_LO

(

bits_

)

Value:

((bits_)->w[1])

Helper to access the low member of a cosc_64bits struct.

Parameters

bits_

A pointer to the cosc_64bits struct.

COSC_64BITS_SET

#define COSC_64BITS_SET	(		bits_,
			hi_,
			lo_ )

Value:

do { COSC_64BITS_HI(bits_) = (hi_); COSC_64BITS_LO(bits_) = (lo_); } while (0)

Helper to set the members of a cosc_64bits struct.

Parameters

bits_	A pointer to the cosc_64bits struct.
hi_	The 32 most significant bits.
lo_	The 32 least significant bits.

COSC_FLOAT64_INIT_ZERO

#define COSC_FLOAT64_INIT_ZERO   0

Initializer cosc_float64 or cosc_ufloat64 as zero.

Parameters

ptr	A pofloater to the cosc_float64 or cosc_ufloat64.

COSC_FLOAT64_SET_ZERO

#define COSC_FLOAT64_SET_ZERO

(

ptr

)

Value:

(*(ptr) = 0)

Set cosc_float64 or cosc_ufloat64 as zero.

Parameters

ptr	A pofloater to the cosc_float64 or cosc_ufloat64.

COSC_INT64_INIT_ZERO

#define COSC_INT64_INIT_ZERO   0

Initializer cosc_int64 or cosc_uint64 as zero.

Parameters

ptr	A pointer to the cosc_int64 or cosc_uint64.

COSC_INT64_SET_ZERO

#define COSC_INT64_SET_ZERO

(

ptr

)

Value:

(*(ptr) = 0)

Set cosc_int64 or cosc_uint64 as zero.

Parameters

ptr	A pointer to the cosc_int64 or cosc_uint64.

COSC_PAD

#define COSC_PAD

(

sz

)

Value:

(COSC_PADMUST(sz) & 3)

Get the required zero pad size for 4 byte alignment.

Parameters

sz	The byte size of the object.

Returns

The number of zeroes to pad.

COSC_PADMUST

#define COSC_PADMUST

(

sz

)

Value:

(4 - ((cosc_uint32)(sz) & 3))

Get the required zero pad size for strings that require a zero terminator and 4 byte alignment.

Parameters

sz	The byte size of the string, excluding the zero terminator.

Returns

The number of zeroes to pad.

COSC_SERIAL_ISREADER

#define COSC_SERIAL_ISREADER

(

serial_

)

Value:

((serial_)->rbuffer != 0)

Macro to check if a serial is a reader.

Parameters

serial_

A pointer to the serial.

Returns

True or false.

COSC_SERIAL_ISWRITER

#define COSC_SERIAL_ISWRITER

(

serial_

)

Value:

((serial_)->wbuffer != 0)

Macro to check if a serial is a writer.

Parameters

serial_

A pointer to the serial.

Returns

True or false.

COSC_TYPE_FLOAT32

#define COSC_TYPE_FLOAT32   float

Used to typedef cosc_float32.

Note

If defined it must be at both compile and include time.

Must be exactly 32 bits in width.

COSC_TYPE_FLOAT64

#define COSC_TYPE_FLOAT64   double

Used to typedef cosc_float64.

Note

If defined it must be at both compile and include time.

Must be exactly 64 bits in width.

COSC_TYPE_INT32

#define COSC_TYPE_INT32   int32_t

Used to typedef cosc_int32.

Note

If defined it must be at both compile and include time.

Must be exactly 32 bits in width.

COSC_TYPE_INT64

#define COSC_TYPE_INT64   int64_t

Used to typedef cosc_int64.

Note

If defined it must be at both compile and include time.

Must be exactly 64 bits in width.

COSC_TYPE_UINT32

#define COSC_TYPE_UINT32   uint32_t

Used to typedef cosc_uint32.

Note

If defined it must be at both compile and include time.

Must be exactly 32 bits in width.

COSC_TYPE_UINT64

#define COSC_TYPE_UINT64   uint64_t

Used to typedef cosc_uint64.

Note

If defined it must be at both compile and include time.

Must be exactly 64 bits in width.

Function Documentation

cosc_address_char_validate()

COSC_API cosc_int32 cosc_address_char_validate

(

cosc_int32

c

)

Check if an address character is valid.

Parameters

c	The character.

Returns

Non-zero if valid or zero if invalid.

cosc_address_validate()

COSC_API cosc_int32 cosc_address_validate	(	const char *	address,
		cosc_int32	address_n,
		cosc_int32 *	invalid )

Scan address for invalid characters.

Parameters

	address	The address.
	address_n	Read at most this many bytes from address.
[out]	invalid	If non-NULL and the function returns 0 the index of the invalid character is stored here.

Returns

Non-zero if valid or zero if invalid.

Note

If the address is valid the value stored to invalid will be -1.

Invalid characters are "#*,?[]{}" and any ASCII <= 32.

See also

cosc_typetag_validate() and cosc_pattern_validate().

cosc_big_endian()

COSC_API cosc_int32 cosc_big_endian

(

void

)

If big endian was detected when building this function returns non-zero, otherwise zero.

Returns

Non-zero if big endian was detected when building, otherwise zero.

cosc_feature_array()

COSC_API cosc_int32 cosc_feature_array

(

void

)

Feature test for array support.

Returns

Non-zero if cosc was built with array support.

cosc_feature_float32()

COSC_API cosc_int32 cosc_feature_float32

(

void

)

Feature test for 32-bit float support.

Returns

Non-zero if cosc was built with 32-bit float support.

cosc_feature_float64()

COSC_API cosc_int32 cosc_feature_float64

(

void

)

Feature test for 64-bit float support.

Returns

Non-zero if cosc was built with 64-bit float support.

cosc_feature_fltconv()

COSC_API cosc_int32 cosc_feature_fltconv

(

void

)

Feature test for float conversion support.

Returns

Non-zero if cosc was built with float support.

cosc_feature_int64()

COSC_API cosc_int32 cosc_feature_int64

(

void

)

Feature test for 64-bit integer support.

Returns

Non-zero if cosc was built with 64-bit integer support.

cosc_feature_pattern()

COSC_API cosc_int32 cosc_feature_pattern

(

void

)

Feature test for pattern support.

Returns

Non-zero if cosc was built with pattern support.

cosc_feature_reader()

COSC_API cosc_int32 cosc_feature_reader

(

void

)

Feature test for reader support.

Returns

Non-zero if cosc was built with reader support.

cosc_feature_swap()

COSC_API cosc_int32 cosc_feature_swap

(

void

)

Feature test for endian swapping.

Returns

Non-zero if cosc was built with endian swapping.

cosc_feature_timetag()

COSC_API cosc_int32 cosc_feature_timetag

(

void

)

Feature test for timetag conversion support.

Returns

Non-zero if cosc was built with timetag support.

cosc_feature_writer()

COSC_API cosc_int32 cosc_feature_writer

(

void

)

Feature test for writer support.

Returns

Non-zero if cosc was built with writer support.

cosc_float32_to_float64()

COSC_API cosc_float64 cosc_float32_to_float64

(

cosc_float32

value

)

Convert a 32-bit float to a 64-bit float.

Parameters

value

The 32-bit float.

Returns

The 64-bit float.

Note

This function is only useful if either or both COSC_NOFLOAT32 and COSC_FLOAT64 were defined when building.

Remarks

This function is not available if cosc was built with COSC_NOFLTCONV.

cosc_float64_to_float32()

COSC_API cosc_float32 cosc_float64_to_float32

(

cosc_float64

value

)

Convert a 64-bit float to a 32-bit float.

Parameters

value

The 64-bit float.

Returns

The 32-bit float.

Note

This function is only useful if either or both COSC_NOFLOAT32 and COSC_FLOAT64 were defined when building.

Remarks

This function is not available if cosc was built with COSC_NOFLTCONV.

cosc_message_dump()

COSC_API cosc_int32 cosc_message_dump	(	char *	s,
		cosc_int32	n,
		const struct cosc_message *	message )

Dump an OSC message to string.

Parameters

[out]	s	If non-NULL store to this string.
	n	Store at most this many bytes to s.
	message	The message.

Returns

The length of the string, excluding the zero terminator.

Note

The returned length may be greater than or equal to n indicating that the string was truncated.

Remarks

This function is not available if COSC_NOSTDLIB or COSC_NODUMP were defined when compiling.

Examples

bundle.c, and message.c.

cosc_pattern_char_validate()

COSC_API cosc_int32 cosc_pattern_char_validate

(

cosc_int32

c

)

Check if an pattern character is valid.

Parameters

c	The character.

Returns

Non-zero if valid or zero if invalid.

Remarks

This function is not available if COSC_NOPATTERN was defined when compiling.

cosc_pattern_match()

COSC_API cosc_int32 cosc_pattern_match	(	const char *	s,
		cosc_int32	s_n,
		const char *	pattern,
		cosc_int32	pattern_n )

Match an address or typetag.

Parameters

s	The address or typetag to match with.
s_n	Read at most this many bytes from s.
pattern	The matching pattern.
pattern_n	Read at most this many bytes from pattern.

Returns

Non-zero when matching or zero for no match.

Note

Because square brackets collide with the array syntax of OSC typetags the array brackets are ignored when matching.

For typetags the comma prefix and array brackets are ignored and should be omitted from the pattern.

Remarks

This function is not available if COSC_NOPATTERN was defined when compiling.

Pattern syntax:

• * match zero or more characters.
• [] match any character inside square brackets.
• {} match any comma separated string inside curly brackets.
• '?' match a single character.

Extended syntax for typetags, not part of the OSC specification:

• '#' for typetags match a numeric type ('i', 'f', 'r', 'h', 't' and 'd').
• '#' for addresses match a base-10 digit (0-9).
• 'B' match a boolean ('T' or 'F').

When matching addresses '#' is simply ignored.

cosc_pattern_validate()

COSC_API cosc_int32 cosc_pattern_validate	(	const char *	s,
		cosc_int32	s_n,
		cosc_int32 *	invalid )

Scan matching pattern for invalid characters.

Parameters

	s	The pattern.
	s_n	Read at most this many bytes from s.
[out]	invalid	If non-NULL and the function returns 0 the index of the invalid character is stored here.

Returns

Non-zero if valid or zero if invalid.

Note

If the pattern is valid or s_n <= 0 or s is empty the value stored to invalid will be -1.

If the function returns 0 and the value stored to invalid is >= s_n it means the pattern ended unexpectedly, probably due to an unclosed '[' or '{' marker.

See also

cosc_address_validate(), cosc_typetag_validate() and cosc_pattern_match().

Note

When matching typetags the comma prefix and any array syntax characters are removed from the matching.

Remarks

This function is not available if COSC_NOPATTERN was defined when compiling.

cosc_read_blob()

COSC_API cosc_int32 cosc_read_blob	(	const void *	buffer,
		cosc_int32	size,
		void *	value,
		cosc_int32	value_n,
		const void **	data,
		cosc_int32 *	data_size )

Read a blob.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
[out]	value	If non-NULL and the function does not return a negative error code store the blob data here.
	value_n	Store at most this many bytes to value.
[out]	data	If non-NULL and the function does not return a negative error code a pointer to the first byte of the blob data is stored here, or NULL if the blob has zero bytes.
[out]	data_size	If non-NULL and the function does not return a negative error code the size of the blob data is stored here.

Returns

The number of read bytes or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if size is too small.
• COSC_ESIZEMAX if the data_size exceeds COSC_SIZE_MAX.
• COSC_EPSIZE if the data_size is invalid.

cosc_read_bundle()

COSC_API cosc_int32 cosc_read_bundle	(	const void *	buffer,
		cosc_int32	size,
		cosc_uint64 *	timetag,
		cosc_int32 *	psize )

Read an OSC bundle head.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
[out]	timetag	If non-NULL and the function does not return a negative error code the timetag is stored here.
[out]	psize	If non-NULL and a signed 32-bit integer at the start describing the byte size of the message is stored here, NULL if there is no packet size descriptor prefix.

Returns

The number of read bytes or a negative error code if the operation fails.

Note

If size is non-NULL and the size < 4 the value stored to size will be 0.

Possible error codes:

• COSC_EOVERRUN if buffer is non-NULL and size is too small.
• COSC_EPSIZE if psize is invalid.
• COSC_ETYPE if buffer does not have a "#bundle" head.

Examples

bundle.c.

cosc_read_char()

COSC_API cosc_int32 cosc_read_char	(	const void *	buffer,
		cosc_int32	size,
		cosc_int32 *	value )

Read an ASCII character.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if size is too small.

cosc_read_float32()

COSC_API cosc_int32 cosc_read_float32	(	const void *	buffer,
		cosc_int32	size,
		cosc_float32 *	value )

Read a 32-bit big endian floating point.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if size is too small.

cosc_read_float64()

COSC_API cosc_int32 cosc_read_float64	(	const void *	buffer,
		cosc_int32	size,
		cosc_float64 *	value )

Read a 64-bit big endian floating point.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if size is too small.

cosc_read_int32()

COSC_API cosc_int32 cosc_read_int32	(	const void *	buffer,
		cosc_int32	size,
		cosc_int32 *	value )

Read a 32-bit big endian signed integer.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if size is too small.

cosc_read_int64()

COSC_API cosc_int32 cosc_read_int64	(	const void *	buffer,
		cosc_int32	size,
		cosc_int64 *	value )

Read a 64-bit big endian signed integer.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if size is too small.

cosc_read_message()

COSC_API cosc_int32 cosc_read_message	(	const void *	buffer,
		cosc_int32	size,
		struct cosc_message *	message,
		cosc_int32 *	psize,
		cosc_int32 *	value_count,
		cosc_int32	exit_early )

Read an OSC message.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
	message	The message or NULL to discard the message.
	psize	If non-NULL read a 32 bit packet size integer before the message and store it here, may be 0 if the function fails before reading it. NULL if you are not expecting any packet size integer at the start of the buffer.
[out]	value_count	If non-NULL the number of read values is stored here.
	exit_early	If non-zero and the types have an array specified the function will stop reading more array members and exit early even if there are more bytes left in buffer.

Returns

The number of read bytes or a negative error code if the operation fails.

Note

The message address is NOT validated.

If message.values_n is less than the values specified in message.typetag the rest of the values will be read and discarded.

The value of exit_early has no effect if COSC_NOARRAY was defined when building.

• COSC_EOVERRUN if size is too small.
• COSC_ESIZEMAX if size > COSC_SIZE_MAX.
• COSC_ETYPE if mesage typetag is invalid.
• COSC_EPSIZE if the size

Examples

bundle.c, and message.c.

cosc_read_midi()

COSC_API cosc_int32 cosc_read_midi	(	const void *	buffer,
		cosc_int32	size,
		unsigned char	value[4] )

Read an ASCII character.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code if the operation fails.

Note

The last byte isn't used by actual MIDI.

Possible error codes:

• COSC_EOVERRUN if size is too small.

cosc_read_signature()

COSC_API cosc_int32 cosc_read_signature	(	const void *	buffer,
		cosc_int32	size,
		const char **	address,
		cosc_int32 *	address_n,
		const char **	typetag,
		cosc_int32 *	typetag_n,
		cosc_int32 *	psize )

Read an OSC message signature.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
[out]	address	If non-NULL and the function does not return a negative error code the address pointer is stored here.
[out]	address_n	If non-NULL and the function does not return a negative error code the address length, excluding the zero terminator, is stored here.
[out]	typetag	If non-NULL and the function does not return a negative error code the typetag pointer is stored here.
[out]	typetag_n	If non-NULL and the function does not return a negative error code the typetag length, excluding the zero terminator, is stored here.
[out]	psize	If non-NULL and the function does not return a negative error code a signed 32-bit integer at the start describing the byte size of the message is stored here, NULL if there is no size descriptor prefix.

Returns

The number of read bytes or a negative error code if the operation fails.

Note

This function does NOT validate address or typetag.

Possible error codes:

• COSC_EOVERRUN if size is too small.
• COSC_ESIZEMAX if the size exceeds COSC_SIZE_MAX.
• COSC_EPSIZE if psize is invalid.

cosc_read_string()

COSC_API cosc_int32 cosc_read_string	(	const void *	buffer,
		cosc_int32	size,
		char *	value,
		cosc_int32	value_n,
		cosc_int32 *	length )

Read a string.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
[out]	value	If non-NULL store the string here.
	value_n	Store at most this many bytes to value.
[out]	length	If non-NULL and the function does not return a negative error code the length of the string, excluding the zero terminator, is stored here.

Returns

The number of read bytes or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if size is too small.

cosc_read_uint32()

COSC_API cosc_int32 cosc_read_uint32	(	const void *	buffer,
		cosc_int32	size,
		cosc_uint32 *	value )

Read a 32-bit big endian unsigned integer.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if size is too small.

cosc_read_uint64()

COSC_API cosc_int32 cosc_read_uint64	(	const void *	buffer,
		cosc_int32	size,
		cosc_uint64 *	value )

Read a 64-bit big endian unsigned integer.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if size is too small.

cosc_read_value()

COSC_API cosc_int32 cosc_read_value	(	const void *	buffer,
		cosc_int32	size,
		char	type,
		union cosc_value *	value )

Read an OSC value.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
	type	The type.
[out]	value	If non-NULL and the functon does not return a negative error code store the read values here.

Returns

The number of read bytes or a negative error code if the operation fails.

• COSC_EOVERRUN if size is too small.
• COSC_ESIZEMAX if size > COSC_SIZE_MAX.
• COSC_ETYPE if type is invalid.

cosc_read_values()

COSC_API cosc_int32 cosc_read_values	(	const void *	buffer,
		cosc_int32	size,
		const char *	types,
		cosc_int32	types_n,
		union cosc_value *	values,
		cosc_int32	values_n,
		cosc_int32 *	value_count,
		cosc_int32	exit_early )

Read OSC values.

Parameters

	buffer	Read bytes from this buffer.
	size	Read at most this many bytes from buffer.
	types	The types, the starting comma may be omitted.
	types_n	Read at most this many bytes from types.
[out]	values	If non-NULL store the read values here.
	values_n	Store at most this many members to values.
[out]	value_count	If non-NULL the number of read values is stored here.
	exit_early	If non-zero and the types have an array specified the function will stop reading more array members and exit early even if there are more bytes left in buffer.

Returns

The number of read bytes or a negative error code if the operation fails.

Note

If values_n is less than the values specified by types the remaining values are discarded.

The value of exit_early has no effect if COSC_NOARRAY was defined when building.

• COSC_EOVERRUN if size is too small.
• COSC_ESIZEMAX if size > COSC_SIZE_MAX.
• COSC_ETYPE if type is invalid.

cosc_reader_blob()

COSC_API cosc_int32 cosc_reader_blob	(	struct cosc_serial *	serial,
		void *	value,
		cosc_int32	value_n,
		const void **	data,
		cosc_int32 *	data_size )

Write a blob.

Parameters

	serial	The serial.
[out]	value	If non-NULL and the function does not return a negative error code store the blob data here.
	value_n	Store at most this many bytes to value.
[out]	data	If non-NULL and the function does not return a negative error code a pointer to the first byte of the blob data is stored here, or NULL if the blob has zero bytes.
[out]	data_size	If non-NULL and the function does not return a negative error code the size of the blob data is stored here.

Returns

The number of read bytes or a negative error code on failure.

Note

To read raw bytes to a started blob level use cosc_reader_bytes().

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_reader_bytes()

COSC_API cosc_int32 cosc_reader_bytes	(	struct cosc_serial *	serial,
		void *	value,
		cosc_int32	value_n )

Read bytes to a started blob level.

Parameters

	serial	The serial.
[out]	value	If non-NULL store read bytes here or NULL to discard the bytes.
	value_n	The number of bytes to read.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.

cosc_reader_char()

COSC_API cosc_int32 cosc_reader_char	(	struct cosc_serial *	serial,
		cosc_int32 *	value )

Write an ASCII character.

Parameters

	serial	The serial.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_reader_end_blob()

COSC_API cosc_int32 cosc_reader_end_blob

(

struct cosc_serial *

serial

)

End a blob level.

Parameters

serial

The serial.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer, this can happen if the blob needs to add pad bytes.
• COSC_ELEVELTYPE if the current level is not a blob.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

Examples

serial.c.

cosc_reader_end_bundle()

COSC_API cosc_int32 cosc_reader_end_bundle

(

struct cosc_serial *

serial

)

End a bundle level.

Parameters

serial

The serial.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_ELEVELTYPE if the current level is not a bundle.

Examples

serial.c.

cosc_reader_end_message()

COSC_API cosc_int32 cosc_reader_end_message	(	struct cosc_serial *	serial,
		cosc_int32	exit_early )

End a message level.

Parameters

serial	The serial.
exit_early	If non-zero and the types have an array specified the function will stop reading more array members and exit early even if there are more bytes left in buffer.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_ELEVELTYPE if the current level is not a message.

Examples

serial.c.

cosc_reader_float32()

COSC_API cosc_int32 cosc_reader_float32	(	struct cosc_serial *	serial,
		cosc_float32 *	value )

Write a 32-bit float.

Parameters

	serial	The serial.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

Examples

serial.c.

cosc_reader_float64()

COSC_API cosc_int32 cosc_reader_float64	(	struct cosc_serial *	serial,
		cosc_float64 *	value )

Write a 64-bit float.

Parameters

	serial	The serial.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_reader_int32()

COSC_API cosc_int32 cosc_reader_int32	(	struct cosc_serial *	serial,
		cosc_int32 *	value )

Write a signed 32-bit integer.

Parameters

	serial	The serial.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

Examples

serial.c.

cosc_reader_int64()

COSC_API cosc_int32 cosc_reader_int64	(	struct cosc_serial *	serial,
		cosc_int64 *	value )

Write a signed 64-bit integer.

Parameters

	serial	The serial.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_reader_message()

COSC_API cosc_int32 cosc_reader_message	(	struct cosc_serial *	serial,
		struct cosc_message *	message,
		cosc_int32 *	value_count,
		cosc_int32	exit_early )

Read an OSC message.

Parameters

	serial	The serial.
	message	The message or NULL to discard the message.
[out]	value_count	If non-NULL the number of read values is stored here.
	exit_early	If non-zero and the types have an array specified the function will stop reading more array members and exit early even if there are more bytes left in buffer.

Returns

The number of read bytes or a negative error code if the operation fails.

Note

The message address is NOT validated.

If message.values_n is less than the values specified in message.typetag the rest of the values will be read and discarded.

The value of exit_early has no effect if COSC_NOARRAY was defined when building.

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_ETYPE if the message typetag is invalid.

Examples

serial.c.

cosc_reader_midi()

COSC_API cosc_int32 cosc_reader_midi	(	struct cosc_serial *	serial,
		unsigned char	value[4] )

Write a MIDI message.

Parameters

	serial	The serial.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code on failure.

Note

Normally the fourth byte isn't used in MIDI.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_reader_peek_bundle()

COSC_API cosc_int32 cosc_reader_peek_bundle	(	struct cosc_serial *	serial,
		cosc_uint64 *	timetag,
		cosc_int32 *	psize )

Check if the buffer has a bundle at the current read size.

Parameters

	serial	The serial.
[out]	timetag	If non-NULL and the function does not return a negative error code the timestamp is stored here.
	psize	If non-NULL and the function does not return a negative error code stored the packet size here, will be 0 if there is no packet size.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept a bundle.
• COSC_ETYPE if it's not a bundle.

Examples

serial.c.

cosc_reader_repeat()

COSC_API cosc_int32 cosc_reader_repeat

(

struct cosc_serial *

serial

)

Repeat typetag from the beginning of an array start, not including the starting '[' character.

Parameters

serial

The serial.

Returns

0 on success or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE the current message typetag type is not ']'.

cosc_reader_setup()

COSC_API void cosc_reader_setup	(	struct cosc_serial *	serial,
		const void *	buffer,
		cosc_int32	buffer_size,
		struct cosc_level *	levels,
		cosc_int32	level_max,
		cosc_uint32	flags )

Setup a serial for reading.

Parameters

[out]	serial	The serial.
	buffer	A writable buffer, must not be NULL.
	buffer_size	The size of the buffer.
	levels	Provided levels, must point to an array of levels with at least one member.
	level_max	The number of provided levels, must be at least 1.
	flags	Serial flags, see COSC_SERIAL_* macros.

See also

COSC_SERIAL_PSIZE.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Examples

serial.c.

cosc_reader_skip()

COSC_API cosc_int32 cosc_reader_skip

(

struct cosc_serial *

serial

)

Skip a value, if the value has payload it will be zeroes.

Parameters

serial

The serial.

Returns

The number of read bytes or a negative error code on failure or 0 if there are no more types in the message typetag.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_reader_start_blob()

COSC_API cosc_int32 cosc_reader_start_blob	(	struct cosc_serial *	serial,
		cosc_int32 *	value_size )

Start a new blob level.

Parameters

	serial	The serial.
[out]	value_size	If non-NULL and the function does not return a negative error code the BLOB data size is stored here.

Returns

The number of read bytes or a negative error code on failure.

Note

To read raw bytes to a started blob level use cosc_reader_bytes().

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELMAX the maximum number of levels is reached.
• COSC_ELEVELTYPE if the current level does not accept a blob.

Examples

serial.c.

cosc_reader_start_bundle()

COSC_API cosc_int32 cosc_reader_start_bundle	(	struct cosc_serial *	serial,
		cosc_uint64 *	timetag )

Start a new bundle level.

Parameters

	serial	The serial.
[out]	timetag	If non-NULL and the function does not return a negative error code the timestamp is stored here.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELMAX the maximum number of levels is reached.
• COSC_ELEVELTYPE if the current level does not accept a bundle.
• COSC_ETYPE if it's not a bundle.

Examples

serial.c.

cosc_reader_start_message()

COSC_API cosc_int32 cosc_reader_start_message	(	struct cosc_serial *	serial,
		const char **	address,
		cosc_int32 *	address_n,
		const char **	typetag,
		cosc_int32 *	typetag_n )

Start a new message level.

Parameters

	serial	The serial.
[out]	address	If non-NULL and the function does not return a negative error code a pointer to the address is stored here.
[out]	address_n	If non-NULL and the function does not return a negative error code the length, excluding the zero terminator, of the address is stored here.
[out]	typetag	If non-NULL and the function does not return a negative error code a pointer to the typetag is stored here.
[out]	typetag_n	If non-NULL and the function does not return a negative error code the length, excluding the zero terminator, of the typetag is stored here.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELMAX the maximum number of levels is reached.
• COSC_ELEVELTYPE if the current level does not accept a message.

Examples

serial.c.

cosc_reader_string()

COSC_API cosc_int32 cosc_reader_string	(	struct cosc_serial *	serial,
		char *	value,
		cosc_int32	value_n,
		cosc_int32 *	length )

Write a string.

Parameters

	serial	The serial.
[out]	value	If non-NULL store the string here.
	value_n	Store at most this many bytes to value.
[out]	length	If non-NULL and the function does not return a negative error code the length of the string, excluding the zero terminator, is stored here.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_reader_uint32()

COSC_API cosc_int32 cosc_reader_uint32	(	struct cosc_serial *	serial,
		cosc_uint32 *	value )

Write an unsigned 32-bit integer.

Parameters

	serial	The serial.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_reader_uint64()

COSC_API cosc_int32 cosc_reader_uint64	(	struct cosc_serial *	serial,
		cosc_uint64 *	value )

Write an unsigned 64-bit integer.

Parameters

	serial	The serial.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_reader_value()

COSC_API cosc_int32 cosc_reader_value	(	struct cosc_serial *	serial,
		cosc_int32	type,
		union cosc_value *	value )

Read a value.

Parameters

	serial	The serial.
	type	The value typetag type.
[out]	value	If non-NULL and the function does not return a negative error code the value is stored here.

Returns

The number of read bytes or a negative error code on failure.

Note

Normally the fourth byte isn't used in MIDI.

Remarks

This function is not available if COSC_NOREADER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a writer.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.
• COSC_ETYPE if type is invalid.

cosc_serial_get_buffer_size()

COSC_API cosc_int32 cosc_serial_get_buffer_size

(

const struct cosc_serial *

serial

)

The maximum number of bytes that can be written/read to/from the buffer.

Parameters

serial

The serial.

Returns

The maximum number of bytes to write/read.

Remarks

This function is not available if both COSC_NOWRITER and COSC_NOREADER were defined when compiling.

cosc_serial_get_msgtype()

COSC_API cosc_int32 cosc_serial_get_msgtype

(

const struct cosc_serial *

serial

)

Get the current typetag type of a message level.

Parameters

serial

The serial.

Returns

The current message typetag type, COSC_ELEVELTYPE if the current leve is not a message or 0 if the typetag has reached it's end.

Remarks

This function is not available if both COSC_NOWRITER and COSC_NOREADER were defined when compiling.

cosc_serial_get_size()

COSC_API cosc_int32 cosc_serial_get_size

(

const struct cosc_serial *

serial

)

Get the number of written or read bytes.

Parameters

serial

The serial.

Returns

The number of written/read bytes.

Remarks

This function is not available if both COSC_NOWRITER and COSC_NOREADER were defined when compiling.

Examples

serial.c.

cosc_serial_reset()

COSC_API void cosc_serial_reset

(

struct cosc_serial *

serial

)

Reset serial.

Parameters

serial

The serial.

cosc_signature_match()

COSC_API cosc_int32 cosc_signature_match	(	const void *	buffer,
		cosc_int32	size,
		const char *	apattern,
		cosc_int32	apattern_n,
		const char *	tpattern,
		cosc_int32	tpattern_n,
		cosc_int32	prefix )

Match an address and typetag.

Parameters

buffer	The buffer.
size	Read at most this many bytes from buffer.
apattern	The matching pattern for the address.
apattern_n	Read at most this many bytes from apattern.
tpattern	The matching pattern for the typetag.
tpattern_n	Read at most this many bytes from apattern.
prefix	Non-zero to expect a message with a 32-bit signed size integer prefix.

Returns

Non-zero when matching or zero for no match.

Remarks

This function is not available if COSC_NOPATTERN was defined when compiling.

cosc_time_to_timetag()

COSC_API cosc_uint64 cosc_time_to_timetag	(	cosc_uint32	seconds,
		cosc_uint32	nanos )

Convert time to a timetag.

Parameters

seconds	The time in seconds.
nanos	The time nanos.

Returns

The timetag.

Examples

bundle.c, and serial.c.

cosc_timetag_to_time()

COSC_API cosc_uint32 cosc_timetag_to_time	(	cosc_uint64	timetag,
		cosc_uint32 *	nanos )

Convert a timetag to seconds and nanoseconds.

Parameters

	timetag	The timetag.
[out]	nanos	If non-NULL store the nanoseconds here.

Returns

The seconds.

Note

Because a timetag's fraction of a second is greater than a nanosecond the returned nanos will have a loss of precision.

Examples

bundle.c, and serial.c.

cosc_typetag_char_validate()

COSC_API cosc_int32 cosc_typetag_char_validate

(

cosc_int32

c

)

Check if an typetag character is valid.

Parameters

c	The character.

Returns

Non-zero if valid or zero if invalid.

cosc_typetag_payload()

COSC_API cosc_int32 cosc_typetag_payload	(	char *	s,
		cosc_int32	s_n,
		const char *	typetag,
		cosc_int32	typetag_n,
		cosc_int32 *	array_members )

Scan typetag for types with payload, ignoring the comma prefix, array syntax and types T, F, N and I.

Parameters

[out]	s	If non-NULL store the payload types here.
	s_n	Store at most this many bytes to s.
	typetag	The typetag.
	typetag_n	Read at most this many bytes from typetag.
[out]	array_members	If non-NULL store the number of payload types that belong to an array, i.e is inside the array syntax.

Returns

The total number of types with payload found in typetag.

Note

This function does not exit early or report any errors for invalid typetags.

This function will zero terminate s, make sure it is wide enough to accept all types + 1.

The function may return a value greater than or equal to s_n indicating that some types may have been truncated to fit s.

If cosc was built with COSC_NOARRAY the value stored to array_members will always be 0.

cosc_typetag_validate()

COSC_API cosc_int32 cosc_typetag_validate	(	const char *	typetag,
		cosc_int32	typetag_n,
		cosc_int32 *	invalid )

Scan typetag for invalid characters.

Parameters

	typetag	The typetag.
	typetag_n	Read at most this many bytes from typetag.
[out]	invalid	If non-NULL and the function returns 0 the index of the invalid character is stored here.

Returns

Non-zero if valid or zero if invalid.

Note

If the typetag is valid or s_n <= 0 or s is empty the value stored to invalid will be -1.

If the function returns 0 and the value stored to invalid is >= s_n it means the typetag ended unexpectedly, probably due to an unclosed array '[' marker.

Typetags must always start with ',', even if they contain no types.

See also

cosc_address_validate() and cosc_pattern_validate().

cosc_value_dump()

COSC_API cosc_int32 cosc_value_dump	(	char *	s,
		cosc_int32	n,
		char	type,
		const union cosc_value *	value )

Dump an OSC value to string.

Parameters

[out]	s	If non-NULL store to this string.
	n	Store at most this many bytes to s.
	type	The OSC typetag type.
	value	The value.

Returns

The length of the string, excluding the zero terminator.

Note

The returned length may be greater than or equal to n indicating that the string was truncated.

Remarks

This function is not available if COSC_NOSTDLIB or COSC_NODUMP were defined when compiling.

cosc_write_blob()

COSC_API cosc_int32 cosc_write_blob	(	void *	buffer,
		cosc_int32	size,
		const void *	value,
		cosc_int32	value_n )

Write a blob.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	value	The blob data, may be NULL to fill with zeroes.
	value_n	The size of the blob data.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if buffer is non-NULL and size is too small.
• COSC_ESIZEMAX if the blob exceeds COSC_SIZE_MAX.

cosc_write_bundle()

COSC_API cosc_int32 cosc_write_bundle	(	void *	buffer,
		cosc_int32	size,
		cosc_uint64	timetag,
		cosc_int32	psize )

Write an OSC bundle head.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	timetag	The timetag of the bundle.
	psize	0 for no packet size integer, < 0 to write a packet size integer based on the signature data or > 0 to set the packet size to a specific value.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Note

You can use cosc_write_int32() to store a new psize at the beginning of the buffer at a later time.

Possible error codes:

• COSC_EOVERRUN if buffer is non-NULL and size is too small.
• COSC_ESIZEMAX if psize + the bundle data exceeds COSC_SIZE_MAX.
• COSC_EPSIZE if size > 0 and is invalid or too small.

Examples

bundle.c.

cosc_write_char()

COSC_API cosc_int32 cosc_write_char	(	void *	buffer,
		cosc_int32	size,
		cosc_int32	value )

Write an ASCII character.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	value	The value.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if buffer is non-NULL and size is too small.

cosc_write_float32()

COSC_API cosc_int32 cosc_write_float32	(	void *	buffer,
		cosc_int32	size,
		cosc_float32	value )

Write a 32-bit big endian floating point.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	value	The value.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if buffer is non-NULL and size is too small.

cosc_write_float64()

COSC_API cosc_int32 cosc_write_float64	(	void *	buffer,
		cosc_int32	size,
		cosc_float64	value )

Write a 64-bit big endian floating point.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	value	The value.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if buffer is non-NULL and size is too small.

cosc_write_int32()

COSC_API cosc_int32 cosc_write_int32	(	void *	buffer,
		cosc_int32	size,
		cosc_int32	value )

Write a 32-bit big endian signed integer.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	value	The value.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if buffer is non-NULL and size is too small.

Examples

bundle.c.

cosc_write_int64()

COSC_API cosc_int32 cosc_write_int64	(	void *	buffer,
		cosc_int32	size,
		cosc_int64	value )

Write a 64-bit big endian signed integer.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	value	The value.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if buffer is non-NULL and size is too small.

cosc_write_message()

COSC_API cosc_int32 cosc_write_message	(	void *	buffer,
		cosc_int32	size,
		const struct cosc_message *	message,
		cosc_int32	psize,
		cosc_int32 *	value_count )

Write an OSC message.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	message	The message or NULL for an empty message.
	psize	0 for no packet size integer, < 0 to write a packet size integer based on the signature data or > 0 to set the packet size to a specific value.
[out]	value_count	If non-NULL the number of written values is stored here.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Note

The message address is NOT validated.

If message.values_n is less than the values specified in message.typetag the rest of the values will be written as zero/empty.

• COSC_EOVERRUN if buffer is non-NULL and size is too small.
• COSC_ESIZEMAX if size > COSC_SIZE_MAX.
• COSC_ETYPE if message typetag is invalid.
• COSC_EPSIZE if size > 0 and is invalid or too small.

Examples

bundle.c, and message.c.

cosc_write_midi()

COSC_API cosc_int32 cosc_write_midi	(	void *	buffer,
		cosc_int32	size,
		const unsigned char	value[4] )

Write a MIDI message.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	value	The value or NULL to fill the message with zeroes.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Note

The last byte isn't used by actual MIDI.

Possible error codes:

• COSC_EOVERRUN if buffer is non-NULL and size is too small.

cosc_write_signature()

COSC_API cosc_int32 cosc_write_signature	(	void *	buffer,
		cosc_int32	size,
		const char *	address,
		cosc_int32	address_n,
		const char *	typetag,
		cosc_int32	typetag_n,
		cosc_int32	psize )

Write an OSC message signature.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	address	The address.
	address_n	Read at most this many bytes from address.
	typetag	The typetag.
	typetag_n	Read at most this many bytes from typetag.
	psize	0 for no packet size integer, < 0 to write a packet size integer based on the signature data or > 0 to set the packet size to a specific value.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Note

You can use cosc_write_int32() to store a new psize at the beginning of the buffer at a later time.

This function does NOT validate address or typetag.

Possible error codes:

• COSC_EOVERRUN if buffer is non-NULL and size is too small.
• COSC_ESIZEMAX if the size exceeds COSC_SIZE_MAX.
• COSC_EPSIZE if size > 0 and is invalid or too small.

cosc_write_string()

COSC_API cosc_int32 cosc_write_string	(	void *	buffer,
		cosc_int32	size,
		const char *	value,
		cosc_int32	value_n,
		cosc_int32 *	length )

Write a string.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	value	The string.
	value_n	Read at most this many bytes from s.
[out]	length	If non-NULL and the function does not return a negative error code the length of the string, excluding the zero terminator, is stored here.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if buffer is non-NULL and size is too small.
• COSC_ESIZEMAX if the string exceeds COSC_SIZE_MAX.

cosc_write_uint32()

COSC_API cosc_int32 cosc_write_uint32	(	void *	buffer,
		cosc_int32	size,
		cosc_uint32	value )

Write a 32-bit, big endian unsigned integer.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	value	The value.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if buffer is non-NULL and size is too small.

cosc_write_uint64()

COSC_API cosc_int32 cosc_write_uint64	(	void *	buffer,
		cosc_int32	size,
		cosc_uint64	value )

Write a 64-bit, big endian unsigned integer.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	value	The value.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Possible error codes:

• COSC_EOVERRUN if buffer is non-NULL and size is too small.

cosc_write_value()

COSC_API cosc_int32 cosc_write_value	(	void *	buffer,
		cosc_int32	size,
		char	type,
		const union cosc_value *	value )

Write an OSC value.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	type	The type.
	value	The value or NULL for zeroed/empty.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

• COSC_EOVERRUN if buffer is non-NULL and size is too small.
• COSC_ESIZEMAX if size > COSC_SIZE_MAX.
• COSC_ETYPE if type is invalid.

cosc_write_values()

COSC_API cosc_int32 cosc_write_values	(	void *	buffer,
		cosc_int32	size,
		const char *	types,
		cosc_int32	types_n,
		const union cosc_value *	values,
		cosc_int32	values_n,
		cosc_int32 *	value_count )

Write OSC values.

Parameters

[out]	buffer	If non-NULL store the OSC data here, if NULL then no bytes are stored.
	size	Store at most this many bytes to buffer.
	types	The types, the starting comma may be omitted.
	types_n	Read at most this many bytes from types.
	values	The values.
	values_n	Read at most this many members from values.
[out]	value_count	If non-NULL the number of written values is stored here.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Note

If values_n is less than the values specified by typetag the remaining values are written as zero/empty.

• COSC_EOVERRUN if buffer is non-NULL and size is too small.
• COSC_ESIZEMAX if size > COSC_SIZE_MAX.
• COSC_ETYPE if on of the types is invalid.

cosc_writer_blob()

COSC_API cosc_int32 cosc_writer_blob	(	struct cosc_serial *	serial,
		const void *	value,
		cosc_int32	value_n )

Write a blob.

Parameters

serial	The serial.
value	The blob data.
value_n	The byte size of the blob data.

Returns

The number of written bytes or a negative error code on failure.

Note

To write raw bytes to a started blob level use cosc_writer_bytes().

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_writer_bytes()

COSC_API cosc_int32 cosc_writer_bytes	(	struct cosc_serial *	serial,
		const void *	value,
		cosc_int32	value_n )

Write bytes to a started blob level.

Parameters

serial	The serial.
value	The bytes or NULL to zero the bytes.
value_n	The number of bytes to write.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.

cosc_writer_char()

COSC_API cosc_int32 cosc_writer_char	(	struct cosc_serial *	serial,
		cosc_int32	value )

Write an ASCII character.

Parameters

serial	The serial.
value	The value.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_writer_end_blob()

COSC_API cosc_int32 cosc_writer_end_blob

(

struct cosc_serial *

serial

)

End a blob level.

Parameters

serial

The serial.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer, this can happen if the blob needs to add pad bytes.
• COSC_ELEVELTYPE if the current level is not a blob.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

Examples

serial.c.

cosc_writer_end_bundle()

COSC_API cosc_int32 cosc_writer_end_bundle

(

struct cosc_serial *

serial

)

End a bundle level.

Parameters

serial

The serial.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_ELEVELTYPE if the current level is not a bundle.

Examples

serial.c.

cosc_writer_end_message()

COSC_API cosc_int32 cosc_writer_end_message

(

struct cosc_serial *

serial

)

End a message level.

Parameters

serial

The serial.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_ELEVELTYPE if the current level is not a message.

Examples

serial.c.

cosc_writer_float32()

COSC_API cosc_int32 cosc_writer_float32	(	struct cosc_serial *	serial,
		cosc_float32	value )

Write a 32-bit float.

Parameters

serial	The serial.
value	The value.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

Examples

serial.c.

cosc_writer_float64()

COSC_API cosc_int32 cosc_writer_float64	(	struct cosc_serial *	serial,
		cosc_float64	value )

Write a 64-bit float.

Parameters

serial	The serial.
value	The value.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_writer_int32()

COSC_API cosc_int32 cosc_writer_int32	(	struct cosc_serial *	serial,
		cosc_int32	value )

Write a signed 32-bit integer.

Parameters

serial	The serial.
value	The value.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

Examples

serial.c.

cosc_writer_int64()

COSC_API cosc_int32 cosc_writer_int64	(	struct cosc_serial *	serial,
		cosc_int64	value )

Write a signed 64-bit integer.

Parameters

serial	The serial.
value	The value.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_writer_message()

COSC_API cosc_int32 cosc_writer_message	(	struct cosc_serial *	serial,
		const struct cosc_message *	message,
		cosc_int32 *	value_count )

Write an OSC message.

Parameters

	serial	The serial.
	message	The message or NULL for an empty message.
[out]	value_count	If non-NULL the number of written values is stored here.

Returns

The number of written bytes if buffer is non-NULL, the required size if buffer is NULL or a negative error code if the operation fails.

Note

The message address is NOT validated.

If message.values_n is less than the values specified in message.typetag the rest of the values will be written as zero/empty.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

• COSC_EOVERRUN if buffer is non-NULL and size is too small.
• COSC_ESIZEMAX if size > COSC_SIZE_MAX.
• COSC_ETYPE if message typetag is invalid.
• COSC_EPSIZE if size > 0 and is invalid or too small.

cosc_writer_midi()

COSC_API cosc_int32 cosc_writer_midi	(	struct cosc_serial *	serial,
		const unsigned char	value[4] )

Write a MIDI message.

Parameters

serial	The serial.
value	The value or NULL for all zeroes.

Returns

The number of written bytes or a negative error code on failure.

Note

Normally the fourth byte isn't used in MIDI.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_writer_repeat()

COSC_API cosc_int32 cosc_writer_repeat

(

struct cosc_serial *

serial

)

Repeat typetag from the beginning of an array start, where the array starts with a '['.

Parameters

serial

The serial.

Returns

0 on success or a negative error code on failure.

Note

If cosc was built with COSC_NOARRAY defined this function does nothing and returns 0 or COSC_EINVAL.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE the current message typetag type is not ']' or if the typetag has no valid array start.

cosc_writer_setup()

COSC_API void cosc_writer_setup	(	struct cosc_serial *	serial,
		void *	buffer,
		cosc_int32	buffer_size,
		struct cosc_level *	levels,
		cosc_int32	level_max,
		cosc_uint32	flags )

Setup a serial for writing.

Parameters

[out]	serial	The serial.
	buffer	A writable buffer, must not be NULL.
	buffer_size	The size of the buffer.
	levels	Provided levels, must point to an array of levels with at least one member.
	level_max	The number of provided levels, must be at least 1.
	flags	Serial flags, see COSC_SERIAL_* macros.

See also

COSC_SERIAL_PSIZE.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Examples

serial.c.

cosc_writer_skip()

COSC_API cosc_int32 cosc_writer_skip

(

struct cosc_serial *

serial

)

Skip a value, if the value has payload it will be zeroes.

Parameters

serial

The serial.

Returns

The number of written bytes or a negative error code on failure or 0 if there are no more types in the message typetag.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_writer_start_blob()

COSC_API cosc_int32 cosc_writer_start_blob

(

struct cosc_serial *

serial

)

Start a new blob level.

Parameters

serial

The serial.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Note

To write raw bytes to a started blob level use cosc_writer_bytes().

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELMAX the maximum number of levels is reached.
• COSC_ELEVELTYPE if the current level does not accept a blob.

Examples

serial.c.

cosc_writer_start_bundle()

COSC_API cosc_int32 cosc_writer_start_bundle	(	struct cosc_serial *	serial,
		cosc_uint64	timetag )

Start a new bundle level.

Parameters

serial	The serial.
timetag	A timetag for the bundle.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELMAX the maximum number of levels is reached.
• COSC_ELEVELTYPE if the current level does not accept a bundle.

Examples

serial.c.

cosc_writer_start_message()

COSC_API cosc_int32 cosc_writer_start_message	(	struct cosc_serial *	serial,
		const char *	address,
		cosc_int32	address_n,
		const char *	typetag,
		cosc_int32	typetag_n )

Start a new message level.

Parameters

serial	The serial.
address	The address.
address_n	Read at most this many bytes from address.
typetag	The typetag.
typetag_n	Read at most this many bytes from typetag.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELMAX the maximum number of levels is reached.
• COSC_ELEVELTYPE if the current level does not accept a message.

Examples

serial.c.

cosc_writer_string()

COSC_API cosc_int32 cosc_writer_string	(	struct cosc_serial *	serial,
		const char *	value,
		cosc_int32	value_n,
		cosc_int32 *	length )

Write a string.

Parameters

	serial	The serial.
	value	The value.
	value_n	Read at most this many bytes from value.
[out]	length	If non-NULL and the function does not return a negative error code the length, excluding the zero terminator, of the string is stored here.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_writer_uint32()

COSC_API cosc_int32 cosc_writer_uint32	(	struct cosc_serial *	serial,
		cosc_uint32	value )

Write an unsigned 32-bit integer.

Parameters

serial	The serial.
value	The value.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_writer_uint64()

COSC_API cosc_int32 cosc_writer_uint64	(	struct cosc_serial *	serial,
		cosc_uint64	value )

Write an unsigned 64-bit integer.

Parameters

serial	The serial.
value	The value.

Returns

The number of written bytes or a negative error code on failure.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.

cosc_writer_value()

COSC_API cosc_int32 cosc_writer_value	(	struct cosc_serial *	serial,
		cosc_int32	type,
		const union cosc_value *	value )

Write a value.

Parameters

serial	The serial.
type	The value typetag type.
value	The value or NULL for zero/empty.

Returns

The number of written bytes or a negative error code on failure.

Note

Normally the fourth byte isn't used in MIDI.

Remarks

This function is not available if COSC_NOWRITER was defined when compiling.

Error codes:

• COSC_EINVAL if the serial was setup as a reader.
• COSC_EOVERRUN if the operation will overrun the buffer.
• COSC_ELEVELTYPE if the current level does not accept the value.
• COSC_EMSGTYPE if trying to add the value to a message where the value type does not match the typetag.
• COSC_ETYPE if type is invalid.