Session API used by a client peer in WAMP applications. More...

#include <cppwamp/session.hpp>

Inheritance diagram for wamp::Session:

Public Types
using	Ptr = std::shared_ptr< Session >
	Shared pointer to a Session.

using	State = SessionState
	Enumerates the possible states that a Session can be in.

using	EventSlot = AnyReusableHandler< void(Event)>
	Type-erased wrapper around a WAMP event handler.

using	CallSlot = AnyReusableHandler< Outcome(Invocation)>
	Type-erased wrapper around an RPC handler.

using	InterruptSlot = AnyReusableHandler< Outcome(Interruption)>
	Type-erased wrapper around an RPC interruption handler.

using	LogHandler = AnyReusableHandler< void(std::string)>
	Type-erased wrapper around a log event handler.

using	StateChangeHandler = AnyReusableHandler< void(SessionState)>
	Type-erased wrapper around a Session state change handler.

using	ChallengeHandler = AnyReusableHandler< void(Challenge)>
	Type-erased wrapper around an authentication challenge handler.

template<typename T , typename C >
using	Deduced = decltype(boost::asio::async_initiate< C, void(T)>(std::declval< GenericOp & >(), std::declval< C & >()))
	Obtains the type returned by boost::asio::async_initiate with given the completion token type `C` and signature `void(T)`. More...

Public Member Functions
virtual	~Session ()
	Destructor. More...

Non-copyable
	Session (const Session &)=delete

Session &	operator= (const Session &)=delete

Observers
AnyIoExecutor	userExecutor () const
	Obtains the fallback executor used to execute user-provided handlers.

AnyIoExecutor	userIosvc () const
	Legacy function kept for backward compatiblity. More...

IoStrand	strand () const
	Obtains the execution context in which which I/O operations are serialized.

SessionState	state () const
	Returns the current state of the session.

Modifiers
void	setWarningHandler (LogHandler handler)
	Sets the log handler that is dispatched for warnings. More...

void	setWarningHandler (ThreadSafe, LogHandler handler)
	Thread-safe setting of warning handler. More...

void	setTraceHandler (LogHandler handler)
	Sets the log handler that is dispatched for debug traces. More...

void	setTraceHandler (ThreadSafe, LogHandler handler)
	Thread-safe setting of trace handler. More...

void	setStateChangeHandler (StateChangeHandler handler)
	Sets the handler that is posted for session state changes. More...

void	setStateChangeHandler (ThreadSafe, StateChangeHandler handler)
	Thread-safe setting of state change handler. More...

void	setChallengeHandler (ChallengeHandler handler)
	Sets the handler that is dispatched for authentication challenges. More...

void	setChallengeHandler (ThreadSafe, ChallengeHandler handler)
	Thread-safe setting of state change handler. More...

Session Management
template<typename C >
Deduced< ErrorOr< std::size_t >, C >	connect (C &&completion)
	Asynchronously attempts to connect to a router. More...

template<typename C >
Deduced< ErrorOr< std::size_t >, C >	connect (ThreadSafe, C &&completion)
	Thread-safe connect. More...

template<typename C >
Deduced< ErrorOr< SessionInfo >, C >	join (Realm realm, C &&completion)
	Asynchronously attempts to join the given WAMP realm. More...

template<typename C >
Deduced< ErrorOr< SessionInfo >, C >	join (ThreadSafe, Realm realm, C &&completion)
	Thread-safe join. More...

void	authenticate (Authentication auth)
	Sends an `AUTHENTICATE` in response to a `CHALLENGE`. More...

void	authenticate (ThreadSafe, Authentication auth)
	Thread-safe authenticate. More...

template<typename C >
Deduced< ErrorOr< Reason >, C >	leave (C &&completion)
	Asynchronously leaves the WAMP session. More...

template<typename C >
Deduced< ErrorOr< Reason >, C >	leave (ThreadSafe, C &&completion)
	Thread-safe leave. More...

template<typename C >
Deduced< ErrorOr< Reason >, C >	leave (Reason reason, C &&completion)
	Asynchronously leaves the WAMP session with the given reason. More...

template<typename C >
Deduced< ErrorOr< Reason >, C >	leave (ThreadSafe, Reason reason, C &&completion)
	Thread-safe leave with reason. More...

void	disconnect ()
	Disconnects the transport between the client and router. More...

void	disconnect (ThreadSafe)
	Thread-safe disconnect. More...

void	reset ()
	Terminates the transport connection between the client and router. More...

void	reset (ThreadSafe)
	Thread-safe reset. More...

Pub/Sub
template<typename C >
Deduced< ErrorOr< Subscription >, C >	subscribe (Topic topic, EventSlot eventSlot, C &&completion)
	Subscribes to WAMP pub/sub events having the given topic. More...

template<typename C >
Deduced< ErrorOr< Subscription >, C >	subscribe (ThreadSafe, Topic topic, EventSlot eventSlot, C &&completion)
	Thread-safe subscribe. More...

void	unsubscribe (Subscription sub)
	Unsubscribes a subscription to a topic. More...

void	unsubscribe (ThreadSafe, Subscription sub)
	Thread-safe unsubscribe. More...

template<typename C >
Deduced< ErrorOr< bool >, C >	unsubscribe (Subscription sub, C &&completion)
	Unsubscribes a subscription to a topic and waits for router acknowledgement, if necessary. More...

template<typename C >
Deduced< ErrorOr< bool >, C >	unsubscribe (ThreadSafe, Subscription sub, C &&completion)
	Thread-safe acknowledged unsubscribe. More...

void	publish (Pub pub)
	Publishes an event. More...

void	publish (ThreadSafe, Pub pub)
	Thread-safe publish. More...

template<typename C >
Deduced< ErrorOr< PublicationId >, C >	publish (Pub pub, C &&completion)
	Publishes an event and waits for an acknowledgement from the router. More...

