Devices

Typedefs
typedef void	mapper_device_link_handler(mapper_device dev, mapper_link link, mapper_record_event event)
typedef void	mapper_device_map_handler(mapper_device dev, mapper_map map, mapper_record_event event)

Functions
void	mapper_device_set_link_callback (mapper_device dev, mapper_device_link_handler *handler)
void	mapper_device_set_map_callback (mapper_device dev, mapper_device_map_handler *handler)
mapper_device	mapper_device_new (const char *name_prefix, int port, mapper_network net)
void	mapper_device_free (mapper_device dev)
mapper_id	mapper_device_generate_unique_id (mapper_device dev)
mapper_network	mapper_device_network (mapper_device dev)
void	mapper_device_set_user_data (mapper_device dev, const void *user_data)
void *	mapper_device_user_data (mapper_device dev)
mapper_signal	mapper_device_add_signal (mapper_device dev, mapper_direction dir, int num_instances, const char *name, int length, char type, const char *unit, const void *minimum, const void *maximum, mapper_signal_update_handler *handler, const void *user_data)
mapper_signal	mapper_device_add_input_signal (mapper_device dev, const char *name, int length, char type, const char *unit, const void *minimum, const void *maximum, mapper_signal_update_handler *handler, const void *user_data)
mapper_signal	mapper_device_add_output_signal (mapper_device dev, const char *name, int length, char type, const char *unit, const void *minimum, const void *maximum)
int	mapper_device_num_signals (mapper_device dev, mapper_direction dir)
mapper_signal *	mapper_device_signals (mapper_device dev, mapper_direction dir)
mapper_signal	mapper_device_signal_by_id (mapper_device dev, mapper_id id)
mapper_signal	mapper_device_signal_by_name (mapper_device dev, const char *sig_name)
mapper_signal_group	mapper_device_add_signal_group (mapper_device dev)
void	mapper_device_remove_signal_group (mapper_device dev, mapper_signal_group group)
const char *	mapper_device_description (mapper_device dev)
int	mapper_device_num_links (mapper_device dev, mapper_direction dir)
mapper_link *	mapper_device_links (mapper_device dev, mapper_direction dir)
mapper_link	mapper_device_link_by_remote_device (mapper_device dev, mapper_device remote_dev)
int	mapper_device_num_maps (mapper_device dev, mapper_direction dir)
mapper_map *	mapper_device_maps (mapper_device dev, mapper_direction dir)
int	mapper_device_num_properties (mapper_device dev)
int	mapper_device_property (mapper_device dev, const char *name, int *length, char *type, const void **value)
int	mapper_device_property_index (mapper_device dev, unsigned int index, const char **name, int *length, char *type, const void **value)
void	mapper_device_set_description (mapper_device dev, const char *description)
int	mapper_device_set_property (mapper_device dev, const char *name, int length, char type, const void *value, int publish)
void	mapper_device_clear_staged_properties (mapper_device dev)
void	mapper_device_push (mapper_device dev)
int	mapper_device_remove_property (mapper_device dev, const char *name)
int	mapper_device_poll (mapper_device dev, int block_ms)
int	mapper_device_num_fds (mapper_device dev)
int	mapper_device_fds (mapper_device dev, int *fds, int num)
void	mapper_device_service_fd (mapper_device dev, int fd)
int	mapper_device_ready (mapper_device dev)
void	mapper_device_synced (mapper_device dev, mapper_timetag_t *tt)
int	mapper_device_version (mapper_device dev)
const char *	mapper_device_name (mapper_device dev)
const char *	mapper_device_host (mapper_device dev)
mapper_id	mapper_device_id (mapper_device dev)
int	mapper_device_is_local (mapper_device dev)
unsigned int	mapper_device_port (mapper_device dev)
unsigned int	mapper_device_ordinal (mapper_device dev)
void	mapper_device_start_queue (mapper_device dev, mapper_timetag_t tt)
void	mapper_device_send_queue (mapper_device dev, mapper_timetag_t tt)
lo_server	mapper_device_lo_server_udp (mapper_device dev)
lo_server	mapper_device_lo_server_tcp (mapper_device dev)
mapper_database	mapper_device_database (mapper_device dev)
mapper_device *	mapper_device_query_union (mapper_device *query1, mapper_device *query2)
mapper_device *	mapper_device_query_intersection (mapper_device *query1, mapper_device *query2)
mapper_device *	mapper_device_query_difference (mapper_device *query1, mapper_device *query2)
mapper_device	mapper_device_query_index (mapper_device *query, int index)
mapper_device *	mapper_device_query_next (mapper_device *query)
mapper_device *	mapper_device_query_copy (mapper_device *query)
void	mapper_device_query_done (mapper_device *query)
void	mapper_device_print (mapper_device dev)

