Subscription that automatically connects services and manages lifecycle of connected services. More...

#include <Subscription.h>

Public Member Functions
std::map< ServiceSubscriptionClientID, boost::shared_ptr< RRObject > >	GetConnectedClients ()
	Returns a map of connected clients.
event_connection	AddClientConnectListener (boost::function< void(const boost::shared_ptr< ServiceSubscription > &, const ServiceSubscriptionClientID &, const boost::shared_ptr< RRObject > &)> handler)
	Add a listener callback that is invoked when a client is connected.
event_connection	AddClientDisconnectListener (boost::function< void(const boost::shared_ptr< ServiceSubscription > &, const ServiceSubscriptionClientID &, const boost::shared_ptr< RRObject > &)> handler)
	Add a listener callback that is invoked when a client is disconnected.
event_connection	AddClientConnectFailedListener (boost::function< void(const boost::shared_ptr< ServiceSubscription > &, const ServiceSubscriptionClientID &, const std::vector< std::string > &, const boost::shared_ptr< RobotRaconteurException > &)> handler)
	Add a listener callback that is invoked when a client connection attempt fails.
RR_OVIRTUAL void	Close () RR_OVERRIDE
	Close the subscription.
virtual void	ClaimClient (const boost::shared_ptr< RRObject > &client)
	Claim a client that was connected by the subscription.
virtual void	ReleaseClient (const boost::shared_ptr< RRObject > &client)
	Release a client previously claimed with ClaimClient().
uint32_t	GetConnectRetryDelay ()
	Get the connect retry delay in milliseconds.
void	SetConnectRetryDelay (uint32_t delay_milliseconds)
	Set the connect retry delay in milliseconds.
template<typename T>
boost::shared_ptr< WireSubscription< T > >	SubscribeWire (boost::string_ref membername, boost::string_ref servicepath="")
	Creates a wire subscription.
template<typename T>
boost::shared_ptr< PipeSubscription< T > >	SubscribePipe (boost::string_ref membername, boost::string_ref servicepath="", uint32_t max_recv_packets=std::numeric_limits< uint32_t >::max())
	Creates a pipe subscription.
template<typename T>
boost::shared_ptr< T >	GetDefaultClient ()
	Get the "default client" connection.
template<typename T>
bool	TryGetDefaultClient (boost::shared_ptr< T > &client_out)
	Try getting the "default client" connection.
template<typename T>
boost::shared_ptr< T >	GetDefaultClientWait (int32_t timeout=RR_TIMEOUT_INFINITE)
	Get the "default client" connection, waiting with timeout if not connected.
template<typename T>
bool	TryGetDefaultClientWait (boost::shared_ptr< T > &client_out, int32_t timeout=RR_TIMEOUT_INFINITE)
	Try getting the "default client" connection, waiting with timeout if not connected.
template<typename T>
void	AsyncGetDefaultClient (boost::function< void(const boost::shared_ptr< T > &, const boost::shared_ptr< RobotRaconteurException > &)> handler, int32_t timeout=RR_TIMEOUT_INFINITE)
	Asynchronously get the default client, with optional timeout.
std::vector< std::string >	GetServiceURL ()
	Get the service connection URL.
void	UpdateServiceURL (boost::string_ref url, boost::string_ref username="", const boost::intrusive_ptr< RRMap< std::string, RRValue > > &credentials=(boost::intrusive_ptr< RRMap< std::string, RRValue > >()), boost::string_ref object_type="", bool close_connected=false)
	Update the service connection URL.
void	UpdateServiceURL (const std::vector< std::string > &url, boost::string_ref username="", const boost::intrusive_ptr< RRMap< std::string, RRValue > > &credentials=(boost::intrusive_ptr< RRMap< std::string, RRValue > >()), boost::string_ref object_type="", bool close_connected=false)
	Update the service connection URL.
