Messaging accross device boundaries. More...

Typedefs
typedef int	reme_remote_t
	Handle referencing a remote control object. More...

reme_error_t	reme_remote_create (reme_context_t c, reme_remote_t *r)
	Create a remote object. More...

reme_error_t	reme_remote_destroy (reme_context_t c, reme_remote_t *r)
	Destroy a previously created remote object. More...

reme_error_t	reme_remote_bind (reme_context_t c, reme_remote_t r, const char *address)
	Launch a broker service at a specific address. More...

reme_error_t	reme_remote_connect (reme_context_t c, reme_remote_t r, const char *address, int timeout)
	Connect to a broker service. More...

reme_error_t	reme_remote_subscribe (reme_context_t c, reme_remote_t r, const char *topic)
	Listen to topics. More...

reme_error_t	reme_remote_subscribe_advanced (reme_context_t c, reme_remote_t r, const char topic, const char group, bool exactTopicMatch, int priority, int maxQueueSize)
	Subscribe to a topic. More...

reme_error_t	reme_remote_recv (reme_context_t c, reme_remote_t r, int topicIndex, const char *topicName, reme_bag_t b, int timeout)
	Try receive from any of the subscribed topics. More...

reme_error_t	reme_remote_send (reme_context_t c, reme_remote_t r, const char *topic, reme_bag_t b)
	Send data to topic. More...

reme_error_t	reme_remote_notify (reme_context_t c, reme_remote_t r, const char *topic)
	Send empty message to topic. More...

Detailed Description

Messaging accross device boundaries.

The Remote module provides methods to communicate between ReconstructMe SDK instances running on different devices connected through network interfaces.

Central to Remote is the existance of a broker service. The broker service is responsible for distributing messages among interested subscribers. Messages are sent and received via topics.

To get started with ReMe Remote you need a process that will provide the broker service as shown below.

    reme_remote_t r;
    reme_remote_create(c, &r);
    reme_remote_bind(c, r, "tcp://127.0.0.1:50000");

In the above snippet, the broker provides its service on "tcp://127.0.0.1:50000". Similarly, clients may connect to the broker service

    reme_remote_t r;
    reme_remote_create(c, &r);
    reme_remote_connect(c, r, "tcp://127.0.0.1:50000", 10000);

Next you may want to subscribe for topics.

    const char *topics[] = { "system/shutdown", "system/greet" };
    reme_remote_subscribe(c, r, topics[0]);
    reme_remote_subscribe(c, r, topics[1]);

To see if subscribed topics have data use the reme_remote_recv function.

        int topicIndex = -1;
        const char *topicName = 0;
        reme_remote_recv(c, r, &topicIndex, &topicName, bag, 1000);

This method will wait no longer than the specified timeout for a subscribed topic to have new data. The first topic with a pending read (if any) is returned. When the received topic has data attached, its result will be stored in the bag parameter passed along. For using bags, please refer to Bag.

To send data to an any topic you can use reme_remote_send as shown below.

reme_remote_send(c, r, "system/greetings", bag);

In case you want to signal a topic (i.e sending to the topic without data), you can use reme_remote_notify.

reme_remote_notify(c, r, "system/shutdown");

For a remote reconstruction example please refer to example_reconstructmesdk_remote_reconstruction.cpp

Specifics when using Remote

There are a couple of design decisions in Remote that you should be aware of

By design messages sent to topics that do not have subscribers will be dropped by the broker.
By default topic queue sizes at the broker are limited to avoid memory allocation issues when slow subscribers cannot cope with the speed of senders. When a topic queue is full and new messages arrive, old messages are dropped in favor of new messages. Use reme_remote_subscribe_advanced to control queue sizes.
By default when subscribing to multiple topics, messages will be delivered in chronological receive order. You can prioritize specific topics over others using reme_remote_subscribe_advanced.
The broker service runs in the background and on heavy load it might slow down the process it runs in. If you can, you might want to dedicate a broker service to process that runs it exclusively.