Detailed Description

A device is an entity on the network which has input and/or output signals. The mapper_device is the primary interface through which a program uses libmapper. A device must have a name, to which a unique ordinal is subsequently appended. It can also be given other user-specified metadata. Devices signals can be connected, which is accomplished by requests from an external GUI.

Typedef Documentation

mapper_device_link_handler

typedef void mapper_device_link_handler(mapper_device dev, mapper_link link, mapper_record_event event)

A callback function prototype for when a link is added, updated, or removed from a given device. Such a function is passed in to mapper_device_set_link_callback().

Parameters

dev	The device that registered this callback.
link	The link record.
event	A value of mapper_record_event indicating what is happening to the link record.

mapper_device_map_handler

typedef void mapper_device_map_handler(mapper_device dev, mapper_map map, mapper_record_event event)

A callback function prototype for when a map is added, updated, or removed from a given device. Such a function is passed in to mapper_device_set_map_callback().

Parameters

dev	The device that registered this callback.
map	The map record.
event	A value of mapper_record_event indicating what is happening to the map record.

Function Documentation

mapper_device_add_input_signal()

mapper_signal mapper_device_add_input_signal	(	mapper_device	dev,
		const char *	name,
		int	length,
		char	type,
		const char *	unit,
		const void *	minimum,
		const void *	maximum,
		mapper_signal_update_handler *	handler,
		const void *	user_data
	)

Add an input signal to a mapper device. Values and strings pointed to by this call (except user_data) will be copied. For minimum and maximum, actual type must correspond to 'type' (if type='i', then int*, etc).

Parameters

dev	The device to add a signal to.
name	The name of the signal.
length	The length of the signal vector, or 1 for a scalar.
type	The type fo the signal value.
unit	The unit of the signal, or 0 for none.
minimum	Pointer to a minimum value, or 0 for none.
maximum	Pointer to a maximum value, or 0 for none.
handler	Function to be called when the value of the signal is updated.
user_data	User context pointer to be passed to handler.

Returns

The new signal.

mapper_device_add_output_signal()

mapper_signal mapper_device_add_output_signal	(	mapper_device	dev,
		const char *	name,
		int	length,
		char	type,
		const char *	unit,
		const void *	minimum,
		const void *	maximum
	)

Add an output signal to a mapper device. Values and strings pointed to by this call (except user_data) will be copied. For minimum and maximum, actual type must correspond to 'type' (if type='i', then int*, etc).

Parameters

dev	The device to add a signal to.
name	The name of the signal.
length	The length of the signal vector, or 1 for a scalar.
type	The type fo the signal value.
unit	The unit of the signal, or 0 for none.
minimum	Pointer to a minimum value, or 0 for none.
maximum	Pointer to a maximum value, or 0 for none.

Returns

The new signal.

mapper_device_add_signal()

mapper_signal mapper_device_add_signal	(	mapper_device	dev,
		mapper_direction	dir,
		int	num_instances,
		const char *	name,
		int	length,
		char	type,
		const char *	unit,
		const void *	minimum,
		const void *	maximum,
		mapper_signal_update_handler *	handler,
		const void *	user_data
	)

Add a signal to a mapper device. Values and strings pointed to by this call (except user_data) will be copied. For minimum and maximum, actual type must correspond to 'type' (if type='i', then int*, etc).

Parameters

