Graphs

Typedefs
typedef void	mpr_graph_handler(mpr_graph graph, mpr_obj object, const mpr_status event, const void *data)

Functions
mpr_graph	mpr_graph_new (int autosubscribe_types)
int	mpr_graph_set_interface (mpr_graph graph, const char *iface)
const char *	mpr_graph_get_interface (mpr_graph graph)
int	mpr_graph_set_address (mpr_graph graph, const char *group, int port)
const char *	mpr_graph_get_address (mpr_graph graph)
int	mpr_graph_poll (mpr_graph graph, int block_ms)
int	mpr_graph_start_polling (mpr_graph graph, int block_ms)
int	mpr_graph_stop_polling (mpr_graph graph)
void	mpr_graph_free (mpr_graph graph)
void	mpr_graph_subscribe (mpr_graph graph, mpr_dev device, int types, int timeout)
void	mpr_graph_unsubscribe (mpr_graph graph, mpr_dev device)
int	mpr_graph_add_cb (mpr_graph graph, mpr_graph_handler *handler, int types, const void *data)
void *	mpr_graph_remove_cb (mpr_graph graph, mpr_graph_handler *handler, const void *data)
mpr_list	mpr_graph_get_list (mpr_graph graph, int types)
mpr_obj	mpr_graph_get_obj (mpr_graph graph, mpr_id id, mpr_type type)

Detailed Description

Graphs are the primary interface through which a program may observe the distributed graph and store information about devices and signals that are present. Each Graph stores records of devices, signals, and maps, which can be queried. Changes to the graph will trigger any registered graph callbacks, as well as modify the object status of the graph. As with other libmapper objects, the volatile status bits can be reset by calling mpr_obj_reset_status().

Typedef Documentation

mpr_graph_handler

typedef void mpr_graph_handler(mpr_graph graph, mpr_obj object, const mpr_status event, const void *data)

A callback function prototype for when an object record is added or updated. Such a function is passed in to mpr_graph_add_cb().

Parameters

graph	The graph that registered this callback.
object	The object record.
event	A value of mpr_graph_evt indicating what is happening to the object record.
data	The user context pointer registered with this callback.

Function Documentation

mpr_graph_add_cb()

int mpr_graph_add_cb	(	mpr_graph	graph,
		mpr_graph_handler *	handler,
		int	types,
		const void *	data )

Register a callback for when an object record is added or updated in the graph.

Parameters

graph	The graph to query.
handler	Callback function.
types	Bitflags setting the type of information of interest. Can be a combination of mpr_type values.
data	A user-defined pointer to be passed to the callback for context.

Returns

One if a callback was added, otherwise zero.

mpr_graph_free()

void mpr_graph_free

(

mpr_graph

graph

)

Free a graph.

Parameters

graph

The graph to free.

mpr_graph_get_address()

const char * mpr_graph_get_address

(

mpr_graph

graph

)

Retrieve the multicast group currently in use. The returned value belongs to the graph and should not be modified or freed.

Parameters

graph

The graph structure to query.

Returns

A string specifying the multicast URL for bus communication with the distributed graph.

mpr_graph_get_interface()

const char * mpr_graph_get_interface

(

mpr_graph

graph

)

Return a string indicating the name of the network interface in use. The returned value belongs to the graph and should not be modified or freed.

Parameters

graph

The graph structure to query.

Returns

A string containing the name of the network interface.

mpr_graph_get_list()

mpr_list mpr_graph_get_list	(	mpr_graph	graph,
		int	types )

Return a list of objects.

Parameters

graph	The graph to query.
types	Bitflags setting the type of information of interest. Currently restricted to a single object type.

Returns

A list of results. Use mpr_list_get_next() to iterate.

mpr_graph_get_obj()

mpr_obj mpr_graph_get_obj	(	mpr_graph	graph,
		mpr_id	id,
		mpr_type	type )

Retrieve a specific object from the graph by id.

Parameters

graph	The graph to query.
type	The type of object to search for. Use MPR_OBJ if the type is not known.
id	Unique id identifying the object to find in the graph.

Returns

The object matching the query, or zero if not found.

mpr_graph_new()

mpr_graph mpr_graph_new

(

int

autosubscribe_types

)

Create a peer in the distributed graph.

Parameters

autosubscribe_types

A combination of mpr_type values controlling whether the graph should automatically subscribe to information about devices, signals and/or maps when it encounters a previously-unseen device.

Returns

The new graph.

mpr_graph_poll()

int mpr_graph_poll	(	mpr_graph	graph,
		int	block_ms )

Synchronize a local graph copy with the distributed graph.

Parameters

graph	The graph to update.
block_ms	Number of milliseconds to block waiting for messages, or 0 for non-blocking behaviour. Setting block_ms<0 will process all queued messages and then return immediately.

Returns

The number of handled messages.

mpr_graph_remove_cb()

void * mpr_graph_remove_cb	(	mpr_graph	graph,
		mpr_graph_handler *	handler,
		const void *	data )

Remove an object record callback from the graph service.

Parameters

graph	The graph to query.
handler	Callback function.
data	The user context pointer that was originally specified when adding the callback.

Returns

User data pointer associated with this callback (if any).

mpr_graph_set_address()

int mpr_graph_set_address	(	mpr_graph	graph,
		const char *	group,
		int	port )

Set the multicast group and port to use.

Parameters

graph	The graph structure to query.
group	A string specifying the multicast group for bus communication with the distributed graph.
port	The port to use for multicast communication.

Returns

Zero if successful, non-zero otherwise.

mpr_graph_set_interface()

int mpr_graph_set_interface	(	mpr_graph	graph,
		const char *	iface )

Specify network interface to use.

Parameters

graph	The graph structure to use.
iface	The name of the network interface to use.

Returns

Zero if successful, non-zero otherwise.

mpr_graph_start_polling()

int mpr_graph_start_polling	(	mpr_graph	graph,
		int	block_ms )

Start automatically synchronizing a local graph copy in a separate thread.

Parameters

graph	The graph to update.
block_ms	The number of milliseconds to block on each iteration, or <0 to process all incoming messages.

Returns

Zero if successful, less than zero otherwise.

mpr_graph_stop_polling()

int mpr_graph_stop_polling

(

mpr_graph

graph

)

Stop automatically synchronizing a local graph copy in a separate thread.

Parameters

graph

The graph to update.

Returns

Zero if successful, less than zero otherwise.

mpr_graph_subscribe()

void mpr_graph_subscribe	(	mpr_graph	graph,
		mpr_dev	device,
		int	types,
		int	timeout )

Subscribe to receive information from remote objects.

Parameters

graph	The graph to use.
device	The device of interest. If NULL the graph will automatically subscribe to all discovered devices.
types	Bitflags setting the type of information of interest. Can be a combination of mpr_type values.
timeout	The length in seconds for this subscription. If set to -1, the graph will automatically renew the subscription until it is freed or this function is called again.

mpr_graph_unsubscribe()

void mpr_graph_unsubscribe	(	mpr_graph	graph,
		mpr_dev	device )

Unsubscribe from information from remote objects.

Parameters

graph	The graph to use.
device	The device of interest. If NULL the graph will unsubscribe from all devices.