Typedef Documentation

◆ reme_remote_t

typedef int reme_remote_t

Handle referencing a remote control object.

A reme_remote_t allows you to communicate with remote services running on other devices. This allows you split reconstruction into data acquisition on low powered mobile devices and perform the reconstruction on remote devices.

ReconstructMe SDK implements a message bus system where a single broker distributes messages to remote points. Messages are identified by topic names. Endpoints can subscribe to topics via the broker to receive messages, or send messages to specific topics. The messages being sent and received are reme_bag_t objects.

Function Documentation

◆ reme_remote_create()

reme_error_t reme_remote_create	(	reme_context_t	c,
		reme_remote_t *	r
	)

Create a remote object.

A remote object is used to communicate with other ReconstructMe instances accross device boundaries.

Parameters

c	A valid context object
r	A pointer to receive the created remote object handle.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:: example_reconstructmesdk_remote_intro.cpp, and example_reconstructmesdk_remote_reconstruction.cpp.

◆ reme_remote_destroy()

reme_error_t reme_remote_destroy	(	reme_context_t	c,
		reme_remote_t *	r
	)

Destroy a previously created remote object.

Parameters

c	A pointer to a valid context object
r	A mutable pointer to a valid remote handle to destroy

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

◆ reme_remote_bind()

reme_error_t reme_remote_bind	(	reme_context_t	c,
		reme_remote_t	r,
		const char *	address
	)

Launch a broker service at a specific address.

A broker is the central dispatch component in the ReconstructMe SDK remote messaging system. The broker is responsible for distributing messages sent to interested listeners. There needs at least to be one broker service running in a distributed system.

When you call reme_remote_bind a broker service at the given address is launched. There is no need for the caller to invoke reme_remote_connect too, as the reme_remote_bind implicitly connects.

Note when calling this method multiple times, previous broker services will be destroyed.

Parameters

c	A pointer to a valid context object
r	A valid remote object
address	Address to run the broker service on. Examples include tcp://127.0.0.1:50000, or tcp://*:50000

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:: example_reconstructmesdk_remote_intro.cpp, and example_reconstructmesdk_remote_reconstruction.cpp.

◆ reme_remote_connect()

reme_error_t reme_remote_connect	(	reme_context_t	c,
		reme_remote_t	r,
		const char *	address,
		int	timeout
	)

Connect to a broker service.

In order to send / receive messages a remote needs to be connected to a broker service. Use this method to connect to broker service that was created through reme_remote_bind.

Parameters

c	A pointer to a valid context object
r	A valid remote object
address	Address of running broker service. For example tcp://127.0.0.1:50000
timeout	Timeout in milliseconds for connect to succeed.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:: example_reconstructmesdk_remote_intro.cpp, and example_reconstructmesdk_remote_reconstruction.cpp.

◆ reme_remote_subscribe()

reme_error_t reme_remote_subscribe	(	reme_context_t	c,
		reme_remote_t	r,
		const char *	topic
	)

Listen to topics.

Subscribes to a single topic. A topic is a named delivery address for messages. When calling this method multiple times, the remote object will subscribe to each one of the topics. The order of subscription will be used later on to allow you distinguishing which topic received a message based on its order of subscription index.

Note, the remote object needs to be connected to a broker service (reme_remote_connect or reme_remote_bind), before subscribing to topics.

This method uses default parameters for the subscription. See reme_remote_subscribe_advanced for more info. The default description limits the memory usage on the broker by setting the maximum broker queue length to 20 messages. If you cannot receive fast enough, the broker will drop old messages in favor of new messages.

Parameters

c	A pointer to a valid context object
r	A valid remote object
topic	Name of topic.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:: example_reconstructmesdk_remote_intro.cpp, and example_reconstructmesdk_remote_reconstruction.cpp.

◆ reme_remote_subscribe_advanced()

