ditto::Presence Class Reference

#include <Presence.hpp>

Public Member Functions
PresenceObserver	observe (PresenceCallback presence_cb)
	This will run the provided callback when peers are updated.
DITTO_DEPRECATED PresenceGraph	exec ()
	Deprecated alias of graph()
PresenceGraph	graph ()
	Return an immediate representation of known peers.
nlohmann::json	peer_metadata () const
	Metadata associated with the current peer.
void	set_peer_metadata (nlohmann::json const &peer_metadata)
	Set arbitrary metadata to be associated with the current peer.
std::string	peer_metadata_json_string () const
	Metadata associated with the current peer as a JSON string.
void	set_peer_metadata_json_string (std::string json_string)
	Set arbitrary metadata formatted as JSON to be associated with the current peer.
void	set_connection_request_handler (ConnectionRequestHandler connection_request_handler)
	Set this handler to control which peers in a Ditto mesh can connect to the current peer.
void	set_connection_request_handler (std::nullptr_t)
	Unset the connection request handler, if one was previously set, replacing it with the default all-allowing one.

Detailed Description

Presence allows peers in the mesh to be monitored.

Member Function Documentation

exec()

PresenceGraph ditto::Presence::exec

(

)

Deprecated alias of graph()

Deprecated

Use graph() instead.

graph()

PresenceGraph ditto::Presence::graph

(

)

Return an immediate representation of known peers.

Returns

PresenceGraph graph of known peers.

observe()

PresenceObserver ditto::Presence::observe

(

PresenceCallback

presence_cb

)

This will run the provided callback when peers are updated.

Parameters

presence_cb

callback that will be run when the peers are updated

Returns

PresenceObserver handle to drop to stop observing peers.

peer_metadata()

nlohmann::json ditto::Presence::peer_metadata

(

)

const

Metadata associated with the current peer.

Other peers in the same mesh can access this user-provided dictionary of metadata via the presence graph at Presence::exec and when evaluating connection requests using connection_request_handler. Use set_peer_metadata or set_peer_metadata_json_string to set this value.

This is not made available to peers only connected via WebSocket.

This is a convenience wrapper around peer_metadata_json_string.

Returns

a map of metadata associated with the current peer.

peer_metadata_json_string()

std::string ditto::Presence::peer_metadata_json_string

(

)

const

Metadata associated with the current peer as a JSON string.

Other peers in the same mesh can access this user-provided dictionary of metadata via the presence graph at graph and when evaluating connection requests using connection_request_handler. Use set_peer_metadata or set_peer_metadata_json_string to set this value.

This is not made available to peers only connected via WebSocket.

‍Important: The returned JSON string is not cached, make sure to call this

method once and keep it for as long as needed.

set_connection_request_handler()

void ditto::Presence::set_connection_request_handler

(

ConnectionRequestHandler

connection_request_handler

)

Set this handler to control which peers in a Ditto mesh can connect to the current peer.

Each peer in a Ditto mesh will attempt to connect to other peers that it can reach. By default, the mesh will try and establish connections that optimize for the best overall connectivity between peers. However, you can set this handler to assert some control over which peers you connect to.

If set, this handler is called for every incoming connection request from a remote peer and is passed the other peer's peer_key, peer_metadata, and identity_service_metadata. The handler can then accept or reject the request by returning an appropriate ConnectionRequestAuthorization value. When the connection request is rejected, the remote peer may retry the connection request after a short delay.

Connection request handlers must reliably respond to requests within a short time. If a handler takes too long to respond or throws an exception, the connection request will be denied. The response currently times out after 10 seconds, but this exact value may be subject to change in future releases.

Note

The handler is called from a different thread.

See also

peer_metadata

set_peer_metadata()

void ditto::Presence::set_peer_metadata

(

nlohmann::json const &

peer_metadata

)

Set arbitrary metadata to be associated with the current peer.

Note

The metadata must not exceed 4 KB in size when JSON-encoded.

This is a convenience method that wraps set_peer_metadata_json_string.

Parameters

peer_metadata

a json object containing metadata.

Exceptions

ValidationNotAMapError	if the peer_metadata is not a json object.
ValidationSizeLimitExceededError	if the JSON-encoded metadata exceeds the maximum size as given by 4 KB.
ValidationNotAMapError	if the provided json value is not a json object/map.

See also

peer_metadata for details on usage of metadata.

set_peer_metadata_json_string()

void ditto::Presence::set_peer_metadata_json_string

(

std::string

json_string

)

Set arbitrary metadata formatted as JSON to be associated with the current peer.

Note

The metadata must not exceed 4 KB in size.

Parameters

json_string

JSON-encoded metadata string.

Exceptions

ref ValidationNotJSONCompatibleError if

Parameters

json_string

is not a valid JSON string.

Exceptions

ref ValidationNotAMapError if

Parameters

json_string

decodes to a json value which is not a json object/map.

Exceptions

ref ValidationSizeLimitExceededError if

Parameters

json_string

exceeds the maximum size of 4 KB.

See also

peer_metadata for details on usage of metadata.