template<typename C >
Deduced< ErrorOr< PublicationId >, C >	publish (ThreadSafe, Pub pub, C &&completion)
	Thread-safe acknowledged publish. More...

Remote Procedures
template<typename C >
Deduced< ErrorOr< Registration >, C >	enroll (Procedure procedure, CallSlot callSlot, C &&completion)
	Registers a WAMP remote procedure call. More...

template<typename C >
Deduced< ErrorOr< Registration >, C >	enroll (ThreadSafe, Procedure procedure, CallSlot callSlot, C &&completion)
	Thread-safe enroll. More...

template<typename C >
Deduced< ErrorOr< Registration >, C >	enroll (Procedure procedure, CallSlot callSlot, InterruptSlot interruptSlot, C &&completion)
	Registers a WAMP remote procedure call with an interruption handler. More...

template<typename C >
Deduced< ErrorOr< Registration >, C >	enroll (ThreadSafe, Procedure procedure, CallSlot callSlot, InterruptSlot interruptSlot, C &&completion)
	Thread-safe enroll interruptible. More...

void	unregister (Registration reg)
	Unregisters a remote procedure call. More...

void	unregister (ThreadSafe, Registration reg)
	Thread-safe unregister. More...

template<typename C >
Deduced< ErrorOr< bool >, C >	unregister (Registration reg, C &&completion)
	Unregisters a remote procedure call and waits for router acknowledgement. More...

template<typename C >
Deduced< ErrorOr< bool >, C >	unregister (ThreadSafe, Registration reg, C &&completion)
	Thread-safe acknowledged unregister. More...

template<typename C >
Deduced< ErrorOr< Result >, C >	call (Rpc rpc, C &&completion)
	Calls a remote procedure. More...

template<typename C >
Deduced< ErrorOr< Result >, C >	call (ThreadSafe, Rpc rpc, C &&completion)
	Thread-safe call. More...

template<typename C >
Deduced< ErrorOr< Result >, C >	call (Rpc rpc, CallChit &chit, C &&completion)
	Calls a remote procedure, obtaining a token that can be used for cancellation. More...

template<typename C >
Deduced< ErrorOr< Result >, C >	call (ThreadSafe, Rpc rpc, CallChit &chit, C &&completion)
	Thread-safe call with CallChit capture. More...

void	cancel (CallChit)
	Cancels a remote procedure using the cancel mode that was specified in the Rpc. More...

void	cancel (ThreadSafe, CallChit)
	Thread-safe cancel. More...

void	cancel (CallChit, CallCancelMode mode)
	Cancels a remote procedure using the given mode. More...

void	cancel (ThreadSafe, CallChit, CallCancelMode mode)
	Thread-safe cancel with a given mode. More...

void	cancel (CallCancellation cancellation)
	Cancels a remote procedure. More...

void	cancel (ThreadSafe, CallCancellation cancellation)
	Thread-safe cancel. More...

Static Public Member Functions
static Ptr	create (AnyIoExecutor exec, const Connector::Ptr &connector)
	Creates a new Session instance. More...

static Ptr	create (AnyIoExecutor exec, const ConnectorList &connectors)
	Creates a new Session instance. More...

template<typename TExecutionContext >
static Ptr	create (TExecutionContext &context, const Connector::Ptr &connector)
	Creates a new Session instance. More...

template<typename TExecutionContext >
static Ptr	create (TExecutionContext &context, const ConnectorList &connectors)
	Creates a new Session instance. More...

static const Object &	roles ()
	Obtains a dictionary of roles and features supported on the client side. More...

Detailed Description

Session API used by a client peer in WAMP applications.

Roles

This API supports all of the WAMP client roles:

Callee
Caller
Publisher
Subscriber

Asynchronous Operations: Most of Session's member functions are asynchronous and thus require a completion token that is invoked when the operation is completed. All asynchronous operations emit an ErrorOr as the result. ErrorOr makes it difficult for handlers to ignore error conditions when accessing the result of an asynchronous operation.

Note: In the detailed documentation of asynchronous operations, items listed under Returns refer to results that are emitted via ErrorOr.

The boost::asio::io_context passed via create() is used when executing handler functions passed-in by the user. This can be the same, or different than the io_context passed to the Connector creation functions.

Aborting Asynchronous Operations: All pending asynchronous operations can be aborted by dropping the client connection via Session::disconnect. Pending post-join operations can be also be aborted via Session::leave. There is currently no way to abort a single operation without dropping the connection or leaving the realm.

Terminating Asynchronous Operations: All pending asynchronous operations can be terminated by dropping the client connection via Session::reset or the Session destructor. By design, the handlers for pending operations will not be invoked if they were terminated in this way (this will result in hung coroutine operations). This is useful if a client application needs to shutdown abruptly and cannot enforce the lifetime of objects accessed within the asynchronous operation handlers.

Thread-safety: Undecorated methods must be called within the Session's execution strand. If the same io_context is used by a single-threaded app and a Session's transport, calls to undecorated methods will implicitly be within the Session's strand. If invoked from other threads, calls to undecorated methods must be executed via boost::asio::dispatch(session->stand(), operation). Session methods decorated with the ThreadSafe tag type may be safely used concurrently by multiple threads. These decorated methods take care of executing operations via a Session's strand so that they become sequential.

See also: ErrorOr, Registration, Subscription.

Member Typedef Documentation

◆ Deduced

template<typename T , typename C >

using wamp::Session::Deduced = decltype( boost::asio::async_initiate<C, void(T)>(std::declval<GenericOp&>(), std::declval<C&>()))

Obtains the type returned by boost::asio::async_initiate with given the completion token type C and signature void(T).

Token Type	Deduced Return Type
Callback function	`void`
`boost::asio::yield_context`	`ErrorOr<Value>`
`boost::asio::use_awaitable`	An awaitable yielding `ErrorOr<Value>`
`boost::asio::use_future`	`std::future<ErrorOr<Value>>`

Constructor & Destructor Documentation

◆ ~Session()