dev	The device to add a signal to.
dir	The signal direction.
num_instances	The number of signal instances.
name	The name of the signal.
length	The length of the signal vector, or 1 for a scalar.
type	The type fo the signal value.
unit	The unit of the signal, or 0 for none.
minimum	Pointer to a minimum value, or 0 for none.
maximum	Pointer to a maximum value, or 0 for none.
handler	Function to be called when the value of the signal is updated.
user_data	User context pointer to be passed to handler.

Returns

The new signal.

mapper_device_add_signal_group()

mapper_signal_group mapper_device_add_signal_group

(

mapper_device

dev

)

Create a new signal group, used for coordinating signal instances across related signals.

Parameters

dev	The device.

Returns

A new signal group identifier. Use the function mapper_signal_set_group() to add or remove signals from a group.

mapper_device_clear_staged_properties()

void mapper_device_clear_staged_properties

(

mapper_device

dev

)

Clear any staged property changes.

Parameters

dev	The device to operate on.

mapper_device_database()

mapper_database mapper_device_database

(

mapper_device

dev

)

Return the internal mapper_database structure used by a device.

Parameters

dev	The device structure to query.

Returns

The mapper_database used by this device.

mapper_device_description()

const char* mapper_device_description

(

mapper_device

dev

)

Get the description for a specific device.

Parameters

dev	The device to check.

Returns

The device description if it is defined, or NULL.

mapper_device_fds()

int mapper_device_fds	(	mapper_device	dev,
		int *	fds,
		int	num
	)

Write the list of file descriptors for this device to the provided array. Up to num file descriptors will be written. These file descriptors can be used as input for the read array of select or poll, for example.

Parameters

dev	The device to get file descriptors for.
fds	Memory to receive file descriptors.
num	The number of file descriptors pointed to by fds.

Returns

The number of file descriptors actually written to fds.

mapper_device_free()

void mapper_device_free

(

mapper_device

dev

)

Free resources used by a mapper device.

Parameters

dev	The device to use.

mapper_device_generate_unique_id()

mapper_id mapper_device_generate_unique_id

(

mapper_device

dev

)

Return a unique id associated with a given device.

Parameters

dev	The device to use.

Returns

A new unique id.

mapper_device_host()

const char* mapper_device_host

(

mapper_device

dev

)

Return a string indicating the device's host, if it is registered. The returned string must not be externally modified.

Parameters

dev	The device to query.

Returns

String containing the device's host, or zero if it is not available.

mapper_device_id()

mapper_id mapper_device_id

(

mapper_device

dev

)

Return the unique id allocated to this device by the mapper network.

Parameters

dev	The device to query.

Returns

The device's id, or zero if it is not available.

mapper_device_is_local()

int mapper_device_is_local

(

mapper_device

dev

)

Indicate whether this device is local.

Parameters

dev	The device to query.

Returns

1 if the device is local, 0 otherwise.

mapper_device_link_by_remote_device()

mapper_link mapper_device_link_by_remote_device	(	mapper_device	dev,
		mapper_device	remote_dev
	)

Find information for a registered link.

Parameters

dev	Device record to query.
remote_dev	Remote device.

Returns

Information about the link, or zero if not found.

mapper_device_links()

mapper_link* mapper_device_links	(	mapper_device	dev,
		mapper_direction	dir
	)

Return the list of network links associated with a given device.

Parameters

dev	Device record query.
dir	The direction of the link relative to the given device.

Returns

A double-pointer to the first item in the list of results. Use mapper_link_query_next() to iterate.

mapper_device_lo_server_tcp()

lo_server mapper_device_lo_server_tcp

(

mapper_device

dev

)

Get access to the device's underlying TCP lo_server.

Parameters

dev	The device to use.

Returns

The liblo server used by this device.

mapper_device_lo_server_udp()

lo_server mapper_device_lo_server_udp

(

mapper_device

dev

)

Get access to the device's underlying UDP lo_server.

Parameters

dev	The device to use.

Returns

The liblo server used by this device.

mapper_device_maps()