void	UpdateServiceByType (const std::vector< std::string > &service_types, const boost::shared_ptr< ServiceSubscriptionFilter > &filter=boost::shared_ptr< ServiceSubscriptionFilter >())
	Update the service type and filter for subscription.
boost::shared_ptr< SubObjectSubscription >	SubscribeSubObject (boost::string_ref servicepath, boost::string_ref objecttype="")
	Creates a sub object subscription.

Detailed Description

Subscription that automatically connects services and manages lifecycle of connected services.

Created using RobotRaconteurNode::SubscribeService() or RobotRaconteurNode::SubscribeServiceByType(). The ServiceSubscription class is used to automatically create and manage connections based on connection criteria. RobotRaconteurNode::SubscribeService() is used to create a robust connection to a service with a specific URL. RobotRaconteurNode::SubscribeServiceByType() is used to connect to services with a specified type, filtered with a ServiceSubscriptionFilter. Subscriptions will create connections to matching services, and will retry the connection if it fails or the connection is lost. This behavior allows subscriptions to be used to create robust connections. The retry delay for connections can be modified using SetConnectRetryDelay() and GetConnectRetryDelay().

The currently connected clients can be retrieved using the GetConnectedClients() function. A single "default client" can be retrieved using the GetDefaultClient() function or TryGetDefaultClient() functions. Listeners for client connect and disconnect events can be added using the AddClientConnectListener() and AddClientDisconnectListener() functions. If the user wants to claim a client, the ClaimClient() and ReleaseClient() functions will be used. Claimed clients will no longer have their lifecycle managed by the subscription.

Subscriptions can be used to create pipe and wire subscriptions. These member subscriptions aggregate the packets and values being received from all services. They can also act as a "reverse broadcaster" to send packets and values to all services that are actively connected. See PipeSubscription and WireSubscription.

Member Function Documentation

◆ AddClientConnectFailedListener()

event_connection RobotRaconteur::ServiceSubscription::AddClientConnectFailedListener ( boost::function< void(const boost::shared_ptr< ServiceSubscription > &, const ServiceSubscriptionClientID &, const std::vector< std::string > &, const boost::shared_ptr< RobotRaconteurException > &)> handler )

Add a listener callback that is invoked when a client connection attempt fails.

The callback should have the signature:

void cb(ServiceSubscriptionPtr subscription, const ServiceSubscriptionClientID& client_id, const std::vector<std::string>& url, RobotRaconteurExceptionPtr err)

The returned event_connection can be used to modify or close the Boost.Signals2 connection.

Parameters

handler The callback function

Returns: event_connection The Boost.Signals2 connection

◆ AddClientConnectListener()

event_connection RobotRaconteur::ServiceSubscription::AddClientConnectListener ( boost::function< void(const boost::shared_ptr< ServiceSubscription > &, const ServiceSubscriptionClientID &, const boost::shared_ptr< RRObject > &)> handler )

Add a listener callback that is invoked when a client is connected.

The callback should have the signature:

void cb(ServiceSubscriptionPtr subscription, const ServiceSubscriptionClientID& client_id, RRObjectPtr client)

The returned event_connection can be used to modify or close the Boost.Signals2 connection.

Parameters

handler The callback function

Returns: event_connection The Boost.Signals2 connection

◆ AddClientDisconnectListener()

event_connection RobotRaconteur::ServiceSubscription::AddClientDisconnectListener ( boost::function< void(const boost::shared_ptr< ServiceSubscription > &, const ServiceSubscriptionClientID &, const boost::shared_ptr< RRObject > &)> handler )

Add a listener callback that is invoked when a client is disconnected.

The callback should have the signature:

void cb(ServiceSubscriptionPtr subscription, const ServiceSubscriptionClientID& client_id, RRObjectPtr client)

The returned event_connection can be used to modify or close the Boost.Signals2 connection.

Parameters

handler The callback function

Returns: event_connection The Boost.Signals2 connection

◆ AsyncGetDefaultClient()

template<typename T>