wamp::Session::~Session ( )

virtual

Destructor.

Automatically invokes reset() on the session, which drops the connection and terminates all pending asynchronous operations.

Member Function Documentation

◆ create() [1/4]

Session::Ptr wamp::Session::create	(	AnyIoExecutor	exec,
		const Connector::Ptr &	connector
	)

static

Creates a new Session instance.

The provided executor serves as a fallback when asynchronous operation handlers don't bind a specific executor (in lieu of using the system executor as fallback.

Postcondition: session->state() == SessionState::disconnected

Returns: A shared pointer to the created session object.

Parameters

exec	Fallback executor with which to execute user-provided handlers.
connector	Connection details for the transport to use.

Examples: examples/asynctimeclient/main.cpp, examples/asynctimeservice/main.cpp, examples/coro20timeclient/main.cpp, examples/coro20timeservice/main.cpp, examples/futuretimeclient/main.cpp, examples/futuretimeservice/main.cpp, examples/stacklesstimeclient/main.cpp, examples/stacklesstimeservice/main.cpp, examples/timeclient/main.cpp, and examples/timeservice/main.cpp.

◆ create() [2/4]

Session::Ptr wamp::Session::create	(	AnyIoExecutor	exec,
		const ConnectorList &	connectors
	)

static

Creates a new Session instance.

The provided executor serves as a fallback when asynchronous operation handlers don't bind a specific executor (in lieu of using the system executor as fallback.

Precondition: connectors.empty() == false

Postcondition: session->state() == SessionState::disconnected

Returns: A shared pointer to the created Session object.

Exceptions

error::Logic if connectors.empty() == true

Parameters

exec	Fallback executor with which to execute user-provided handlers.
connectors	A list of connection details for the transports to use.

◆ create() [3/4]

template<typename TExecutionContext >

static Ptr wamp::Session::create	(	TExecutionContext &	context,
		const Connector::Ptr &	connector
	)

inlinestatic

Creates a new Session instance.

The provided executor serves as a fallback when asynchronous operation handlers don't bind a specific executor (in lieu of using the system executor as fallback.

Postcondition: session->state() == SessionState::disconnected

Returns: A shared pointer to the created session object.

Only participates in overload resolution when isExecutionContext<TExecutionContext>() == true

Template Parameters

TExecutionContext Must meet the requirements of Boost.Asio's ExecutionContext

Parameters

context	Provides executor with which to post all user-provided handlers.
connector	Connection details for the transport to use.

◆ create() [4/4]

template<typename TExecutionContext >

static Ptr wamp::Session::create	(	TExecutionContext &	context,
		const ConnectorList &	connectors
	)

inlinestatic

Creates a new Session instance.

The provided executor serves as a fallback when asynchronous operation handlers don't bind a specific executor (in lieu of using the system executor as fallback.

Precondition: connectors.empty() == false

Postcondition: session->state() == SessionState::disconnected

Returns: A shared pointer to the created Session object.

Exceptions

error::Logic if connectors.empty() == true

Only participates in overload resolution when isExecutionContext<TExecutionContext>() == true

Template Parameters

TExecutionContext Must meet the requirements of Boost.Asio's ExecutionContext

Parameters

context	Provides executor with which to post all user-provided handlers.
connectors	Connection details for the transport to use.

◆ roles()

const Object & wamp::Session::roles ( )

static

Obtains a dictionary of roles and features supported on the client side.

The dictionary is structured as per HELLO.Details.roles, as desribed in the "Client: Role and Feature Announcement" section of the advanced WAMP specification.

◆ userIosvc()

AnyIoExecutor wamp::Session::userIosvc ( ) const

Legacy function kept for backward compatiblity.

Deprecated:: Use wamp::Session::userExecutor instead.

◆ setWarningHandler() [1/2]

void wamp::Session::setWarningHandler ( LogHandler handler )

Sets the log handler that is dispatched for warnings.

Warnings occur when the session encounters problems that do not prevent it from proceeding normally. An example of such warnings is when a peer attempts to send an event with arguments that does not match the types of a statically-typed event slot.

By default, warnings are discarded.

Parameters

handler Callable handler of type `<void (std::string)>`.

◆ setWarningHandler() [2/2]

void wamp::Session::setWarningHandler	(	ThreadSafe	,
		LogHandler	handler
	)

Thread-safe setting of warning handler.

Warnings occur when the session encounters problems that do not prevent it from proceeding normally. An example of such warnings is when a peer attempts to send an event with arguments that does not match the types of a statically-typed event slot.

By default, warnings are discarded.

Parameters

handler Callable handler of type `<void (std::string)>`.

◆ setTraceHandler() [1/2]

void wamp::Session::setTraceHandler ( LogHandler handler )

Sets the log handler that is dispatched for debug traces.

By default, debug traces are discarded.

Parameters

handler Callable handler of type `<void (std::string)>`.

◆ setTraceHandler() [2/2]

void wamp::Session::setTraceHandler	(	ThreadSafe	,
		LogHandler	handler
	)

Thread-safe setting of trace handler.

By default, debug traces are discarded.

Parameters

handler Callable handler of type `<void (std::string)>`.

◆ setStateChangeHandler() [1/2]

void wamp::Session::setStateChangeHandler ( StateChangeHandler handler )

Sets the handler that is posted for session state changes.

Note: No state change events are fired when the session object is destructing.

Parameters

handler Callable handler of type `<void (SessionState)>`.

◆ setStateChangeHandler() [2/2]

void wamp::Session::setStateChangeHandler	(	ThreadSafe	,
		StateChangeHandler	handler
	)

Thread-safe setting of state change handler.

Note: No state change events are fired when the session object is destructing.

Parameters

handler Callable handler of type `<void (SessionState)>`.

◆ setChallengeHandler() [1/2]

void wamp::Session::setChallengeHandler ( ChallengeHandler handler )

Sets the handler that is dispatched for authentication challenges.