mapper_map* mapper_device_maps	(	mapper_device	dev,
		mapper_direction	dir
	)

Return the list of maps associated with a given device.

Parameters

dev	Device record query.
dir	The direction of the map relative to the given device.

Returns

A double-pointer to the first item in the list of results. Use mapper_map_query_next() to iterate.

mapper_device_name()

const char* mapper_device_name

(

mapper_device

dev

)

Return a string indicating the device's full name, if it is registered. The returned string must not be externally modified.

Parameters

dev	The device to query.

Returns

String containing the device's full name, or zero if it is not available.

mapper_device_network()

mapper_network mapper_device_network

(

mapper_device

dev

)

Retrieve the networking structure from a device.

Parameters

dev	The device to use.

Returns

The device network data structure.

mapper_device_new()

mapper_device mapper_device_new	(	const char *	name_prefix,
		int	port,
		mapper_network	net
	)

Allocate and initialize a mapper device.

Parameters

name_prefix	A short descriptive string to identify the device. Must not contain spaces or the slash character '/'.
port	An optional port for starting the port allocation scheme.
net	A previously allocated network structure to use. If 0, one will be allocated for use with this device.

Returns

A newly allocated mapper device. Should be free using mapper_device_free().

mapper_device_num_fds()

int mapper_device_num_fds

(

mapper_device

dev

)

Return the number of file descriptors needed for this device. This can be used to allocated an appropriately-sized list for called to mapper_device_fds. Note that the number of descriptors needed can change throughout the life of a device, therefore this function should be called whenever the list of file descriptors is needed.

Parameters

dev	The device to count file descriptors for.

Returns

The number of file descriptors needed for the indicated device.

mapper_device_num_links()

int mapper_device_num_links	(	mapper_device	dev,
		mapper_direction	dir
	)

Return the number of network links associated with a specific device.

Parameters

dev	The device to check.
dir	The direction of the links relative to the given device.

Returns

The number of associated links.

mapper_device_num_maps()

int mapper_device_num_maps	(	mapper_device	dev,
		mapper_direction	dir
	)

Return the number of maps associated with a specific device.

Parameters

dev	The device to check.
dir	The direction of the maps relative to the given device.

Returns

The number of associated maps.

mapper_device_num_properties()

int mapper_device_num_properties

(

mapper_device

dev

)

Get the total number of properties for a specific device.

Parameters

dev	The device to check.

Returns

The number of properties.

mapper_device_num_signals()

int mapper_device_num_signals	(	mapper_device	dev,
		mapper_direction	dir
	)

Return the number of signals.

Parameters

dev	The device to query.
dir	The direction of the signals to count.

Returns

The number of signals.

mapper_device_ordinal()

unsigned int mapper_device_ordinal

(

mapper_device

dev

)

Return an allocated ordinal which is appended to this device's network name. In general the results of this function are not valid unless mapper_device_ready() returns non-zero.

Parameters

dev	The device to query.

Returns

A positive ordinal unique to this device (per name).

mapper_device_poll()

int mapper_device_poll	(	mapper_device	dev,
		int	block_ms
	)

Poll this device for new messages. Note, if you have multiple devices, the right thing to do is call this function for each of them with block_ms=0, and add your own sleep if necessary.

Parameters

dev	The device to check messages for.
block_ms	Number of milliseconds to block waiting for messages, or 0 for non-blocking behaviour.

Returns

The number of handled messages. May be zero if there was nothing to do.

mapper_device_port()

unsigned int mapper_device_port

(

mapper_device

dev

)

Return the port used by a device to receive signals, if available.

Parameters

dev	The device to query.

Returns

An integer indicating the device's port, or zero if it is not available.

mapper_device_print()

void mapper_device_print

(

mapper_device

dev

)

Helper to print the properties of a specific device.

Parameters

dev	The device to print.

mapper_device_property()

int mapper_device_property	(	mapper_device	dev,
		const char *	name,
		int *	length,
		char *	type,
		const void **	value
	)

Look up a device property by name.

Parameters