void RobotRaconteur::ServiceSubscription::AsyncGetDefaultClient	(	boost::function< void(const boost::shared_ptr< T > &, const boost::shared_ptr< RobotRaconteurException > &)>	handler,
		int32_t	timeout = RR_TIMEOUT_INFINITE )

inline

Asynchronously get the default client, with optional timeout.

Same as GetDefaultClientWait(), but returns asynchronously.

Template Parameters

T	The type of the client object

Parameters

handler	The handler to call when default client is available, or times out
timeout	Timeout in milliseconds, or RR_TIMEOUT_INFINITE for no timeout

◆ ClaimClient()

virtual void RobotRaconteur::ServiceSubscription::ClaimClient ( const boost::shared_ptr< RRObject > & client )

virtual

Claim a client that was connected by the subscription.

The subscription class will automatically manage the lifecycle of the connected clients. The clients will be automatically disconnected and/or reconnected as necessary. If the user wants to disable this behavior for a specific client connection, the client connection can be "claimed".

Parameters

client The client to be claimed

◆ Close()

RR_OVIRTUAL void RobotRaconteur::ServiceSubscription::Close ( )

Close the subscription.

Close the subscription. Subscriptions are automatically closed when the node is shut down.

◆ GetConnectedClients()

std::map< ServiceSubscriptionClientID, boost::shared_ptr< RRObject > > RobotRaconteur::ServiceSubscription::GetConnectedClients ( )

Returns a map of connected clients.

The returned map contains the connect clients. The map is keyed with ServiceSubscriptionClientID.

Clients must be cast to a type, similar to the client returned by RobotRaconteurNode::ConnectService().

Clients can be "claimed" using ClaimClient(). Once claimed, the subscription will stop managing the lifecycle of the client.

This function does not block.

Returns: std::map<ServiceSubscriptionClientID, ServiceInfo2 > The detected services.

◆ GetConnectRetryDelay()

uint32_t RobotRaconteur::ServiceSubscription::GetConnectRetryDelay ( )

Get the connect retry delay in milliseconds.

Default is 2.5 seconds

Returns: uint32_t The retry delay in milliseconds

◆ GetDefaultClient()

template<typename T>

boost::shared_ptr< T > RobotRaconteur::ServiceSubscription::GetDefaultClient ( )

inline

Get the "default client" connection.

The "default client" is the "first" client returned from the connected clients map. This is effectively default, and is only useful if only a single client connection is expected. This is normally true for RobotRaconteurNode::SubscribeService()

Clients using GetDefaultClient() should not store a reference to the client. It should instead call GetDefaultClient() right before using the client to make sure the most recently connection is being used. If possible, SubscribePipe() or SubscribeWire() should be used so the lifecycle of pipes and wires can be managed automatically.

Template Parameters

T	The type of the client object

Returns: RR_SHARED_PTR<T> The client connection

◆ GetDefaultClientWait()

template<typename T>

boost::shared_ptr< T > RobotRaconteur::ServiceSubscription::GetDefaultClientWait ( int32_t timeout = RR_TIMEOUT_INFINITE )

inline

Get the "default client" connection, waiting with timeout if not connected.

The "default client" is the "first" client returned from the connected clients map. This is effectively default, and is only useful if only a single client connection is expected. This is normally true for RobotRaconteurNode::SubscribeService()

Clients using GetDefaultClient() should not store a reference to the client. It should instead call GetDefaultClient() right before using the client to make sure the most recenty connection is being used. If possible, SubscribePipe() or SubscribeWire() should be used so the lifecycle of pipes and wires can be managed automatically.

Parameters

timeout Timeout in milliseconds, or RR_TIMEOUT_INFINITE for no timeout

Template Parameters

T	The type of the client object

Returns: RR_SHARED_PTR<T> The client connection

◆ GetServiceURL()

std::vector< std::string > RobotRaconteur::ServiceSubscription::GetServiceURL ( )

Get the service connection URL.