Parameters

handler Callable handler of type `<void (Challenge)>`.

◆ setChallengeHandler() [2/2]

void wamp::Session::setChallengeHandler	(	ThreadSafe	,
		ChallengeHandler	handler
	)

Thread-safe setting of state change handler.

Parameters

handler Callable handler of type `<void (Challenge)>`.

◆ connect() [1/2]

template<typename C >

Deduced< ErrorOr< std::size_t >, C > wamp::Session::connect ( C && completion )

Asynchronously attempts to connect to a router.

The session will attempt to connect using the transports that were specified by the wamp::Connector objects passed during create(). If more than one transport was specified, they will be traversed in the same order as they appeared in the ConnectorList.

Returns: The index of the Connector object used to establish the connetion.

Postcondition: this->state() == SessionState::connecting if successful

Error Codes

TransportErrc::aborted if the connection attempt was aborted.
SessionErrc::allTransportsFailed if more than one transport was specified and they all failed to connect.
SessionErrc::invalidState if the session was not disconnected before the attempt to connect.
Some other platform or transport-dependent std::error_code if only one transport was specified and it failed to connect.

Parameters

completion A callable handler of type `void(ErrorOr<size_t>)`, or a compatible Boost.Asio completion token.

◆ connect() [2/2]

template<typename C >

Deduced< ErrorOr< std::size_t >, C > wamp::Session::connect	(	ThreadSafe	,
		C &&	completion
	)

Thread-safe connect.

The session will attempt to connect using the transports that were specified by the wamp::Connector objects passed during create(). If more than one transport was specified, they will be traversed in the same order as they appeared in the ConnectorList.

Returns: The index of the Connector object used to establish the connetion.

Postcondition: this->state() == SessionState::connecting if successful

Error Codes

TransportErrc::aborted if the connection attempt was aborted.
SessionErrc::allTransportsFailed if more than one transport was specified and they all failed to connect.
SessionErrc::invalidState if the session was not disconnected before the attempt to connect.
Some other platform or transport-dependent std::error_code if only one transport was specified and it failed to connect.

Parameters

completion A callable handler of type void(ErrorOr<size_t>), or a compatible Boost.Asio completion token.

◆ join() [1/2]

template<typename C >

Deduced< ErrorOr< SessionInfo >, C > wamp::Session::join	(	Realm	realm,
		C &&	completion
	)

Asynchronously attempts to join the given WAMP realm.

Returns: A SessionInfo object with details on the newly established session.

Parameters

completion A callable handler of type void(ErrorOr<SessionInfo>), or a compatible Boost.Asio completion token.

Postcondition: this->state() == SessionState::establishing if successful

Error Codes

SessionErrc::invalidState if the session was not closed before the attempt to join.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer.
SessionErrc::noSuchRealm if the realm does not exist.
SessionErrc::noSuchRole if one of the client roles is not supported on the router.
SessionErrc::joinError for other errors reported by the router.
Some other std::error_code for protocol and transport errors.

Parameters

realm	Details on the realm to join.
completion	Callable handler of type `void(ErrorOr<SessionInfo>)`, or a compatible Boost.Asio completion token.

◆ join() [2/2]

template<typename C >

Deduced< ErrorOr< SessionInfo >, C > wamp::Session::join	(	ThreadSafe	,
		Realm	realm,
		C &&	completion
	)

Thread-safe join.

Returns: A SessionInfo object with details on the newly established session.

Parameters

completion A callable handler of type void(ErrorOr<SessionInfo>), or a compatible Boost.Asio completion token.

Postcondition: this->state() == SessionState::establishing if successful

Error Codes

SessionErrc::invalidState if the session was not closed before the attempt to join.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer.
SessionErrc::noSuchRealm if the realm does not exist.
SessionErrc::noSuchRole if one of the client roles is not supported on the router.
SessionErrc::joinError for other errors reported by the router.
Some other std::error_code for protocol and transport errors.

Parameters

realm	Details on the realm to join.
completion	Callable handler of type `void(ErrorOr<SessionInfo>)`, or a compatible Boost.Asio completion token.

◆ authenticate() [1/2]

void wamp::Session::authenticate ( Authentication auth )

Sends an AUTHENTICATE in response to a CHALLENGE.

If this->state() != SessionState::authenticating, then the authentication is discarded and not sent.

Parameters

auth	Contains the authentication signature and other options.

◆ authenticate() [2/2]

void wamp::Session::authenticate	(	ThreadSafe	,
		Authentication	auth
	)

Thread-safe authenticate.

If this->state() != SessionState::authenticating, then the authentication is discarded and not sent.

Parameters

auth	Contains the authentication signature and other options.

◆ leave() [1/4]

template<typename C >

Deduced< ErrorOr< Reason >, C > wamp::Session::leave ( C && completion )

Asynchronously leaves the WAMP session.

The "wamp.close.close_realm" reason is sent as part of the outgoing GOODBYE message.

Returns: The Reason URI and details from the GOODBYE response returned by the router.

Postcondition: this->state() == SessionState::shuttingDown if successful

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to leave.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer before a GOODBYE response was received.
Some other std::error_code for protocol and transport errors.

Parameters

completion Callable handler of type `void(ErrorOr<Reason>)`, or a compatible Boost.Asio completion token.

◆ leave() [2/4]

template<typename C >

Deduced< ErrorOr< Reason >, C > wamp::Session::leave	(	ThreadSafe	,
		C &&	completion
	)

Thread-safe leave.

The "wamp.close.close_realm" reason is sent as part of the outgoing GOODBYE message.

Returns: The Reason URI and details from the GOODBYE response returned by the router.

Postcondition: this->state() == SessionState::shuttingDown if successful

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to leave.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer before a GOODBYE response was received.
Some other std::error_code for protocol and transport errors.

Parameters

completion Callable handler of type `void(ErrorOr<Reason>)`, or a compatible Boost.Asio completion token.

◆ leave() [3/4]

