Context for services registered in a node for use by clients. More...

#include <Service.h>

Public Member Functions
std::map< std::string, boost::intrusive_ptr< RRValue > >	GetAttributes ()
	Get the service attributes.
void	SetAttributes (const std::map< std::string, boost::intrusive_ptr< RRValue > > &attr)
	Set the service attributes.
std::vector< std::string >	GetExtraImports ()
	Get the current vector of extra service definition imports.
void	AddExtraImport (boost::string_ref import_)
	Add an extra service definition import.
bool	RemoveExtraImport (boost::string_ref import_)
	Removes an extra import service definition registered with AddExtraImport().
std::string	GetServiceName () const
	Get the name of the service.
	ServerContext (const boost::shared_ptr< ServiceFactory > &f, const boost::shared_ptr< RobotRaconteurNode > &node)
	Construct a new ServerContext instance.
virtual void	KickUser (boost::string_ref username)
	Kicks a user with the specified username.
virtual bool	RequireValidUser ()
	Return if a valid user is required.
void	RequestObjectLock (boost::string_ref servicepath, boost::string_ref username)
	Request an object lock on servicepath for user username.
void	RequestClientObjectLock (boost::string_ref servicepath, boost::string_ref username, uint32_t endpoint)
	Request a client lock on servicepath for a specific client connection.
void	ReleaseObjectLock (boost::string_ref servicepath, boost::string_ref username, bool override_)
	Release a client lock on servicepath.
std::string	GetObjectLockUsername (boost::string_ref servicepath)
	Get the name of the user that has locked the specified service path.
void	ReleaseServicePath (boost::string_ref path)
	Release the specified service path and all sub objects.
void	ReleaseServicePath (boost::string_ref path, const std::vector< uint32_t > &endpoints)
	Release the specified service path and all sub objects.
int32_t	GetMonitorThreadPoolCount ()
	Get the number of threads used by the monitor thread pool.
void	SetMonitorThreadPoolCount (int32_t count)
	Set the monitor lock thread pool count.
boost::shared_ptr< ThreadPool >	GetMonitorThreadPool ()
	Get the monitor lock thread pool.
std::vector< std::string >	GetCandidateConnectionURLs ()
	Get the candidate connection URLs for this service.
void	PrintCandidateConnectionURLs (std::ostream &out=std::cout)
	Print the candidate connection URLs for this service.
void	LogCandidateConnectionURLs (RobotRaconteur_LogLevel level=RobotRaconteur_LogLevel_Info)
	Log the candidate connection URLs for this service.

Static Public Member Functions
static boost::shared_ptr< ServerContext >	GetCurrentServerContext ()
	Get the current ServerContext.
static std::string	GetCurrentServicePath ()
	Get the current object service path.

Protected Member Functions
void	SetSecurityPolicy (const boost::shared_ptr< ServiceSecurityPolicy > &policy)
	Set the security policy of the service.

Detailed Description

Context for services registered in a node for use by clients.

Services are registered using the RobotRaconteurNode::RegisterService() family of functions. The ServerContext manages the services, and dispatches requests and packets to the appropriate service object members. Services may expose more than one object. The root object is specified when the service is registered. Other objects are specified through ObjRef members. A name for the service is also specified when the service is registered. This name forms the root of the service path namespace. Other objects in the service have a unique service path based on the ObjRef used to access the object.

Services may handle multiple connected clients concurrently. Each client is assigned a ServerEndpoint. The ServerEndpoint is unique to the client connection, and interacts with ServerContext to complete requests and dispatch packets. When the service needs to address a specific client, the ServerEndpoint or the ServerEndpoint::GetLocalEndpoint() is used. (ServerEndpoint::GetLocalEndpoint() returns the uint32_t local client ID.)

