contains basic utilities for reading, writing, and querying an OSC bundle More...

#include <inttypes.h>
#include <stdarg.h>
#include "ose.h"

Include dependency graph for ose_util.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	ose_pnbytes(n) (((n) + 4) & 0xfffffffc)
	Pad a number of bytes to the nearest multiple of 4.

#define	ose_addToInt32(b, offset, amt)
	Add a value to a 32-bit OSC integer in a bundle at an offset.

#define	ose_readSymbol(b, o) ose_readString((b), (o))

#define	ose_writeSymbol(b, o, s) ose_writeString((b), (o), (s))

#define	ose_readInt8(b, o) ose_readInt32((b), (o))

#define	ose_writeInt8(b, o, i) ose_writeInt32((b), (o), (i))

#define	ose_readUInt8(b, o) ose_readInt32((b), (o))

#define	ose_writeUInt8(b, o, i) ose_writeInt32((b), (o), (i))

Functions
int32_t	ose_pstrlen (const char *const s)
	Get the padded length of a string.

bool	ose_isAddressChar (char c)
	Determine whether a given character is a valid OSC address character.

bool	ose_isKnownTypetag (char typetag)
	Determine whether a given character is a typetag known to the system.

bool	ose_isStringType (char typetag)
	Determine whether a given character is a string type.

bool	ose_isIntegerType (char typetag)
	Determine whether a given character is an integer type.

bool	ose_isFloatType (char typetag)
	Determine whether a given character is a floating point type.

bool	ose_isNumericType (char typetag)
	Determine whether a given character is a numeric type.

bool	ose_isUnitType (char typetag)
	Determine whether a given character is a unit type.

bool	ose_isBoolType (char typetag)
	Determine whether a given character is either OSETT_TRUE or OSETT_FALSE.

bool	ose_isBundle (ose_bundle B)
	Determine whether the data pointed to contains a bundle or not.

bool	ose_blobContainsBundleAtOffset (ose_bundle B, const int32_t offset)

bool	ose_blobContainsBundle (ose_bundle B)

bool	ose_bundleIsEmpty (ose_bundle B)
	Determine whether a bundle contains any elements.

int32_t	ose_getBundleElemCount (ose_bundle B)
	Get the number of elements in a bundle.

int32_t	ose_getBundleElemElemCount (ose_bundle B, int32_t offset)
	Get the number of items in a bundle element.

bool	ose_bundleHasAtLeastNElems (ose_bundle B, int32_t n)
	Determine whether a bundle has a minimum number of elements.

char	ose_getBundleElemType (ose_bundle B, int32_t offset)
	Get the type of a bundle element.

char	ose_readByte (ose_bundle B, int32_t offset)
	Read a byte at an offset.

int32_t	ose_writeByte (ose_bundle B, int32_t offset, char i)
	Write a byte at an offset.

int32_t	ose_readInt32 (ose_bundle B, int32_t offset)
	Read a 32-bit int at an offset.

int32_t	ose_writeInt32 (ose_bundle B, int32_t offset, int32_t i)
	Write a 32-bit int at an offset.

float	ose_readFloat (ose_bundle B, int32_t offset)
	Read a 32-bit float at an offset.

int32_t	ose_writeFloat (ose_bundle B, int32_t offset, float f)
	Write a 32-bit float at an offset.

const char *	ose_readString (ose_bundle B, int32_t offset)
	Read a string at an offset.

int32_t	ose_getStringLen (ose_bundle B, int32_t offset)
	Get the length of a string at an offset.

int32_t	ose_getPaddedStringLen (ose_bundle B, int32_t offset)
	Get the padded length of a string at an offset.

int32_t	ose_writeString (ose_bundle B, int32_t offset, const char *const s, int32_t slen, int32_t slen_padded)
	Read a byte at an offset.

int32_t	ose_processEscapes (char *s)

const char *	ose_readBlob (ose_bundle B, int32_t offset)
	Read a blob at an offset.

int32_t	ose_readBlobSize (ose_bundle B, int32_t offset)
	Get the size of a blob.

int32_t	ose_getBlobPaddingForNBytes (int32_t n)
	Get the number of bytes required to pad a blob size to a multiple of 4 bytes.

int32_t	ose_getPaddedBlobSize (ose_bundle B, int32_t offset)
	Get the padded size of a blob at an offset.

const char *	ose_readBlobPayload (ose_bundle B, int32_t offset)
	Get a pointer to the payload of a blob at an offset.

int32_t	ose_writeBlob (ose_bundle B, int32_t offset, int32_t blobsize, const char *const blob)
	Write a blob at an offset.

double	ose_readDouble (ose_bundle B, int32_t offset)

int32_t	ose_writeDouble (ose_bundle B, int32_t offset, double f)

int16_t	ose_readInt16 (ose_bundle B, int32_t offset)

int32_t	ose_writeInt16 (ose_bundle B, int32_t offset, int16_t i)

uint16_t	ose_readUInt16 (ose_bundle B, int32_t offset)

int32_t	ose_writeUInt16 (ose_bundle B, int32_t offset, uint16_t i)

uint32_t	ose_readUInt32 (ose_bundle B, int32_t offset)

int32_t	ose_writeUInt32 (ose_bundle B, int32_t offset, uint32_t i)

int64_t	ose_readInt64 (ose_bundle B, int32_t offset)

int32_t	ose_writeInt64 (ose_bundle B, int32_t offset, int64_t i)

uint64_t	ose_readUInt64 (ose_bundle B, int32_t offset)

int32_t	ose_writeUInt64 (ose_bundle B, int32_t offset, uint64_t i)

struct ose_timetag	ose_readTimetag (ose_bundle B, int32_t offset)
	Read a timetag at an offset.

int32_t	ose_writeTimetag (ose_bundle B, int32_t offset, uint32_t sec, uint32_t fsec)
	Write a timetag at an offset.