template<typename C >

Deduced< ErrorOr< Reason >, C > wamp::Session::leave	(	Reason	reason,
		C &&	completion
	)

Asynchronously leaves the WAMP session with the given reason.

Returns: The Reason URI and details from the GOODBYE response returned by the router.

Postcondition: this->state() == SessionState::shuttingDown if successful

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to leave.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer before a GOODBYE response was received.
Some other std::error_code for protocol and transport errors.

Parameters

reason	Reason URI and other options
completion	Callable handler of type `void(ErrorOr<Reason>)`, or a compatible Boost.Asio completion token.

◆ leave() [4/4]

template<typename C >

Deduced< ErrorOr< Reason >, C > wamp::Session::leave	(	ThreadSafe	,
		Reason	reason,
		C &&	completion
	)

Thread-safe leave with reason.

Returns: The Reason URI and details from the GOODBYE response returned by the router.

Postcondition: this->state() == SessionState::shuttingDown if successful

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to leave.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer before a GOODBYE response was received.
Some other std::error_code for protocol and transport errors.

Parameters

reason	Reason URI and other options
completion	Callable handler of type `void(ErrorOr<Reason>)`, or a compatible Boost.Asio completion token.

◆ disconnect() [1/2]

void wamp::Session::disconnect ( )

Disconnects the transport between the client and router.

Aborts all pending asynchronous operations, invoking their handlers with error codes indicating that cancellation has occured.

Postcondition: this->state() == SessionState::disconnected

◆ disconnect() [2/2]

void wamp::Session::disconnect ( ThreadSafe )

Thread-safe disconnect.

Aborts all pending asynchronous operations, invoking their handlers with error codes indicating that cancellation has occured.

Postcondition: this->state() == SessionState::disconnected

◆ reset() [1/2]

void wamp::Session::reset ( )

Terminates the transport connection between the client and router.

Terminates all pending asynchronous operations, which does not invoke their handlers. This is useful when a client application needs to shutdown abruptly and cannot enforce the lifetime of objects accessed within the asynchronous operation handlers.

Postcondition: this->state() == SessionState::disconnected

◆ reset() [2/2]

void wamp::Session::reset ( ThreadSafe )

Thread-safe reset.

Terminates all pending asynchronous operations, which does not invoke their handlers. This is useful when a client application needs to shutdown abruptly and cannot enforce the lifetime of objects accessed within the asynchronous operation handlers.

Postcondition: this->state() == SessionState::disconnected

◆ subscribe() [1/2]

template<typename C >

Deduced< ErrorOr< Subscription >, C > wamp::Session::subscribe	(	Topic	topic,
		EventSlot	eventSlot,
		C &&	completion
	)

Subscribes to WAMP pub/sub events having the given topic.

See also: Subscriptions

Returns: A Subscription object, therafter used to manage the subscription's lifetime.

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to subscribe.
SessionErrc::subscribeError if the router replied with an ERROR response.
Some other std::error_code for protocol and transport errors.

Parameters

topic	The topic to subscribe to.
eventSlot	Callable handler of type `void (Event)` to execute when a matching event is received.
completion	Callable handler of type `void(ErrorOr<Subscription>)`, or a compatible Boost.Asio completion token.

◆ subscribe() [2/2]

template<typename C >

Deduced< ErrorOr< Subscription >, C > wamp::Session::subscribe	(	ThreadSafe	,
		Topic	topic,
		EventSlot	eventSlot,
		C &&	completion
	)

Thread-safe subscribe.

See also: Subscriptions

Returns: A Subscription object, therafter used to manage the subscription's lifetime.

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to subscribe.
SessionErrc::subscribeError if the router replied with an ERROR response.
Some other std::error_code for protocol and transport errors.

Parameters

topic	The topic to subscribe to.
eventSlot	Callable handler of type `void (Event)` to execute when a matching event is received.
completion	Callable handler of type `void(ErrorOr<Subscription>)`, or a compatible Boost.Asio completion token.

◆ unsubscribe() [1/4]

void wamp::Session::unsubscribe ( Subscription sub )

Unsubscribes a subscription to a topic.

This function can be safely called during any session state. If the subscription is no longer applicable, then the unsubscribe operation will effectively do nothing.

See also: Subscription, ScopedSubscription

Note: Duplicate unsubscribes using the same Subscription object are safely ignored.

Precondition: bool(sub) == true

Exceptions

error::Logic if the given subscription is empty

Parameters

sub	The subscription to unsubscribe from.

◆ unsubscribe() [2/4]

void wamp::Session::unsubscribe	(	ThreadSafe	,
		Subscription	sub
	)

Thread-safe unsubscribe.

This function can be safely called during any session state. If the subscription is no longer applicable, then the unsubscribe operation will effectively do nothing.

See also: Subscription, ScopedSubscription

Note: Duplicate unsubscribes using the same Subscription object are safely ignored.

Precondition: bool(sub) == true

Exceptions

error::Logic if the given subscription is empty

Parameters

sub	The subscription to unsubscribe from.

◆ unsubscribe() [3/4]

template<typename C >

Deduced< ErrorOr< bool >, C > wamp::Session::unsubscribe	(	Subscription	sub,
		C &&	completion
	)

Unsubscribes a subscription to a topic and waits for router acknowledgement, if necessary.

If there are other local subscriptions on this session remaining for the same topic, then the session does not send an UNSUBSCRIBE message to the router.

See also: Subscription, ScopedSubscription

Returns: false if the subscription was already removed, true otherwise.

Note: Duplicate unsubscribes using the same Subscription handle are safely ignored.

Precondition: !!sub == true

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to unsubscribe.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer.
SessionErrc::noSuchSubscription if the router reports that there was no such subscription.
SessionErrc::unsubscribeError if the router reports some other error.
Some other std::error_code for protocol and transport errors.

Exceptions

error::Logic if the given subscription is empty

Parameters