Service attributes are a varvalue{string} types dictionary that is made available to clients during service discovery. These attributes are used to help clients determine which service should be selected for use. Because the attributes are passed to the clients as part of the discovery process, they should be as concise as possible, and should not use user defined types. Use ServerContext::SetAttributes() to set the service attributes after registering the service.

Security for the service is specified using a ServiceSecurityPolicy instance. This policy is specified by passing as a parameter to RobotRaconteurNode::RegisterService(), or passing the policy to the constructor.

ServerContext implements authentication and object locking. Server side functions are exposed by ServerContext for authentication, object locking, and client management.

Clients using dynamic typing such as Python and MATLAB will only pull service types explicitly imported by the root object and objref objects that have been requested. Clients will not pull service types of user-defined named types if that service type is not explicitly imported. This can be problematic if new struct, pod, and/or namedarray types are introduced that do not have corresponding objects. Extra imports is used to specify extra service definitions the client should pull. Use ServerContext::AddExtraImport(), ServerContext::RemoveExtraImport(), and ServerContext::GetExtraImports() to manage the extra imports passed to the client.

Constructor & Destructor Documentation

◆ ServerContext()

RobotRaconteur::ServerContext::ServerContext	(	const boost::shared_ptr< ServiceFactory > &	f,
		const boost::shared_ptr< RobotRaconteurNode > &	node )

Construct a new ServerContext instance.

The ServerContext object is constructed automatically using RobotRaconteurNode::RegisterService(boost::string_ref, boost::string_ref, const boost::shared_ptr<RRObject>&, boost::shared_ptr< ServiceSecurityPolicy > securitypolicy). It is recommended to use this method instead of constructing ServerContext.

Must use boost::make_shared<ServerContext>() to construct

Call SetBaseObject() after construction

Register using RobotRaconteurNode::RegisterServiceType()

Parameters

f	The service factory for the root object
node	The node that will own this service

Member Function Documentation

◆ AddExtraImport()

void RobotRaconteur::ServerContext::AddExtraImport ( boost::string_ref import_ )

Add an extra service definition import.

Clients using dynamic typing will not automatically pull service definitions unless imported by the root object or an objref. If new struct, pod, or namedarray types are introduced in a new service definition type without a corresponding object, an error will occur. Use AddExtraImport() to add the name of the new service definition to add it to the list of service definitions the client will pull.

Service definition must have been registered using RobotRaconteurNode::RegisterServiceType()

Parameters

import_ The name of the service definition

◆ GetAttributes()

std::map< std::string, boost::intrusive_ptr< RRValue > > RobotRaconteur::ServerContext::GetAttributes ( )

Get the service attributes.

Get the currently registered service attributes

Returns: std::map<std::string, RR_INTRUSIVE_PTR<RRValue> > The service attributes

◆ GetCandidateConnectionURLs()

std::vector< std::string > RobotRaconteur::ServerContext::GetCandidateConnectionURLs ( )

Get the candidate connection URLs for this service.

The candidate connection URLs are the URLs that can be used to connect to the service. The correct URL to use depends on the transport being used to connect to the service, and the network configuration of the client and service.

Returns: std::vector<std::string> The candidate connection URLs

◆ GetCurrentServerContext()

boost::shared_ptr< ServerContext > RobotRaconteur::ServerContext::GetCurrentServerContext ( )

static

Get the current ServerContext.

Returns the current server context during a request or packet event. This is a thread-specific value and only valid during the initial request or packet event invocation.

Returns: RR_SHARED_PTR<ServerContext> The current server context

◆ GetCurrentServicePath()

std::string RobotRaconteur::ServerContext::GetCurrentServicePath ( )

static

Get the current object service path.

Returns the service path of the current object during a request or packet event. This is a thread-specific value and only valid during the initial request or packet event invocation.

Returns: std::string The current object service path

◆ GetExtraImports()

std::vector< std::string > RobotRaconteur::ServerContext::GetExtraImports ( )

Get the current vector of extra service definition imports.

Returns: std::vector<std::string> The vector of extra imports