Returns the service connection URL. Only valid when subscription was created using RobotRaconteurNode::SubscribeService(). Will throw an exception if subscription was opened using RobotRaconteurNode::SubscribeServiceByType()

Returns: std::vector<std::string>

◆ ReleaseClient()

virtual void RobotRaconteur::ServiceSubscription::ReleaseClient ( const boost::shared_ptr< RRObject > & client )

virtual

Release a client previously claimed with ClaimClient().

Lifecycle management is returned to the subscription

Parameters

client The client to release claim

◆ SetConnectRetryDelay()

void RobotRaconteur::ServiceSubscription::SetConnectRetryDelay ( uint32_t delay_milliseconds )

Set the connect retry delay in milliseconds.

Default is 2.5 seconds

Parameters

delay_milliseconds The delay in milliseconds

◆ SubscribePipe()

template<typename T>

boost::shared_ptr< PipeSubscription< T > > RobotRaconteur::ServiceSubscription::SubscribePipe	(	boost::string_ref	membername,
		boost::string_ref	servicepath = "",
		uint32_t	max_recv_packets = std::numeric_limits<uint32_t>::max() )

inline

Creates a pipe subscription.

Pipe subscriptions aggregate the packets received from the connected services. It can also act as a "reverse broadcaster" to send packets to clients. See PipeSubscription.

The optional service path may be an empty string to use the root object in the service. The first level of the service path may be "*" to match any service name. For instance, the service path "*.sub_obj" will match any service name, and use the "sub_obj" objref.

Template Parameters

T	The type of the pipe packets. This must be specified since the subscription does not know the pipe packet type

Parameters

membername	The member name of the pipe
servicepath	The service path of the object owning the pipe member

Returns: RR_SHARED_PTR<PipeSubscription<T> > The pipe subscription

◆ SubscribeSubObject()

boost::shared_ptr< SubObjectSubscription > RobotRaconteur::ServiceSubscription::SubscribeSubObject	(	boost::string_ref	servicepath,
		boost::string_ref	objecttype = "" )

Creates a sub object subscription.

Sub objects are objects within a service that are not the root object. Sub objects are typically referenced using objref members, however they can also be referenced using a service path. The SubObjectSubscription class is used to automatically access sub objects of the default client.

The service path is broken up into segments using periods. See the Robot Raconter documentation for more information. The BuildServicePath() function can be used to assist building service paths. The first level of the* service path may be "*" to match any service name. For instance, the service path "*.sub_obj" will match any service name, and use the "sub_obj" objref

Parameters

servicepath	The service path of the sub object
objecttype	Optional object type to use for the sub object

Returns: RR_SHARED_PTR<SubObjectSubscription> The sub object subscription

◆ SubscribeWire()

template<typename T>

boost::shared_ptr< WireSubscription< T > > RobotRaconteur::ServiceSubscription::SubscribeWire	(	boost::string_ref	membername,
		boost::string_ref	servicepath = "" )

inline

Creates a wire subscription.

Wire subscriptions aggregate the value received from the connected services. It can also act as a "reverse broadcaster" to send values to clients. See WireSubscription.

The optional service path may be an empty string to use the root object in the service. The first level of the service path may be "*" to match any service name. For instance, the service path "*.sub_obj" will match any service name, and use the "sub_obj" objref.

Template Parameters

T	The type of the wire value. This must be specified since the subscription doesn't know the wire value type

Parameters

membername	The member name of the wire
servicepath	The service path of the object owning the wire member

Returns: RR_SHARED_PTR<WireSubscription<T> > The wire subscription

◆ TryGetDefaultClient()

template<typename T>

bool RobotRaconteur::ServiceSubscription::TryGetDefaultClient ( boost::shared_ptr< T > & client_out )

inline

Try getting the "default client" connection.

Same as GetDefaultClient(), but returns a bool success instead of throwing exceptions on failure.

Template Parameters

T	The type of the client object

Parameters