sub	The subscription to unsubscribe from.
completion	Callable handler of type `void(ErrorOr<bool>)`, or a compatible Boost.Asio completion token.

◆ unsubscribe() [4/4]

template<typename C >

Deduced< ErrorOr< bool >, C > wamp::Session::unsubscribe	(	ThreadSafe	,
		Subscription	sub,
		C &&	completion
	)

Thread-safe acknowledged unsubscribe.

If there are other local subscriptions on this session remaining for the same topic, then the session does not send an UNSUBSCRIBE message to the router.

See also: Subscription, ScopedSubscription

Returns: false if the subscription was already removed, true otherwise.

Note: Duplicate unsubscribes using the same Subscription handle are safely ignored.

Precondition: !!sub == true

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to unsubscribe.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer.
SessionErrc::noSuchSubscription if the router reports that there was no such subscription.
SessionErrc::unsubscribeError if the router reports some other error.
Some other std::error_code for protocol and transport errors.

Exceptions

error::Logic if the given subscription is empty

Parameters

sub	The subscription to unsubscribe from.
completion	Callable handler of type `void(ErrorOr<bool>)`, or a compatible Boost.Asio completion token.

◆ publish() [1/4]

void wamp::Session::publish ( Pub pub )

Publishes an event.

If this->state() != SessionState::established, then the publication is discarded and not sent.

Parameters

pub	The publication to publish.

◆ publish() [2/4]

void wamp::Session::publish	(	ThreadSafe	,
		Pub	pub
	)

Thread-safe publish.

If this->state() != SessionState::established, then the publication is discarded and not sent.

Parameters

pub	The publication to publish.

◆ publish() [3/4]

template<typename C >

Deduced< ErrorOr< PublicationId >, C > wamp::Session::publish	(	Pub	pub,
		C &&	completion
	)

Publishes an event and waits for an acknowledgement from the router.

Returns: The publication ID for this event.

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to publish.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer.
SessionErrc::publishError if the router replies with an ERROR response.
Some other std::error_code for protocol and transport errors.

Parameters

pub	The publication to publish.
completion	Callable handler of type `void(ErrorOr<PublicationId>)`, or a compatible Boost.Asio completion token.

◆ publish() [4/4]

template<typename C >

Deduced< ErrorOr< PublicationId >, C > wamp::Session::publish	(	ThreadSafe	,
		Pub	pub,
		C &&	completion
	)

Thread-safe acknowledged publish.

Returns: The publication ID for this event.

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to publish.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer.
SessionErrc::publishError if the router replies with an ERROR response.
Some other std::error_code for protocol and transport errors.

Parameters

pub	The publication to publish.
completion	Callable handler of type `void(ErrorOr<PublicationId>)`, or a compatible Boost.Asio completion token.

◆ enroll() [1/4]

template<typename C >

Deduced< ErrorOr< Registration >, C > wamp::Session::enroll	(	Procedure	procedure,
		CallSlot	callSlot,
		C &&	completion
	)

Registers a WAMP remote procedure call.

See also: Registrations

Returns: A Registration object, therafter used to manage the registration's lifetime.

Note: This function was named enroll because register is a reserved C++ keyword.

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to enroll.
SessionErrc::procedureAlreadyExists if the router reports that the procedure has already been registered for this realm.
SessionErrc::registerError if the router reports some other error.
Some other std::error_code for protocol and transport errors.

Parameters

procedure	The procedure to register.
callSlot	Callable handler of type `Outcome (Invocation)` to execute when the RPC is invoked.
completion	Callable handler of type 'void(ErrorOr<Registration>)', or a compatible Boost.Asio completion token.

◆ enroll() [2/4]

template<typename C >

Deduced< ErrorOr< Registration >, C > wamp::Session::enroll	(	ThreadSafe	,
		Procedure	procedure,
		CallSlot	callSlot,
		C &&	completion
	)

Thread-safe enroll.

See also: Registrations

Returns: A Registration object, therafter used to manage the registration's lifetime.

Note: This function was named enroll because register is a reserved C++ keyword.

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to enroll.
SessionErrc::procedureAlreadyExists if the router reports that the procedure has already been registered for this realm.
SessionErrc::registerError if the router reports some other error.
Some other std::error_code for protocol and transport errors.

Parameters

procedure	The procedure to register.
callSlot	Callable handler of type `Outcome (Invocation)` to execute when the RPC is invoked.
completion	Callable handler of type 'void(ErrorOr<Registration>)', or a compatible Boost.Asio completion token.

◆ enroll() [3/4]

template<typename C >

Deduced< ErrorOr< Registration >, C > wamp::Session::enroll	(	Procedure	procedure,
		CallSlot	callSlot,
		InterruptSlot	interruptSlot,
		C &&	completion
	)

Registers a WAMP remote procedure call with an interruption handler.

See also: Registrations

Returns: A Registration object, therafter used to manage the registration's lifetime.

Note: This function was named enroll because register is a reserved C++ keyword.

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to enroll.
SessionErrc::procedureAlreadyExists if the router reports that the procedure has already been registered for this realm.
SessionErrc::registerError if the router reports some other error.
Some other std::error_code for protocol and transport errors.

Parameters

procedure	The procedure to register.
callSlot	Callable handler of type `Outcome (Invocation)` to execute when the RPC is invoked.
interruptSlot	Callable handler of type `Outcome (Invocation)` to execute when the RPC is interrupted.
completion	Callable handler of type `void(ErrorOr<Registration>)`, or a compatible Boost.Asio completion token.

◆ enroll() [4/4]

template<typename C >

Deduced< ErrorOr< Registration >, C > wamp::Session::enroll	(	ThreadSafe	,
		Procedure	procedure,
		CallSlot	callSlot,
		InterruptSlot	interruptSlot,
		C &&	completion
	)

Thread-safe enroll interruptible.

See also: Registrations

Returns: A Registration object, therafter used to manage the registration's lifetime.