dev	The device record to check.
name	The name of the property to retrieve.
length	A pointer to a location to receive the vector length of the property value. (Required.)
type	A pointer to a location to receive the type of the property value. (Required.)
value	A pointer to a location to receive the address of the property's value. (Required.)

Returns

Zero if found, otherwise non-zero.

mapper_device_property_index()

int mapper_device_property_index	(	mapper_device	dev,
		unsigned int	index,
		const char **	name,
		int *	length,
		char *	type,
		const void **	value
	)

Look up a device property by index. To iterate all properties, call this function from index=0, increasing until it returns zero.

Parameters

dev	The device record to check.
index	Numerical index of a device property.
name	Address of a string pointer to receive the name of indexed property. May be zero.
length	A pointer to a location to receive the vector length of the property value. (Required.)
type	A pointer to a location to receive the type of the property value. (Required.)
value	A pointer to a location to receive the address of the property's value. (Required.)

Returns

Zero if found, otherwise non-zero.

mapper_device_push()

void mapper_device_push

(

mapper_device

dev

)

Push any property changes out to the network.

Parameters

dev	The device to operate on.

mapper_device_query_copy()

mapper_device* mapper_device_query_copy

(

mapper_device *

query

)

Copy a previously-constructed device query.

Parameters

query

The previous device record pointer.

Returns

A double-pointer to the copy of the list, or zero if none. Use mapper_device_query_next() to iterate.

mapper_device_query_difference()

mapper_device* mapper_device_query_difference	(	mapper_device *	query1,
		mapper_device *	query2
	)

Get the difference between two device queries (devices matching query1 but NOT query2).

Parameters

query1	The first device query.
query2	The second device query.

Returns

A double-pointer to the first item in a list of results. Use mapper_device_query_next() to iterate.

mapper_device_query_done()

void mapper_device_query_done

(

mapper_device *

query

)

Given a device record pointer returned from a previous device query, indicate that we are done iterating.

Parameters

query

The previous device record pointer.

mapper_device_query_index()

mapper_device mapper_device_query_index	(	mapper_device *	query,
		int	index
	)

Given a device record pointer returned from a previous device query, get an indexed item in the list.

Parameters

query	The previous device record pointer.
index	The index of the list element to retrieve.

Returns

A pointer to the device record, or zero if it doesn't exist.

mapper_device_query_intersection()

mapper_device* mapper_device_query_intersection	(	mapper_device *	query1,
		mapper_device *	query2
	)

Get the intersection of two device queries (devices matching query1 AND query2).

Parameters

query1	The first device query.
query2	The second device query.

Returns

A double-pointer to the first item in a list of results. Use mapper_device_query_next() to iterate.

mapper_device_query_next()

mapper_device* mapper_device_query_next

(

mapper_device *

query

)

Given a device record pointer returned from a previous device query, get the next item in the list.

Parameters

query

The previous device record pointer.

Returns

A double-pointer to the next device record in the list, or zero if no more devices.

mapper_device_query_union()

mapper_device* mapper_device_query_union	(	mapper_device *	query1,
		mapper_device *	query2
	)

Get the union of two device queries (devices matching query1 OR query2).

Parameters

query1	The first device query.
query2	The second device query.

Returns

A double-pointer to the first item in a list of results. Use mapper_device_query_next() to iterate.

mapper_device_ready()

int mapper_device_ready

(

mapper_device

dev

)

Detect whether a device is completely initialized.

Parameters

dev	The device to query.

Returns

Non-zero if device is completely initialized, i.e., has an allocated receiving port and unique network name. Zero otherwise.

mapper_device_remove_property()

int mapper_device_remove_property	(	mapper_device	dev,
		const char *	name
	)

Remove a property of a device.

Parameters

dev	The device to operate on.
name	The name of the property to remove.

Returns

1 if property has been removed, 0 otherwise.

mapper_device_remove_signal_group()

void mapper_device_remove_signal_group	(	mapper_device	dev,
		mapper_signal_group	group
	)

Remove a previously-defined multi-signal group.

Parameters

dev	The device containing the signal group to be removed.
group	The signal group identifier to be removed.

mapper_device_send_queue()