client_out [out] The client connection

Returns: true client_out is valid; false client_out is invalid, no client is not currently connected

◆ TryGetDefaultClientWait()

template<typename T>

bool RobotRaconteur::ServiceSubscription::TryGetDefaultClientWait	(	boost::shared_ptr< T > &	client_out,
		int32_t	timeout = RR_TIMEOUT_INFINITE )

inline

Try getting the "default client" connection, waiting with timeout if not connected.

Same as GetDefaultClientWait(), but returns a bool success instead of throwing exceptions on failure.

Template Parameters

T	The type of the client object

Parameters

client_out	[out] The client connection
timeout	Timeout in milliseconds, or RR_TIMEOUT_INFINITE for no timeout

Returns: true client_out is valid; false client_out is invalid, no client is not currently connected

◆ UpdateServiceByType()

void RobotRaconteur::ServiceSubscription::UpdateServiceByType	(	const std::vector< std::string > &	service_types,
		const boost::shared_ptr< ServiceSubscriptionFilter > &	filter = boost::shared_ptr< ServiceSubscriptionFilter >() )

Update the service type and filter for subscription.

Updates the existing target service types and filter for a running subscription

Parameters

service_types	A std::vector of service types to listen for, ie com.robotraconteur.robotics.robot.Robot
filter	A filter to select individual services based on specified criteria

◆ UpdateServiceURL() [1/2]

void RobotRaconteur::ServiceSubscription::UpdateServiceURL	(	boost::string_ref	url,
		boost::string_ref	username = "",
		const boost::intrusive_ptr< RRMap< std::string, RRValue > > &	credentials = (boost::intrusive_ptr< RRMap< std::string, RRValue > >()),
		boost::string_ref	object_type = "",
		bool	close_connected = false )

Update the service connection URL.

Updates the URL used to connect to the service. If close_connected is true, existing connections will be closed. If false, existing connections will not be closed.

Parameters

url	The new URL to use to connect to service
username	(Optional) The new username
credentials	(Optional) The new credentials
object_type	(Optional) The desired root object proxy type. Optional but highly recommended.
close_connected	(Optional, default false) Close existing connections

◆ UpdateServiceURL() [2/2]

void RobotRaconteur::ServiceSubscription::UpdateServiceURL	(	const std::vector< std::string > &	url,
		boost::string_ref	username = "",
		const boost::intrusive_ptr< RRMap< std::string, RRValue > > &	credentials = (boost::intrusive_ptr< RRMap< std::string, RRValue > >()),
		boost::string_ref	object_type = "",
		bool	close_connected = false )

Update the service connection URL.

Updates the URL used to connect to the service. If close_connected is true, existing connections will be closed. If false, existing connections will not be closed.

Parameters

url	The new URLs to use to connect to service
username	(Optional) The new username
credentials	(Optional) The new credentials
object_type	The desired root object proxy type. Optional but highly recommended.
close_connected	(Optional, default false) Close existing connections

The documentation for this class was generated from the following file:

/builddir/build/BUILD/robotraconteur-1.2.8-build/RobotRaconteur-1.2.8-Source/RobotRaconteurCore/include/RobotRaconteur/Subscription.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ AddClientConnectFailedListener()

◆ AddClientConnectListener()

◆ AddClientDisconnectListener()

◆ AsyncGetDefaultClient()

◆ ClaimClient()

◆ Close()

◆ GetConnectedClients()

◆ GetConnectRetryDelay()

◆ GetDefaultClient()

◆ GetDefaultClientWait()

◆ GetServiceURL()

◆ ReleaseClient()

◆ SetConnectRetryDelay()

◆ SubscribePipe()

◆ SubscribeSubObject()

◆ SubscribeWire()

◆ TryGetDefaultClient()

◆ TryGetDefaultClientWait()

◆ UpdateServiceByType()

◆ UpdateServiceURL() [1/2]

◆ UpdateServiceURL() [2/2]