Note: This function was named enroll because register is a reserved C++ keyword.

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to enroll.
SessionErrc::procedureAlreadyExists if the router reports that the procedure has already been registered for this realm.
SessionErrc::registerError if the router reports some other error.
Some other std::error_code for protocol and transport errors.

Parameters

procedure	The procedure to register.
callSlot	Callable handler of type `Outcome (Invocation)` to execute when the RPC is invoked.
interruptSlot	Callable handler of type `Outcome (Invocation)` to execute when the RPC is interrupted.
completion	Callable handler of type 'void(ErrorOr<Registration>)', or a compatible Boost.Asio completion token.

◆ unregister() [1/4]

void wamp::Session::unregister ( Registration reg )

Unregisters a remote procedure call.

This function can be safely called during any session state. If the registration is no longer applicable, then the unregister operation will effectively do nothing.

See also: Registration, ScopedRegistration

Note: Duplicate unregistrations using the same Registration handle are safely ignored.

Precondition: bool(reg) == true

Exceptions

error::Logic if the given registration is empty

Parameters

reg	The RPC registration to unregister.

◆ unregister() [2/4]

void wamp::Session::unregister	(	ThreadSafe	,
		Registration	reg
	)

Thread-safe unregister.

This function can be safely called during any session state. If the registration is no longer applicable, then the unregister operation will effectively do nothing.

See also: Registration, ScopedRegistration

Note: Duplicate unregistrations using the same Registration handle are safely ignored.

Precondition: bool(reg) == true

Exceptions

error::Logic if the given registration is empty

Parameters

reg	The RPC registration to unregister.

◆ unregister() [3/4]

template<typename C >

Deduced< ErrorOr< bool >, C > wamp::Session::unregister	(	Registration	reg,
		C &&	completion
	)

Unregisters a remote procedure call and waits for router acknowledgement.

See also: Registration, ScopedRegistration

Returns: false if the registration was already removed, true otherwise.

Note: Duplicate unregistrations using the same Registration handle are safely ignored.

Precondition: !!reg == true

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to unregister.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer.
SessionErrc::noSuchRegistration if the router reports that there is no such procedure registered by that name.
SessionErrc::unregisterError if the router reports some other error.
Some other std::error_code for protocol and transport errors.

Exceptions

error::Logic if the given registration is empty

Parameters

reg	The RPC registration to unregister.
completion	Callable handler of type `void(ErrorOr<bool>)`, or a compatible Boost.Asio completion token.

◆ unregister() [4/4]

template<typename C >

Deduced< ErrorOr< bool >, C > wamp::Session::unregister	(	ThreadSafe	,
		Registration	reg,
		C &&	completion
	)

Thread-safe acknowledged unregister.

See also: Registration, ScopedRegistration

Returns: false if the registration was already removed, true otherwise.

Note: Duplicate unregistrations using the same Registration handle are safely ignored.

Precondition: !!reg == true

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to unregister.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer.
SessionErrc::noSuchRegistration if the router reports that there is no such procedure registered by that name.
SessionErrc::unregisterError if the router reports some other error.
Some other std::error_code for protocol and transport errors.

Exceptions

error::Logic if the given registration is empty

Parameters

reg	The RPC registration to unregister.
completion	Callable handler of type `void(ErrorOr<bool>)`, or a compatible Boost.Asio completion token.

◆ call() [1/4]

template<typename C >

Deduced< ErrorOr< Result >, C > wamp::Session::call	(	Rpc	rpc,
		C &&	completion
	)

Calls a remote procedure.

Returns: The remote procedure result.

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to call.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer.
SessionErrc::noSuchProcedure if the router reports that there is no such procedure registered by that name.
SessionErrc::invalidArgument if the callee reports that there are one or more invalid arguments.
SessionErrc::callError if the router reports some other error.
Some other std::error_code for protocol and transport errors.

Note: If progressive results are enabled, then the given (or generated) completion handler must be copy-constructible so that it can be executed multiple times (checked at runtime).

Precondition: rpc.withProgressiveResults() == false || std::is_copy_constructible_v<std::remove_cvref_t<C>>

Exceptions

error::Logic if progressive results are enabled but the given (or generated) completion handler is not copy-constructible.

Parameters

rpc	Details about the RPC.
completion	Callable handler of type `void(ErrorOr<Result>)`, or a compatible Boost.Asio completion token.

◆ call() [2/4]

template<typename C >

Deduced< ErrorOr< Result >, C > wamp::Session::call	(	ThreadSafe	,
		Rpc	rpc,
		C &&	completion
	)

Thread-safe call.

Returns: The remote procedure result.

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to call.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer.
SessionErrc::noSuchProcedure if the router reports that there is no such procedure registered by that name.
SessionErrc::invalidArgument if the callee reports that there are one or more invalid arguments.
SessionErrc::callError if the router reports some other error.
Some other std::error_code for protocol and transport errors.

Note: If progressive results are enabled, then the given (or generated) completion handler must be copy-constructible so that it can be executed multiple times (checked at runtime).

Precondition: rpc.withProgressiveResults() == false || std::is_copy_constructible_v<std::remove_cvref_t<C>>

Exceptions

error::Logic if progressive results are enabled but the given (or generated) completion handler is not copy-constructible.

Parameters

rpc	Details about the RPC.
completion	Callable handler of type `void(ErrorOr<Result>)`, or a compatible Boost.Asio completion token.

◆ call() [3/4]

template<typename C >

Deduced< ErrorOr< Result >, C > wamp::Session::call	(	Rpc	rpc,
		CallChit &	chit,
		C &&	completion
	)

Calls a remote procedure, obtaining a token that can be used for cancellation.

Returns: The remote procedure result.

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to call.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer.
SessionErrc::noSuchProcedure if the router reports that there is no such procedure registered by that name.
SessionErrc::invalidArgument if the callee reports that there are one or more invalid arguments.
SessionErrc::callError if the router reports some other error.
Some other std::error_code for protocol and transport errors.