double	ose_timetagToDouble (struct ose_timetag tt)
	Convert a timetag to a double-precision float.

struct ose_timetag	ose_doubleToTimetag (double d)
	Convert a double-precision float to a timetag.

void *const	ose_readAlignedPtr_impl (const char *const b)
	Read a pointer.

void *const	ose_readAlignedPtr (ose_bundle B, const int32_t offset)
	Read a pointer at an offset.

int32_t	ose_writeAlignedPtr_impl (char b, const void const ptr)
	Write a pointer.

int32_t	ose_writeAlignedPtr (ose_bundle B, const int32_t offset, const void *const ptr)
	Write a pointer at an offset.

void	ose_dropAtOffset (ose_bundle B, int32_t offset)
	Drop the last element in the bundle.

int32_t	ose_getLastBundleElemOffset (ose_bundle B)
	Get the offset in bytes of the last bundle element.

int32_t	ose_getBundleElemAddressOffset (ose_bundle B, int32_t elemoffset)
	Get the offset in bytes of the address of an element.

int32_t	ose_getBundleElemTTOffset (ose_bundle B, int32_t elemoffset)
	Get the offset in bytes of the typetag / timetag field of an element.

int32_t	ose_getBundleElemPayloadOffset (ose_bundle B, int32_t elemoffset)
	Get the offset in bytes of the payload of an element.

int32_t	ose_getFirstOffsetForMatch (ose_bundle B, const char *const addr)
	Get the offset of the first element whose address matches a string, using simple string comparison.

int32_t	ose_getFirstOffsetForPMatch (ose_bundle B, const char *const addr)
	Get the offset of the first element whose pattern matches a string, using OSC pattern matching.

int32_t	ose_getFirstOffsetForFullPMatch (ose_bundle B, const char *const addr)
	Get the offset of the first element whose address fully matches a string, using OSC pattern matching syntax.

int32_t	ose_getPayloadItemSize_hook (ose_bundle B, const char typetag, const int32_t msg_offset, const int32_t item_offset)

int32_t	ose_getPayloadItemSize (ose_bundle B, char typetag, int32_t msg_offset, int32_t item_offset)
	Calculate the size of a typed OSC item.

int32_t	ose_getPayloadItemLength_hook (ose_bundle B, const char typetag, const int32_t msg_offset, const int32_t item_offset)

int32_t	ose_getPayloadItemLength (ose_bundle B, char typetag, int32_t msg_offset, int32_t item_offset)
	Calculate the length of a typed OSC item.

void	ose_getNthPayloadItem (ose_bundle B, int32_t n, int32_t msg_offset, int32_t typetags_offset, int32_t num_typetags, int32_t last_typetag_offset, int32_t payload_offset, int32_t *last_payload_item_offset)
	Get the offset of the nth payload item of a message.

int32_t	ose_writeMessage (ose_bundle B, int32_t offset, const char *const address, int32_t addresslen, int32_t n,...)
	Write a message with arguments into a bundle at an offset.

int32_t	ose_vwriteMessage (ose_bundle B, int32_t offset, const char *const address, int32_t addresslen, int32_t n, va_list ap)
	Write a message with arguments into a bundle at an offset.

int32_t	ose_computeMessageSize (ose_bundle B, const char *const address, const int32_t addresslen, const int32_t n,...)
	Compute the size of a message.

int32_t	ose_vcomputeMessageSize (ose_bundle B, const char *const address, const int32_t addresslen, const int32_t n, va_list ap)
	Compute the size of a message.

int32_t	ose_printTypeof0 (ose_bundle B, const int32_t offset, char *buf, int32_t buflen)

int32_t	ose_printTypeof1 (ose_bundle B, const int32_t offset, char *buf, int32_t buflen)

int32_t	ose_printTypeof2 (ose_bundle B, const int32_t offset, char *buf, int32_t buflen)

int32_t	ose_fromString_hook (ose_bundle bundle, char typetag, const char *const str)

void	ose_registerType_hook (ose_bundle bundle, char typetag, const char const getPayloadItemLength_addr, ose_getPayloadItemLengthFn getPayloadItemLength, const char const getPayloadItemSize_addr, ose_getPayloadItemSizeFn getPayloadItemSize, const char const pprintPayloadItem_addr, ose_pprintPayloadItemFn pprintPayloadItem, const char const evalType_addr, void(evalType)(ose_bundle), const char const fromString_addr, void(*fromString)(ose_bundle))

int32_t	ose_validateBundle (const char *const bytes, const int32_t size)
	Check that `bytes` is a well formed OSC bundle, entirely within `size` bytes.

int32_t	ose_validateBundleInternal (const char *const bytes, const int32_t size)
	As ose_validateBundle(), for a single message with no bundle header.

int32_t	ose_validateMessage (const char *const bytes, const int32_t size)

Type checking
These render the shape of a bundle as an OSC-address-shaped string and match `pattern` against it with the ordinary OSC pattern matcher. They differ only in how deeply the shape is described. See TYPECHK-EXPLAINED.md for the address form and the pattern dialect.
int	ose_typechk0 (ose_bundle B, const char *const pattern)
	Check the type of a bundle itself.

int	ose_typechk1 (ose_bundle B, const char *const pattern)
	Check a bundle's element types.

int	ose_typechk2 (ose_bundle B, const char *const pattern)
	Check a bundle's element types and their contents.

int	ose_typechk0_ex (ose_bundle B, const char const pattern, int32_t elem, int32_t *item)
	As ose_typechk0, additionally reporting where the mismatch was.

int	ose_typechk1_ex (ose_bundle B, const char const pattern, int32_t elem, int32_t *item)
	As ose_typechk1, additionally reporting where the mismatch was.

int	ose_typechk2_ex (ose_bundle B, const char const pattern, int32_t elem, int32_t *item)
	As ose_typechk2, additionally reporting where the mismatch was.