◆ GetMonitorThreadPool()

boost::shared_ptr< ThreadPool > RobotRaconteur::ServerContext::GetMonitorThreadPool ( )

Get the monitor lock thread pool.

See SetMonitorThreadPoolCount()

Returns: RR_SHARED_PTR<ThreadPool> The monitor lock thread pool

◆ GetMonitorThreadPoolCount()

int32_t RobotRaconteur::ServerContext::GetMonitorThreadPoolCount ( )

Get the number of threads used by the monitor thread pool.

See SetMonitorThreadPoolCount()

Returns: int32_t The number of threads

◆ GetObjectLockUsername()

std::string RobotRaconteur::ServerContext::GetObjectLockUsername ( boost::string_ref servicepath )

Get the name of the user that has locked the specified service path.

Parameters

servicepath The service path

Returns: std::string The user owning the lock, or empty servicepath is not locked

◆ GetServiceName()

std::string RobotRaconteur::ServerContext::GetServiceName ( ) const

Get the name of the service.

The service name forms the root of the service path used to specify objects within the service

Returns: std::string The name of the service

◆ KickUser()

virtual void RobotRaconteur::ServerContext::KickUser ( boost::string_ref username )

virtual

Kicks a user with the specified username.

User must be authenticated.

Parameters

username The username to kick

◆ LogCandidateConnectionURLs()

void RobotRaconteur::ServerContext::LogCandidateConnectionURLs ( RobotRaconteur_LogLevel level = RobotRaconteur_LogLevel_Info )

Log the candidate connection URLs for this service.

See GetCandidateConnectionURLs() for more information

Parameters

level The log level to use. Defaults to RobotRaconteur_LogLevel_Info

◆ PrintCandidateConnectionURLs()

void RobotRaconteur::ServerContext::PrintCandidateConnectionURLs ( std::ostream & out = std::cout )

Print the candidate connection URLs for this service.

See GetCandidateConnectionURLs() for more information

Parameters

out	The output stream to print to. Defaults to std::cout

◆ ReleaseObjectLock()

void RobotRaconteur::ServerContext::ReleaseObjectLock	(	boost::string_ref	servicepath,
		boost::string_ref	username,
		bool	override_ )

Release a client lock on servicepath.

This function handles incoming client requests, but may also be used by the service directly. Client locks can be released by the user that created them if override_ is false, or by any user if override_ is true.

The override_ parameter is set to true for client requests if the client has the "objectlockoverride" permission.

Parameters

servicepath	The service path to release lock
username	The username requesting the lock release
override_	If false, only the creating username can release the lock. If true, any username can release the lock

◆ ReleaseServicePath() [1/2]

void RobotRaconteur::ServerContext::ReleaseServicePath ( boost::string_ref path )

Release the specified service path and all sub objects.

Services take ownership of objects returned by objrefs, and will only request the object once. Subsequent requests will return the cached object. If the objref has changed, the service must call ReleaseServicePath() to tell the service to request the object again.

Release service path will release the object specified by the service path and all sub objects.

This overload will notify all clients that the objref has been released. If the service path contains a session key, use ReleaseServicePath(boost::string_ref, const std::vector<uint32_t>&) to only notify the client that owns the session.

Parameters

path	The service path to release

◆ ReleaseServicePath() [2/2]

void RobotRaconteur::ServerContext::ReleaseServicePath	(	boost::string_ref	path,
		const std::vector< uint32_t > &	endpoints )

Release the specified service path and all sub objects.

Services take ownership of objects returned by objrefs, and will only request the object once. Subsequent requests will return the cached object. If the objref has changed, the service must call ReleaseServicePath() to tell the service to request the object again.

Release service path will release the object specified by the service path and all sub objects.

This overload will notify the specified that the objref has been released. If the service path contains a session key, this overload should be used so the session key is not leaked.

Parameters