Note: If progressive results are enabled, then the given (or generated) completion handler must be copy-constructible so that it can be executed multiple times (checked at runtime).

Precondition: rpc.withProgressiveResults() == false || std::is_copy_constructible_v<std::remove_cvref_t<C>>

Exceptions

error::Logic if progressive results are enabled but the given (or generated) completion handler is not copy-constructible.

Parameters

	rpc	Details about the RPC.
[out]	chit	[out] Token that can be used to cancel the RPC.
	completion	Callable handler of type `void(ErrorOr<Result>)`, or a compatible Boost.Asio completion token.

◆ call() [4/4]

template<typename C >

Deduced< ErrorOr< Result >, C > wamp::Session::call	(	ThreadSafe	,
		Rpc	rpc,
		CallChit &	chit,
		C &&	completion
	)

Thread-safe call with CallChit capture.

Returns: The remote procedure result.

Error Codes

SessionErrc::invalidState if the session was not established before the attempt to call.
SessionErrc::sessionEnded if the operation was aborted.
SessionErrc::sessionEndedByPeer if the session was ended by the peer.
SessionErrc::noSuchProcedure if the router reports that there is no such procedure registered by that name.
SessionErrc::invalidArgument if the callee reports that there are one or more invalid arguments.
SessionErrc::callError if the router reports some other error.
Some other std::error_code for protocol and transport errors.

Note: If progressive results are enabled, then the given (or generated) completion handler must be copy-constructible so that it can be executed multiple times (checked at runtime).

Precondition: rpc.withProgressiveResults() == false || std::is_copy_constructible_v<std::remove_cvref_t<C>>

Exceptions

error::Logic if progressive results are enabled but the given (or generated) completion handler is not copy-constructible.

Parameters

	rpc	Details about the RPC.
[out]	chit	[out] Token that can be used to cancel the RPC.
	completion	Callable handler of type `void(ErrorOr<Result>)`, or a compatible Boost.Asio completion token.

◆ cancel() [1/6]

void wamp::Session::cancel ( CallChit chit )

Cancels a remote procedure using the cancel mode that was specified in the Rpc.

If this->state() != SessionState::established, then the cancellation is discarded and not sent.

Parameters

chit	Contains the request ID of the call to cancel.

◆ cancel() [2/6]

void wamp::Session::cancel	(	ThreadSafe	,
		CallChit	chit
	)

Thread-safe cancel.

If this->state() != SessionState::established, then the cancellation is discarded and not sent.

Parameters

chit	Contains the request ID of the call to cancel.

◆ cancel() [3/6]

void wamp::Session::cancel	(	CallChit	chit,
		CallCancelMode	mode
	)

Cancels a remote procedure using the given mode.

If this->state() != SessionState::established, then the cancellation is discarded and not sent.

Parameters

chit	Contains the request ID of the call to cancel.
mode	The mode with which to cancel the call.

◆ cancel() [4/6]

void wamp::Session::cancel	(	ThreadSafe	,
		CallChit	chit,
		CallCancelMode	mode
	)

Thread-safe cancel with a given mode.

If this->state() != SessionState::established, then the cancellation is discarded and not sent.

Parameters

chit	Contains the request ID of the call to cancel.
mode	The mode with which to cancel the call.

◆ cancel() [5/6]

void wamp::Session::cancel ( CallCancellation cancellation )

Cancels a remote procedure.

Deprecated:: Use the overload taking a CallChit.

If this->state() != SessionState::established, then the cancellation is discarded and not sent.

Parameters

cancellation Contains the request ID and other options.

◆ cancel() [6/6]

void wamp::Session::cancel	(	ThreadSafe	,
		CallCancellation	cancellation
	)

Thread-safe cancel.

Deprecated:: Use the overload taking a CallChit.

If this->state() != SessionState::established, then the cancellation is discarded and not sent.

Parameters

cancellation Contains the request ID and other options.

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

cppwamp/session.hpp
cppwamp/internal/session.ipp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Deduced

Constructor & Destructor Documentation

◆ ~Session()

Member Function Documentation

◆ create() [1/4]

◆ create() [2/4]

◆ create() [3/4]

◆ create() [4/4]

◆ roles()

◆ userIosvc()

◆ setWarningHandler() [1/2]

◆ setWarningHandler() [2/2]

◆ setTraceHandler() [1/2]

◆ setTraceHandler() [2/2]

◆ setStateChangeHandler() [1/2]

◆ setStateChangeHandler() [2/2]

◆ setChallengeHandler() [1/2]

◆ setChallengeHandler() [2/2]

◆ connect() [1/2]

◆ connect() [2/2]

◆ join() [1/2]

◆ join() [2/2]

◆ authenticate() [1/2]

◆ authenticate() [2/2]

◆ leave() [1/4]

◆ leave() [2/4]

◆ leave() [3/4]

◆ leave() [4/4]

◆ disconnect() [1/2]

◆ disconnect() [2/2]

◆ reset() [1/2]

◆ reset() [2/2]

◆ subscribe() [1/2]

◆ subscribe() [2/2]

◆ unsubscribe() [1/4]

◆ unsubscribe() [2/4]

◆ unsubscribe() [3/4]

◆ unsubscribe() [4/4]

◆ publish() [1/4]

◆ publish() [2/4]

◆ publish() [3/4]

◆ publish() [4/4]

◆ enroll() [1/4]

◆ enroll() [2/4]

◆ enroll() [3/4]

◆ enroll() [4/4]

◆ unregister() [1/4]

◆ unregister() [2/4]

◆ unregister() [3/4]

◆ unregister() [4/4]

◆ call() [1/4]

◆ call() [2/4]

◆ call() [3/4]

◆ call() [4/4]

◆ cancel() [1/6]

◆ cancel() [2/6]

◆ cancel() [3/6]

◆ cancel() [4/6]

◆ cancel() [5/6]

◆ cancel() [6/6]