void mapper_device_send_queue	(	mapper_device	dev,
		mapper_timetag_t	tt
	)

Dispatch a time-tagged mapper queue.

Parameters

dev	The device to use.
tt	The timetag for an existing queue created with mapper_device_start_queue().

mapper_device_service_fd()

void mapper_device_service_fd	(	mapper_device	dev,
		int	fd
	)

If an external event indicates that a file descriptor for this device needs servicing, this function should be called.

Parameters

dev	The device that needs servicing.
fd	The file descriptor that needs servicing.

mapper_device_set_description()

void mapper_device_set_description	(	mapper_device	dev,
		const char *	description
	)

Set the description property for a specific local device.

Parameters

dev	The device to modify.
description	The description value to set.

mapper_device_set_link_callback()

void mapper_device_set_link_callback	(	mapper_device	dev,
		mapper_device_link_handler *	handler
	)

Set a function to be called when a link involving a device's local signals is established, modified or destroyed, indicated by the event parameter to the provided function.

Parameters

dev	The device to use.
handler	Function to be called when the local maps change.

mapper_device_set_map_callback()

void mapper_device_set_map_callback	(	mapper_device	dev,
		mapper_device_map_handler *	handler
	)

Set a function to be called when a map involving a device's local signals is established, modified or destroyed, indicated by the event parameter to the provided function.

Parameters

dev	The device to use.
handler	Function to be called when the local maps change.

mapper_device_set_property()

int mapper_device_set_property	(	mapper_device	dev,
		const char *	name,
		int	length,
		char	type,
		const void *	value,
		int	publish
	)

Set a property of a device. Can be used to provide arbitrary metadata. Value pointed to will be copied.

Parameters

dev	The device to operate on.
name	The name of the property to add.
length	The length of value array.
type	The property datatype.
value	An array of property values.
publish	1 to publish property to network, 0 for local-only.

Returns

1 if property has been changed, 0 otherwise.

mapper_device_set_user_data()

void mapper_device_set_user_data	(	mapper_device	dev,
		const void *	user_data
	)

Associate a device with an arbitrary pointer.

Parameters

dev	The device to operate on.
user_data	A pointer to user data to be associated.

mapper_device_signal_by_id()

mapper_signal mapper_device_signal_by_id	(	mapper_device	dev,
		mapper_id	id
	)

Find information for a registered signal.

Parameters

dev	The device to query.
id	Id of the signal to find in the database.

Returns

Information about the signal, or zero if not found.

mapper_device_signal_by_name()

mapper_signal mapper_device_signal_by_name	(	mapper_device	dev,
		const char *	sig_name
	)

Find information for a registered signal.

Parameters

dev	The device to query.
sig_name	Name of the signal to find in the database.

Returns

Information about the signal, or zero if not found.

mapper_device_signals()

mapper_signal* mapper_device_signals	(	mapper_device	dev,
		mapper_direction	dir
	)

Return the list of signals for a given device.

Parameters

dev	The device to query.
dir	The direction of the signals to return.

Returns

A double-pointer to the first item in the list of results. Use mapper_signal_query_next() to iterate.

mapper_device_start_queue()

void mapper_device_start_queue	(	mapper_device	dev,
		mapper_timetag_t	tt
	)

Start a time-tagged mapper queue.

Parameters

dev	The device to use.
tt	A timetag to use for the updates bundled by this queue.

mapper_device_synced()

void mapper_device_synced	(	mapper_device	dev,
		mapper_timetag_t *	tt
	)

Recover a timetag specifying the last time a device made contact. If the device is local this will be the current time.

Parameters

dev	The device whose time we are asking for.
tt	A previously allocated timetag to initialize.

mapper_device_user_data()

void* mapper_device_user_data

(

mapper_device

dev

)

Retrieve the arbitrary pointer associated with a device.

Parameters

dev	The device to operate on.

Returns

A pointer associated with this device.

mapper_device_version()

int mapper_device_version

(

mapper_device

dev

)

Return the current version number for a device.

Parameters

dev	The device to query.

Returns

The version number of the device.