path	The service path to release
endpoints	The client endpoint IDs to notify of the released service path

◆ RemoveExtraImport()

bool RobotRaconteur::ServerContext::RemoveExtraImport ( boost::string_ref import_ )

Removes an extra import service definition registered with AddExtraImport().

See AddExtraImport()

Parameters

import_ The name of the service definition

Returns: true The service definition was removed; false The service definition was not found in the extra imports vector

◆ RequestClientObjectLock()

void RobotRaconteur::ServerContext::RequestClientObjectLock	(	boost::string_ref	servicepath,
		boost::string_ref	username,
		uint32_t	endpoint )

Request a client lock on servicepath for a specific client connection.

This function handles incoming client requests, but may also be used by the service directly. Client object locks lock for a specific client connection, while client locks lock for a specific user. The specific client connection is specified using endpoint.

Parameters

servicepath	The service path to lock
username	The name of the user owning the lock
endpoint	The client endpoint ID of the client owning the lock

◆ RequestObjectLock()

void RobotRaconteur::ServerContext::RequestObjectLock	(	boost::string_ref	servicepath,
		boost::string_ref	username )

Request an object lock on servicepath for user username.

This function handles incoming client requests, but may also be used by the service directly

Parameters

servicepath	The service path to lock
username	The name of the user owning the lock

◆ RequireValidUser()

virtual bool RobotRaconteur::ServerContext::RequireValidUser ( )

virtual

Return if a valid user is required.

Security is configured through the SecurityPolicy object specified with RobotRaconteur::RegisterService() or SetSecurityPolicy()

Returns: true Users must authenticate to use the service; false Anonymous users are allowed

◆ SetAttributes()

void RobotRaconteur::ServerContext::SetAttributes ( const std::map< std::string, boost::intrusive_ptr< RRValue > > & attr )

Set the service attributes.

Sets the service attributes. Attributes are made available to clients during service discovery. Attributes should be concise and not use any user defined types.

Parameters

attr	The service attributes

◆ SetMonitorThreadPoolCount()

void RobotRaconteur::ServerContext::SetMonitorThreadPoolCount ( int32_t count )

Set the monitor lock thread pool count.

Monitor looks use a thread pool to manage tho lock. Each lock takes ownership of a thread, and this thread is used to enforce single thread at a time access. By default 3 threads are activated, allowing for 3 concurrent monitor locks. Use SetMonitorThreadPoolCount() to enable more monitor locks if necessary.

Parameters

count The number of threads

◆ SetSecurityPolicy()

void RobotRaconteur::ServerContext::SetSecurityPolicy ( const boost::shared_ptr< ServiceSecurityPolicy > & policy )

protected

Set the security policy of the service.

The security policy is set automatically using RobotRaconteurNode::RegisterService(boost::string_ref, boost::string_ref, const boost::shared_ptr<RRObject>&, boost::shared_ptr< ServiceSecurityPolicy > securitypolicy). It is recommended to use this method instead of SetSecurityPolicy().

Parameters

policy The security policy

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/Service.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ServerContext()

Member Function Documentation

◆ AddExtraImport()

◆ GetAttributes()

◆ GetCandidateConnectionURLs()

◆ GetCurrentServerContext()

◆ GetCurrentServicePath()

◆ GetExtraImports()

◆ GetMonitorThreadPool()

◆ GetMonitorThreadPoolCount()

◆ GetObjectLockUsername()

◆ GetServiceName()

◆ KickUser()

◆ LogCandidateConnectionURLs()

◆ PrintCandidateConnectionURLs()

◆ ReleaseObjectLock()

◆ ReleaseServicePath() [1/2]

◆ ReleaseServicePath() [2/2]

◆ RemoveExtraImport()

◆ RequestClientObjectLock()

◆ RequestObjectLock()

◆ RequireValidUser()

◆ SetAttributes()

◆ SetMonitorThreadPoolCount()

◆ SetSecurityPolicy()