Detailed Description

contains basic utilities for reading, writing, and querying an OSC bundle

The satisfaction of the preconditions stated in the documentation is the responsibility of the caller, and result in undefined behavior if they are not met.

Macro Definition Documentation

◆ ose_addToInt32

#define ose_addToInt32	(	b,
		offset,
		amt
	)

Value:

    ose_writeInt32((b),                                     \
                   (offset),                                \
                   ose_readInt32((b), (offset)) + (amt))

Add a value to a 32-bit OSC integer in a bundle at an offset.

Parameters

b	the bundle
offset	the offset
amt	the amount to add

Precondition: b or its underlying pointer must not be NULL.; o must be within b.; o must point to an OSC integer.

◆ ose_pnbytes

#define ose_pnbytes ( n ) (((n) + 4) & 0xfffffffc)

Pad a number of bytes to the nearest multiple of 4.

This function is suitable to pad OSC strings, as it will handle an empty string correctly by returning a pading of 4 bytes. It is not suitable for calculating the size of a blob, however, ose_getBlobPaddingForNBytes should be used instead.

Parameters

n	number of bytes to pad

Returns: the closest multiple of 4 greater than n

See also: ose_getBlobPaddingForNBytes

Function Documentation

◆ ose_bundleHasAtLeastNElems()

bool ose_bundleHasAtLeastNElems	(	ose_bundle	B,
		int32_t	n
	)

Determine whether a bundle has a minimum number of elements.

Parameters

B	the bundle
n	the minimum number of elements

Return values

true
false

Precondition: n must be non-zero.

◆ ose_bundleIsEmpty()

bool ose_bundleIsEmpty ( ose_bundle B )

Determine whether a bundle contains any elements.

Parameters

B	the bundle

Return values

true
false

Precondition: B or its underlying pointer must not be NULL.

◆ ose_computeMessageSize()

int32_t ose_computeMessageSize	(	ose_bundle	B,
		const char *const	address,
		const int32_t	addresslen,
		const int32_t	n,
			...
	)

Compute the size of a message.

This function computes the number of bytes a message written by ose_writeMessage will require, including the 4-byte size of the message.

See also: ose_writeMessage

◆ ose_doubleToTimetag()

struct ose_timetag ose_doubleToTimetag ( double d )

Convert a double-precision float to a timetag.

Parameters

d the float

See also: ose_timetagToDouble

◆ ose_dropAtOffset()

void ose_dropAtOffset	(	ose_bundle	B,
		int32_t	offset
	)

Drop the last element in the bundle.

The offset passed to this function must be that of the last element in the bundle.

Parameters

B	The bundle.
offset	the offset of the last element in bytes from the beginning of the bundle.

Precondition: B must not be empty.; offset must be within B.; offset must point to a valid bundle element within B.; offset must point to the LAST element. This is the one that is easy to miss: the function is not "drop the element at this offset", and passing the offset of a middle element is not a slower path but a wrong one.

Postcondition: On violation, sets errno to OSE_ERR_RANGE and leaves B untouched. Before this was checked, a middle offset memset a hole into the bundle and shrank the size, which left every element after the hole unreachable – silently, in any build with asserts compiled out.

◆ ose_getBlobPaddingForNBytes()

int32_t ose_getBlobPaddingForNBytes ( int32_t n )

Get the number of bytes required to pad a blob size to a multiple of 4 bytes.

Parameters

n	number of bytes in the blob

Returns: the number of additional bytes required for n to be a multiple of 4

Precondition: n must be non-negative.

Note: This function behaves differently from ose_pnbytes in that it will return 0 for a blob size of 0.

◆ ose_getBundleElemAddressOffset()

int32_t ose_getBundleElemAddressOffset	(	ose_bundle	B,
		int32_t	elemoffset
	)

Get the offset in bytes of the address of an element.