reme_error_t reme_remote_subscribe_advanced	(	reme_context_t	c,
		reme_remote_t	r,
		const char *	topic,
		const char *	group,
		bool	exactTopicMatch,
		int	priority,
		int	maxQueueSize
	)

Subscribe to a topic.

Subscribes to a single topic. A topic is a named delivery address for messages. When calling this method multiple times, the remote object will subscribe to each one of the topics. The order of subscription will be used later on to allow you distinguishing which topic received a message based on its order of subscription index.

Note, the remote object needs to be connected to a broker service (reme_remote_connect or reme_remote_bind), before subscribing to topics.

Parameters

c	A pointer to a valid context object
r	A valid remote object
topic	Name of topic.
group	When specified, this will put the endpoint in the given group. When multiple endpoints subcribe to the same topic AND group, messages are sent to only one endpoint per group (load balanced queue). When the group is left empty, the endpoint receives all matching messages (private queue). Defaults to empty string. Currently unused.
exactTopicMatch	Whether or not you only want to receive messages sent to the exact topic name used at subscription. If you set this to false and you subscribe to "greet" you would also receive messages sent to the topic "greetings" and other topic names that start with the same characters. Defaults to true.
priority	When specified, matching messages will get this priority. Messages are delivered in the order of their priorities. Messages with equal priorities are delivered chronologically. Defaults to zero.
maxQueueSize	When the queue (at the broker) has more elements than this value older messages are dropped in favor of new ones.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:: example_reconstructmesdk_remote_reconstruction.cpp.

◆ reme_remote_recv()

reme_error_t reme_remote_recv	(	reme_context_t	c,
		reme_remote_t	r,
		int *	topicIndex,
		const char **	topicName,
		reme_bag_t	b,
		int	timeout
	)

Try receive from any of the subscribed topics.

If multiple topics have data messages are delivered chonologically, except when priorities are not equal. See reme_remote_subscribe_advanced for more details.

Parameters

c	A pointer to a valid context object.
r	A valid remote object.
topicIndex	Index of the topic that has data. -1 if no topic was notified or has data.
topicName	Name of topic that has data. Caller does not own memory and shall therefore not free the returned pointer.
b	A valid bag object.
timeout	Maximum time in milliseconds to wait for new messages.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:: example_reconstructmesdk_remote_intro.cpp, and example_reconstructmesdk_remote_reconstruction.cpp.

◆ reme_remote_send()

reme_error_t reme_remote_send	(	reme_context_t	c,
		reme_remote_t	r,
		const char *	topic,
		reme_bag_t	b
	)

Send data to topic.

You can send data to any topic, independent of whether you are subscribed to that particular topic or not.

Messages sent topics without any listeners are dropped by the remote service for performance reasons.

Parameters

c	A pointer to a valid context object.
r	A valid remote object.
topic	Name of the topic to send data to.
b	A valid bag object to send.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:: example_reconstructmesdk_remote_intro.cpp, and example_reconstructmesdk_remote_reconstruction.cpp.

◆ reme_remote_notify()

reme_error_t reme_remote_notify	(	reme_context_t	c,
		reme_remote_t	r,
		const char *	topic
	)

Send empty message to topic.

This method is similar in its behaviour to reme_remote_send but without arguments. It's mostly used to signal specific topics that don't expect event arguments.

Parameters

c	A pointer to a valid context object.
r	A valid remote object.
topic	Name of the topic to send data to.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:: example_reconstructmesdk_remote_intro.cpp, and example_reconstructmesdk_remote_reconstruction.cpp.

Typedefs

Detailed Description

Specifics when using Remote

Typedef Documentation

◆ reme_remote_t

Function Documentation

◆ reme_remote_create()

◆ reme_remote_destroy()

◆ reme_remote_bind()

◆ reme_remote_connect()

◆ reme_remote_subscribe()

◆ reme_remote_subscribe_advanced()

◆ reme_remote_recv()

◆ reme_remote_send()

◆ reme_remote_notify()