This function returns the offset in bytes of the address of a message or a bundle (a bundle's address is always \#bundle).

Parameters

B	the bundle
elemoffset	the offset of the element

Returns: elemoffset + 4

Precondition: B must not be empty.; elemoffset + 4 must be within B

◆ ose_getBundleElemCount()

int32_t ose_getBundleElemCount ( ose_bundle B )

Get the number of elements in a bundle.

Parameters

B	the bundle

Returns: the number of elements in B

Precondition: B or its underlying pointer must not be NULL.

◆ ose_getBundleElemElemCount()

int32_t ose_getBundleElemElemCount	(	ose_bundle	B,
		int32_t	offset
	)

Get the number of items in a bundle element.

Parameters

B	the bundle
offset	the offset of the bundle element in bytes from the beginning of `B`

Returns: the number of items in the bundle element

Precondition: B must not be empty.; offset must point to a valid bundle element in B.

◆ ose_getBundleElemPayloadOffset()

int32_t ose_getBundleElemPayloadOffset	(	ose_bundle	B,
		int32_t	elemoffset
	)

Get the offset in bytes of the payload of an element.

The payload of a bundle begins with the first bundle element it contains, and with a message, it is just after the typetag section.

Parameters

B	the bundle
elemoffset	the offset of the element

Returns: the offset of the payload section

Precondition: B must not be empty.; elemoffset + 4 must be within B

◆ ose_getBundleElemTTOffset()

int32_t ose_getBundleElemTTOffset	(	ose_bundle	B,
		int32_t	elemoffset
	)

Get the offset in bytes of the typetag / timetag field of an element.

This function returns the offset in bytes of the typetag section of a message, or the timetag section of a bundle.

Parameters

B	the bundle
elemoffset	the offset of the element

Returns: the offset of the typetag / timetag section

Precondition: B must not be empty.; elemoffset + 4 must be within B

◆ ose_getBundleElemType()

char ose_getBundleElemType	(	ose_bundle	B,
		int32_t	offset
	)

Get the type of a bundle element.

Parameters

B	the bundle
offset	the offset of the bundle element in bytes from the beginning of `B`

Return values

OSETT_MESSAGE	if the element is a message
OSETT_BUNDLE	if the element is a bundle

Precondition: B must not be empty.; offset must point to a valid bundle element in B.

◆ ose_getFirstOffsetForFullPMatch()

int32_t ose_getFirstOffsetForFullPMatch	(	ose_bundle	B,
		const char *const	addr
	)

Get the offset of the first element whose address fully matches a string, using OSC pattern matching syntax.

Parameters

B	bundle containing elements to test
addr	address to test against the elements of the bundle

Returns: the offset in bytes of the first match, or 0 if no match was found

Precondition: addr must not be NULL.

See also: ose_getFirstOffsetForMatch; ose_getFirstOffsetForPMatch

◆ ose_getFirstOffsetForMatch()

int32_t ose_getFirstOffsetForMatch	(	ose_bundle	B,
		const char *const	addr
	)

Get the offset of the first element whose address matches a string, using simple string comparison.

Parameters

B	bundle containing elements to test
addr	address to test against the elements of the bundle

Returns: the offset in bytes of the first match, or 0 if no match was found

Precondition: addr must not be NULL.

See also: ose_getFirstOffsetForPMatch; ose_getFirstOffsetForFullPMatch

◆ ose_getFirstOffsetForPMatch()

int32_t ose_getFirstOffsetForPMatch	(	ose_bundle	B,
		const char *const	addr
	)

Get the offset of the first element whose pattern matches a string, using OSC pattern matching.

Parameters

B	bundle containing elements to test
addr	address to test against the elements of the bundle

Returns: the offset in bytes of the first match, or 0 if no match was found

Precondition: addr must not be NULL.

Note: This function will report a match if only part of the address in the bundle matched addr, for example: the address "/foo" will match the pattern "/foo/bar" in the bundle.

See also: ose_getFirstOffsetForMatch; ose_getFirstOffsetForFullPMatch

◆ ose_getLastBundleElemOffset()

int32_t ose_getLastBundleElemOffset ( ose_bundle B )

Get the offset in bytes of the last bundle element.

This function returns the offset in bytes of the size field of the last bundle element. If the bundle is empty, the bundle header size (OSE_BUNDLE_HEADER_LEN) is returned.

Parameters

B	the bundle

Returns: the offset of the last element in bytes

Note: A return value equal to OSE_BUNDLE_HEADER_LEN is ambiguous—it can indicate that the bundle has either 0 or 1 elements.

◆ ose_getNthPayloadItem()

void ose_getNthPayloadItem	(	ose_bundle	B,
		int32_t	n,
		int32_t	msg_offset,
		int32_t *	typetags_offset,
		int32_t *	num_typetags,
		int32_t *	last_typetag_offset,
		int32_t *	payload_offset,
		int32_t *	last_payload_item_offset
	)

Get the offset of the nth payload item of a message.

This function gives the offset in bytes of the nth item of a message at offset o. In addition, it also provides the offset of the nth typetag, the total number of typetags, and the offsets of the first typetag and first payload item.

This function counts from the end furthest from the beginning of the element, with n=1 being the last item of the element.

The number of typetags includes the leading comma of the typetag string.

When n=1, lto and lpo contain the offsets of the typetag and payload items furthest from the beginning of the bundle element.

When n is equal to the number of typetags including the leading comma, to == lto and po == lpo.

Parameters

B	the bundle
n	the index of the item to get
msg_offset	the offset of the message `B`
typetags_offset	the offset of the first typetag (the comma)
num_typetags	the total number of typetags
last_typetag_offset	the offset of the last (nth) typetag
payload_offset	the offset of the first payload item
last_payload_item_offset	the offset of the last (nth) payload item

Precondition: B must not be empty.; msg_offset must be within B.; msg_offset must point to the size field of a valid message.; n must be within the range \([1,K]\) where \(K\) is the number of items in the message.; None of the pointer arguments may be NULL.

◆ ose_getPaddedBlobSize()

int32_t ose_getPaddedBlobSize	(	ose_bundle	B,
		int32_t	offset
	)

Get the padded size of a blob at an offset.

Parameters

B	the bundle
offset	the offset

Returns: the size of the blob including NULL padding

Precondition: B or its underlying pointer must not be NULL.; offset must be within B.; offset must point to the size field of a valid OSC blob in B.

◆ ose_getPaddedStringLen()

int32_t ose_getPaddedStringLen	(	ose_bundle	B,
		int32_t	offset
	)

Get the padded length of a string at an offset.

Parameters

b	the bundle
o	the offset

Returns: the length of the string including the NULL byte and any additional padding

Precondition: b or its underlying pointer must not be NULL.; o must be within b.; o must point to a NULL-terminated string.

◆ ose_getPayloadItemLength()

int32_t ose_getPayloadItemLength	(	ose_bundle	B,
		char	typetag,
		int32_t	msg_offset,
		int32_t	item_offset
	)

Calculate the length of a typed OSC item.

Returns the length of an OSC item, not including padding or NULL bytes, or size fields for types that require them.

String lengths do not include any NULL padding (a string of 4 bytes will return a value of 4), and blobs include do not include their size field and any NULL padding (a blob of size 0 will return a value of 0, and a blob of size 1 will return a value of 1.

Parameters

B	the bundle
typetag	the type tag of the data
msg_offset	the offset in bytes of the beginning of the message
item_offset	the offset in bytes from the beginning of the bundle to where the item is

Precondition: B must not be empty.; msg_offset must be within B.; msg_offset must point to the size field of a valid OSC message; item_offset must be within B.; item_offset must point to a valid item in a message of type typetag

◆ ose_getPayloadItemSize()

int32_t ose_getPayloadItemSize	(	ose_bundle	B,
		char	typetag,
		int32_t	msg_offset,
		int32_t	item_offset
	)

Calculate the size of a typed OSC item.

Returns the full size that a given item occupies, including any padding, size field, etc.

String sizes include any NULL padding (a string of 4 bytes will return a value of 8), and blobs include their size field and any NULL padding (a blob of size 0 will return a value of 4, and a blob of size 1 will return a value of 8.

Parameters

B	the bundle
typetag	the typetag of the data
msg_offset	the offset in bytes of the beginning of the message
item_offset	the offset in bytes from the beginning of the bundle to where the item is

Returns: the size of the item in bytes

Precondition: B must not be empty.; msg_offset must be within B.; msg_offset must point to the size field of a valid OSC message; item_offset must be within B.; item_offset must point to a valid item in a message of type typetag

◆ ose_getStringLen()

int32_t ose_getStringLen	(	ose_bundle	B,
		int32_t	offset
	)

Get the length of a string at an offset.

Parameters

b	the bundle
o	the offset

Returns: the length of the string not including the NULL byte

Precondition: b or its underlying pointer must not be NULL.; o must be within b.; o must point to a NULL-terminated string.

◆ ose_isAddressChar()

bool ose_isAddressChar ( char c )

Determine whether a given character is a valid OSC address character.

Parameters

c	the character to check

Return values

true
false

◆ ose_isBoolType()

bool ose_isBoolType ( char typetag )

Determine whether a given character is either OSETT_TRUE or OSETT_FALSE.

Parameters

typetag the character to check

Return values

true
false

◆ ose_isBundle()

bool ose_isBundle ( ose_bundle B )

Determine whether the data pointed to contains a bundle or not.

Parameters

B	the bundle

Return values

true
false

Note: The underlying pointer may be NULL, in which case this function will return false.

◆ ose_isFloatType()

bool ose_isFloatType ( char typetag )

Determine whether a given character is a floating point type.

Parameters

typetag the character to check

Return values

true
false

◆ ose_isIntegerType()

bool ose_isIntegerType ( char typetag )

Determine whether a given character is an integer type.

Parameters

typetag the character to check

Return values

true
false

◆ ose_isKnownTypetag()

bool ose_isKnownTypetag ( char typetag )

Determine whether a given character is a typetag known to the system.

Parameters

typetag the character to check

Return values

true
false

◆ ose_isNumericType()

bool ose_isNumericType ( char typetag )

Determine whether a given character is a numeric type.

Parameters

typetag the character to check

Return values

true
false

◆ ose_isStringType()

bool ose_isStringType ( char typetag )

Determine whether a given character is a string type.

Parameters

typetag the character to check

Return values

true
false

◆ ose_isUnitType()

bool ose_isUnitType ( char typetag )

Determine whether a given character is a unit type.

A unit type is a type that can only take on one value, such as OSETT_TRUE, OSETT_FALSE, OSETT_NIL, and OSETT_INFINITUM. These types have no data allocated in the data section of an OSC message.

Parameters

typetag the character to check

Return values

true
false

◆ ose_pstrlen()

int32_t ose_pstrlen ( const char *const s )

Get the padded length of a string.

Parameters

s	string to compute the length of

Returns: the length of s padded to a multiple of 4 bytes

Note: A string of length 0 will be padded to a length of 4 bytes.

◆ ose_readAlignedPtr()

void *const ose_readAlignedPtr	(	ose_bundle	B,
		const int32_t	offset
	)

Read a pointer at an offset.

An aligned pointer is a pointer that has been stored in a blob with the natural alignmet of the hardware. This function reads that pointer from the blob and returns it.

Parameters

B	the bundle
offset	the offset

Returns: the pointer

Precondition: B or its underlying pointer must not be NULL.; offset must be within B.; offset must point to a blob that has been writen using ose_writeAlignedPtr.

◆ ose_readAlignedPtr_impl()

void *const ose_readAlignedPtr_impl ( const char *const b )

Read a pointer.

An aligned pointer is a pointer that has been stored in a blob with the natural alignmet of the hardware. This function reads that pointer from the blob and returns it.

Parameters

b	the location of the aligned ptr to read

Returns: the pointer

See also: ose_readAlignedPtr

◆ ose_readBlob()

const char * ose_readBlob	(	ose_bundle	B,
		int32_t	offset
	)

Read a blob at an offset.

Parameters

b	the bundle
o	the offset

Returns: a pointer to the blob

Precondition: b or its underlying pointer must not be NULL.; o must be within b.

Note: The blob is not copied and must not be altered, unless you know what you are doing.; The pointer returned points to the size field of the blob. The blob contents are 4 bytes after that.

◆ ose_readBlobPayload()

const char * ose_readBlobPayload	(	ose_bundle	B,
		int32_t	offset
	)

Get a pointer to the payload of a blob at an offset.

The offset must point to the beginning of the blob—that is, the size field, not the payload. This function will return a pointer that is at offset + 4 bytes into B.

Parameters

B	the bundle
offset	the offset of the blob

Returns: a pointer to the payload of the blob

Precondition: B or its underlying pointer must not be NULL.; offset must be within B.; offset must point to the size field of a valid OSC blob in B.

◆ ose_readBlobSize()

int32_t ose_readBlobSize	(	ose_bundle	B,
		int32_t	offset
	)

Get the size of a blob.

Parameters

b	the bundle
o	the offset

Returns: the size of the blob

Precondition: b or its underlying pointer must not be NULL.; o must be within b.; o must point to the size field of a blob.

Note: The size returned is the size of the payload of the blob, i.e. it does not include the 4-byte size.

◆ ose_readByte()

char ose_readByte	(	ose_bundle	B,
		int32_t	offset
	)

Read a byte at an offset.

Parameters

b	the bundle
o	the offset

Returns: the value

Precondition: b or its underlying pointer must not be NULL.; o must be within b.

◆ ose_readFloat()

float ose_readFloat	(	ose_bundle	B,
		int32_t	offset
	)

Read a 32-bit float at an offset.

Parameters

B	the bundle
offset	the offset

Returns: the value

Precondition: B or its underlying pointer must not be NULL.; offset must be within B.; offset + 4 must be within B.

◆ ose_readInt32()

int32_t ose_readInt32	(	ose_bundle	B,
		int32_t	offset
	)

Read a 32-bit int at an offset.

Parameters

b	the bundle
o	the offset

Returns: the value

Precondition: b or its underlying pointer must not be NULL.; o must be within b.; o + 4 must be within b.

◆ ose_readString()

const char * ose_readString	(	ose_bundle	B,
		int32_t	offset
	)

Read a string at an offset.

Parameters

b	the bundle
o	the offset

Returns: a pointer to the string

Precondition: b or its underlying pointer must not be NULL.; o must be within b.

Note: The string is not copied and must not be altered, unless you know what you are doing.

◆ ose_readTimetag()

struct ose_timetag ose_readTimetag	(	ose_bundle	B,
		int32_t	offset
	)

Read a timetag at an offset.

Parameters

B	the bundle
offset	the offset

Returns: the timetag

Precondition: B or its underlying pointer must not be NULL.; offset must be within B.; offset must point to a valid OSC timetag.

See also: ose_timetag

◆ ose_timetagToDouble()

double ose_timetagToDouble ( struct ose_timetag tt )

Convert a timetag to a double-precision float.

Parameters

tt	the timetag

Note: This conversion necessarily loses information.

See also: ose_doubleToTimetag

◆ ose_typechk0()

int ose_typechk0	(	ose_bundle	B,
		const char *const	pattern
	)

Check the type of a bundle itself.

Renders only the outermost type – always /| for a bundle – and matches pattern against it. Use this to ask "is this a bundle at all?".

Unlike ose_typechk1 and ose_typechk2, a pattern that asks for more depth than this describes is not an error: it simply is not this function's business. That is what lets one pattern be handed to all three, each checking as much of it as it describes.

Parameters

B	the bundle to check
pattern	the pattern to match against the bundle's shape

Return values

OSE_ERR_NONE	the pattern matched, or asked for more depth than depth 0 describes
OSE_ERR_ELEM_TYPE	the bundle is not what the pattern asked for
OSE_ERR_ELEM_COUNT	the pattern and the bundle disagree about how many things there are
OSE_ERR_RANGE	the description does not fit the internal buffer
OSE_ERR_TYPE	the pattern itself is malformed

See also: ose_typechk0_ex, ose_typechk1, ose_typechk2

◆ ose_typechk0_ex()

int ose_typechk0_ex	(	ose_bundle	B,
		const char *const	pattern,
		int32_t *	elem,
		int32_t *	item
	)

As ose_typechk0, additionally reporting where the mismatch was.

Parameters

B	the bundle to check
pattern	the pattern to match against the bundle's shape
elem	receives the index of the offending element, or -1 when the fault is with the bundle itself. At depth 0 this is always -1. May be NULL.
item	receives the index within that element, or -1. At depth 0 this is always -1. May be NULL.

Returns: the same values as ose_typechk0

See also: ose_typechk0

◆ ose_typechk1()

int ose_typechk1	(	ose_bundle	B,
		const char *const	pattern
	)

Check a bundle's element types.

Renders the bundle and one character per element – /|/-- is a bundle holding two messages, /|/|- a bundle then a message. No item types appear at this depth.

Parameters

B	the bundle to check
pattern	the pattern to match against the bundle's shape

Return values

OSE_ERR_NONE	the pattern matched
OSE_ERR_ELEM_TYPE	an element is the wrong type
OSE_ERR_ELEM_COUNT	wrong number of elements
OSE_ERR_RANGE	the description does not fit the internal buffer
OSE_ERR_TYPE	the pattern itself is malformed

See also: ose_typechk1_ex, ose_typechk0, ose_typechk2

◆ ose_typechk1_ex()

int ose_typechk1_ex	(	ose_bundle	B,
		const char *const	pattern,
		int32_t *	elem,
		int32_t *	item
	)

As ose_typechk1, additionally reporting where the mismatch was.

Parameters

B	the bundle to check
pattern	the pattern to match against the bundle's shape
elem	receives the index of the offending element, or -1 when the fault is with the bundle itself. May be NULL.
item	receives -1; depth 1 describes no items. May be NULL.

Returns: the same values as ose_typechk1

See also: ose_typechk1

◆ ose_typechk2()

int ose_typechk2	(	ose_bundle	B,
		const char *const	pattern
	)

Check a bundle's element types and their contents.

Renders each element followed by its contents – /|/-/i/-/sf is a bundle holding a message of one int and a message of a string and a float.

Note: The segment after an element type means different things depending on that element: after - it is the message's item types, after | it is that sub-bundle's element types. Errors are reported accordingly.

Parameters

B	the bundle to check
pattern	the pattern to match against the bundle's shape

Return values

OSE_ERR_NONE	the pattern matched
OSE_ERR_ELEM_TYPE	an element is the wrong type
OSE_ERR_ITEM_TYPE	an item within a message is the wrong type
OSE_ERR_ELEM_COUNT	wrong number of elements
OSE_ERR_ITEM_COUNT	wrong number of items within a message
OSE_ERR_RANGE	the description does not fit the internal buffer
OSE_ERR_TYPE	the pattern itself is malformed

See also: ose_typechk2_ex, ose_typechk0, ose_typechk1

◆ ose_typechk2_ex()

int ose_typechk2_ex	(	ose_bundle	B,
		const char *const	pattern,
		int32_t *	elem,
		int32_t *	item
	)

As ose_typechk2, additionally reporting where the mismatch was.

This is what lets a caller say something more useful than "type error":

int32_t elem, item;
ose_typechk2_ex(B, "/|/-/i/-/sd", &elem, &item);
// -> OSE_ERR_ITEM_TYPE, elem = 1, item = 1
//    i.e. "the second item of the second message"

Parameters

B	the bundle to check
pattern	the pattern to match against the bundle's shape
elem	receives the index of the offending element, or -1 when the fault is with the bundle itself. May be NULL.
item	receives the index within that element – an item index for a message, a sub-element index for a bundle – or -1 when the fault is at element level. May be NULL.

Returns: the same values as ose_typechk2

See also: ose_typechk2

◆ ose_validateBundle()

int32_t ose_validateBundle	(	const char *const	bytes,
		const int32_t	size
	)

Check that bytes is a well formed OSC bundle, entirely within size bytes.

Every other function in libose assumes it has been handed a valid bundle. This one does not, and exists for the boundary where that assumption fails: bytes that came from somewhere else. Call it before anything else touches a packet.

Checks, recursively for nested bundles: the #bundle header, that every element size is non-negative, a multiple of four, and fits inside the buffer, that every address and typetag string is NUL terminated inside its message, that the payload implied by the typetags accounts for the message exactly, and that no element carries a type that may not be believed from outside.

Parameters

bytes	Untrusted bytes. May be unaligned.
size	Number of bytes available at `bytes`.

Return values

OSE_ERR_NONE	The bytes are a well formed bundle.
OSE_ERR_MALFORMED	Structure, bounds, or termination is wrong.
OSE_ERR_UNKNOWN_TYPETAG	A typetag libose does not know.
OSE_ERR_UNTRUSTED_TYPE	An aligned pointer, which would let the sender choose an address libose later calls as a function.

See also: ose_validateMessage; osevm_inputMessages

◆ ose_validateBundleInternal()

int32_t ose_validateBundleInternal	(	const char *const	bytes,
		const int32_t	size
	)

As ose_validateBundle(), for a single message with no bundle header.

Parameters

bytes	Untrusted bytes. May be unaligned.
size	Number of bytes available at `bytes`.

Return values

OSE_ERR_NONE	The bytes are a well formed message.
OSE_ERR_MALFORMED	Structure, bounds, or termination is wrong.
OSE_ERR_UNKNOWN_TYPETAG	A typetag libose does not know.
OSE_ERR_UNTRUSTED_TYPE	An aligned pointer.

See also: ose_validateBundle

As ose_validateBundle(), but for bytes that belong to a running VM rather than bytes that arrived from outside.

The two are different questions. ose_validateBundle() answers may these bytes be admitted, and so refuses OSE's own extensions: a bundle held as a message item (OSETT_BUNDLE_) and an aligned pointer, neither of which an OSC peer can legitimately send. This one answers is this structurally a bundle, which is what the VM's own state must satisfy at all times, and it accepts both.

Use it for checking internal state. Never for anything off the wire.

See also: ose_validateBundle

◆ ose_vcomputeMessageSize()

int32_t ose_vcomputeMessageSize	(	ose_bundle	B,
		const char *const	address,
		const int32_t	addresslen,
		const int32_t	n,
		va_list	ap
	)

Compute the size of a message.

See also: ose_computeMessageSize

Todo:: Implement default case for unknown type.

◆ ose_vwriteMessage()

int32_t ose_vwriteMessage	(	ose_bundle	B,
		const int32_t	offset,
		const char *const	address,
		const int32_t	addresslen,
		const int32_t	n,
		va_list	ap
	)

Write a message with arguments into a bundle at an offset.

See also: ose_writeMessage.

Todo:: Implement default case for unknown type.

◆ ose_writeAlignedPtr()

int32_t ose_writeAlignedPtr	(	ose_bundle	B,
		const int32_t	offset,
		const void *const	ptr
	)

Write a pointer at an offset.

This function writes the value of a pointer into a blob at a natural alignment boundary for the hardware.

Parameters

B	the bundle
offset	the offset
ptr	the pointer

Precondition: B or its underlying pointer must not be NULL.; offset must be within B.; offset + OSE_INTPTR2 must be within B.

◆ ose_writeAlignedPtr_impl()

int32_t ose_writeAlignedPtr_impl	(	char *	b,
		const void *const	ptr
	)

Write a pointer.

This function writes the value of a pointer into a blob at a natural alignment boundary for the hardware.

Parameters

b	the location where the pointer should be written
ptr	the pointer

See also: ose_writeAlignedPtr

◆ ose_writeBlob()

int32_t ose_writeBlob	(	ose_bundle	B,
		int32_t	offset,
		int32_t	blobsize,
		const char *const	blob
	)

Write a blob at an offset.

Parameters

B	the bundle
offset	the offset
blobsize	the blob size not including the 4 byte size
blob	the contents of the blob

Precondition: B or its underlying pointer must not be NULL.; offset must be within B.; blobsize must be non-negative.; offset + blobsize + 4 must be within B.

Note: blob may be NULL, in which case the number of bytes specified by blobsize will be set to 0.

◆ ose_writeByte()

int32_t ose_writeByte	(	ose_bundle	B,
		int32_t	offset,
		char	i
	)

Write a byte at an offset.

Parameters

b	the bundle
o	the offset
v	the value to write

Returns: the number of bytes written

Precondition: b or its underlying pointer must not be NULL.; o must be within b.

◆ ose_writeFloat()

int32_t ose_writeFloat	(	ose_bundle	B,
		int32_t	offset,
		float	f
	)

Write a 32-bit float at an offset.

Parameters

B	the bundle
offset	the offset
f	the value to write

Returns: the number of bytes written

Precondition: B or its underlying pointer must not be NULL.; offset must be within B.; offset + 4 must be within B.

◆ ose_writeInt32()

int32_t ose_writeInt32	(	ose_bundle	B,
		int32_t	offset,
		int32_t	i
	)

Write a 32-bit int at an offset.

Parameters

b	the bundle
o	the offset
v	the value to write

Returns: the number of bytes written

Precondition: b or its underlying pointer must not be NULL.; o must be within b.; o + 4 must be within b.

◆ ose_writeMessage()

int32_t ose_writeMessage	(	ose_bundle	B,
		int32_t	offset,
		const char *const	address,
		int32_t	addresslen,
		int32_t	n,
			...
	)

Write a message with arguments into a bundle at an offset.

Typetag	Number of Args	Arg Types	Arg Description
OSETT_INT32	1	`int32_t`
OSETT_FLOAT	1	`float`
OSETT_STRING	1	`char*`
OSETT_BLOB	2	`int32_t`, `char*`	blob size, blob data
OSETT_SYMBOL	1	`char*`
OSETT_DOUBLE	1	`double`
OSETT_INT8	1	`int8_t`
OSETT_UINT8	1	`uint8_t`
OSETT_UINT32	1	`uint_32`
OSETT_INT64	1	`int64_t`
OSETT_UINT64	1	`uint64_t`
OSETT_TIMETAG	2	`int32_t`, `int32_t`	seconds, fractions of a second
OSETT_TRUE	0
OSETT_FALSE	0
OSETT_NIL	0
OSETT_INFINITUM	0
user-defined	2	`int32_t`, `char*`	size, data

Parameters

B	the bundle
offset	the offset into the bundle where the message will be written
address	a C string that will be copied to the address of the message
addresslen	The length in bytes of the address, not ncluding the NULL byte
n	The number of OSC arguments for the message
...	The argument list, which consists of a type tag followed by 0 or more values, depending on the type (see table below).

Precondition: offset must be within B.; B must be large enough to accomodate the size of the message that will be written (see ose_computeMessageSize).; address must not be NULL.; addresslen must be non-negative.; n must be non-negative.; The variable length argument list must correspond to the table above.

See also: ose_computeMessageSize

Example:

ose_writeMessage(bundle, "/foo",
 OSE_BUNDLE_HEADER_LEN,
    4, 
    4,
    OSETT_INT32, 33,
    OSETT_FLOAT, 33.3,
    OSETT_STRING, THIRTY-THREE,
    OSETT_BLOB, 3, (char []){3, 3, 3});

◆ ose_writeString()

int32_t ose_writeString	(	ose_bundle	B,
		int32_t	offset,
		const char *const	s,
		int32_t	slen,
		int32_t	slen_padded
	)

Read a byte at an offset.

Parameters

b	the bundle
o	the offset
s	the string
slen	the string length in bytes, not including the NULL byte or any padding
slen_padded	the string length in bytes including NULL padding to a multiple of 4 bytes (see ose_pstrlen)

Precondition: b or its underlying pointer must not be NULL.; o must be within b.; s must not be NULL.; slen must be non-negative.; slen_padded must be greater than slen.

◆ ose_writeTimetag()

int32_t ose_writeTimetag	(	ose_bundle	B,
		int32_t	offset,
		uint32_t	sec,
		uint32_t	fsec
	)

Write a timetag at an offset.

Parameters

B	the bundle
offset	the offset
sec	the seconds portion of the timetag
fsec	the fractions of a second portion of the timetag

Precondition: B or its underlying pointer must not be NULL.; offset must be within B.; offset + 8 must be within B.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ ose_addToInt32

◆ ose_pnbytes

Function Documentation

◆ ose_bundleHasAtLeastNElems()

◆ ose_bundleIsEmpty()

◆ ose_computeMessageSize()

◆ ose_doubleToTimetag()

◆ ose_dropAtOffset()

◆ ose_getBlobPaddingForNBytes()

◆ ose_getBundleElemAddressOffset()

◆ ose_getBundleElemCount()

◆ ose_getBundleElemElemCount()

◆ ose_getBundleElemPayloadOffset()

◆ ose_getBundleElemTTOffset()

◆ ose_getBundleElemType()

◆ ose_getFirstOffsetForFullPMatch()

◆ ose_getFirstOffsetForMatch()

◆ ose_getFirstOffsetForPMatch()

◆ ose_getLastBundleElemOffset()

◆ ose_getNthPayloadItem()

◆ ose_getPaddedBlobSize()

◆ ose_getPaddedStringLen()

◆ ose_getPayloadItemLength()

◆ ose_getPayloadItemSize()

◆ ose_getStringLen()

◆ ose_isAddressChar()

◆ ose_isBoolType()

◆ ose_isBundle()

◆ ose_isFloatType()

◆ ose_isIntegerType()

◆ ose_isKnownTypetag()

◆ ose_isNumericType()

◆ ose_isStringType()

◆ ose_isUnitType()

◆ ose_pstrlen()

◆ ose_readAlignedPtr()

◆ ose_readAlignedPtr_impl()

◆ ose_readBlob()

◆ ose_readBlobPayload()

◆ ose_readBlobSize()

◆ ose_readByte()

◆ ose_readFloat()

◆ ose_readInt32()

◆ ose_readString()

◆ ose_readTimetag()

◆ ose_timetagToDouble()

◆ ose_typechk0()

◆ ose_typechk0_ex()

◆ ose_typechk1()

◆ ose_typechk1_ex()

◆ ose_typechk2()

◆ ose_typechk2_ex()

◆ ose_validateBundle()

◆ ose_validateBundleInternal()

◆ ose_vcomputeMessageSize()

◆ ose_vwriteMessage()

◆ ose_writeAlignedPtr()

◆ ose_writeAlignedPtr_impl()

◆ ose_writeBlob()

◆ ose_writeByte()

◆ ose_writeFloat()

◆ ose_writeInt32()

◆ ose_writeMessage()

◆ ose_writeString()

◆ ose_writeTimetag()