EntropyEngine::Networking::SessionHandle

EntropyObject-stamped handle for network sessions. More…

#include <SessionHandle.h>

Inherits from EntropyEngine::Core::EntropyObject

Public Functions

	Name
bool	valid() const Checks whether this handle still refers to a live session.
virtual std::string	toString() const override Human-readable short string (class@ptr by default).
bool	supportsMultipleChannels() const Check if connection supports multiple data channels.
Result< void >	sendSceneSnapshot(const std::vector< uint8_t > & snapshotData) const Sends scene snapshot.
Result< void >	sendPropertyUpdateBatch(const std::vector< uint8_t > & batchData) const Sends batched property updates.
Result< void >	sendPropertyUpdate(PropertyHash hash, PropertyType type, const PropertyValue & value) const Sends single property update.
Result< void >	sendHeartbeat() const Sends heartbeat message.
Result< void >	sendEntityDestroyed(uint64_t entityId) const Sends EntityDestroyed protocol message.
Result< void >	sendEntityCreated(uint64_t entityId, const std::string & appId, const std::string & typeName, uint64_t parentId, const std::vector< NetworkSession::ComponentGroupData > & components ={}, uint64_t targetSceneId =0, const std::string & entityName ="") const Sends EntityCreated protocol message.
Result< void >	sendComponentRemoved(uint64_t entityId, ComponentTypeHash typeHash) const Sends ComponentRemoved protocol message.
Result< void >	sendComponentAdded(uint64_t entityId, const NetworkSession::ComponentGroupData & component) const Sends ComponentAdded protocol message.
Result< void >	sendAssetWithdrawAll(const std::string & appId, uint64_t requestId =0) const Sends AssetWithdrawAll request.
Result< void >	sendAssetWithdraw(const std::vector< std::array< uint8_t, 32 > > & assetIds, uint64_t requestId =0) const Sends AssetWithdraw request.
Result< void >	sendAssetUploadComplete(const NetworkSession::AssetUploadCompleteData & data) const Completes a chunked upload session.
Result< void >	sendAssetUploadChunk(const NetworkSession::AssetUploadChunkData & data) const Sends a chunk of data during chunked upload.
Result< void >	sendAssetUploadCancel(const std::array< uint8_t, 16 > & uploadId) const Cancels an in-progress chunked upload.
Result< void >	sendAssetUploadBegin(const NetworkSession::AssetUploadBeginData & data) const Begins a chunked upload session.
Result< void >	sendAssetUpload(const std::string & appId, const std::vector< uint8_t > & data, uint8_t contentType, bool persistent, uint64_t requestId =0) const Sends AssetUpload request.
Result< void >	sendAssetUpload(const std::string & appId, const std::vector< uint8_t > & data, uint8_t contentType, bool persistent, uint64_t requestId, const NetworkSession::AssetMetadataData & metadata) const Sends AssetUpload request with metadata.
Result< void >	sendAssetResolveBatch(const std::vector< std::array< uint8_t, 32 > > & assetIds, uint64_t requestId =0) const Sends AssetResolveBatch request.
Result< void >	sendAssetResolve(const std::array< uint8_t, 32 > & assetId, uint64_t requestId =0) const Sends AssetResolve request.
Result< void >	sendAssetProvideKey(const std::array< uint8_t, 32 > & assetId, const std::array< uint8_t, 32 > & key, uint64_t requestId =0) const Sends AssetProvideKey request.
Result< void >	sendAssetFetch(const std::array< uint8_t, 32 > & assetId, uint64_t requestId =0) const Sends AssetFetch request (for WebRTC delivery).
Result< void >	sendAssetAdvertise(const std::string & appId, const std::vector< NetworkSession::AssetEntryData > & entries, uint64_t requestId =0) const Sends AssetAdvertise request.
Result< void >	performHandshake(const std::string & clientType, const std::string & clientId) const Initiates protocol handshake with remote peer.
SessionHandle &	operator=(const SessionHandle & other)
SessionHandle &	operator=(SessionHandle && other)
Result< void >	openChannel(const std::string & channel) const Open a named data channel for bulk data transfer.
bool	isConnected() const Checks if underlying connection is established.
PropertyRegistry &	getPropertyRegistry() Gets the property registry for this session.
const PropertyRegistry &	getPropertyRegistry() const Gets the property registry (const version).
ConnectionStats	getConnectionStats() const Gets connection statistics.
ConnectionState	getConnectionState() const Gets underlying connection state.
ConnectionHandle	getConnection() const Gets the underlying connection handle.
virtual const char *	className() const override Runtime class name for diagnostics and reflection.
virtual uint64_t	classHash() const override Stable type hash for cross-language identification.
	SessionHandle() =default
	SessionHandle(const SessionHandle & other)
	SessionHandle(SessionHandle && other)

Friends

	Name
class	SessionManager

Additional inherited members

Protected Classes inherited from EntropyEngine::Core::EntropyObject

	Name
struct	HandleCore Optional handle identity stamped by an owner/registry.

Public Functions inherited from EntropyEngine::Core::EntropyObject

	Name
virtual	~EntropyObject() =default
virtual const TypeSystem::TypeInfo *	typeInfo() const Optional richer type information; may be null.
bool	tryRetain() const Attempts to retain only if the object is still alive.
void	retain() const Increments the reference count.
void	release() const Decrements the reference count and deletes when it reaches zero.
uint32_t	refCount() const Current reference count (approximate under contention).
bool	hasHandle() const
template <class OwnerT > OwnerT *	handleOwnerAs() const Returns the stamped owner pointer cast to the requested type.
const void *	handleOwner() const
uint32_t	handleIndex() const
uint64_t	handleId() const
uint32_t	handleGeneration() const
WeakControlBlock *	getWeakControlBlock() const Lazily retrieves or creates the weak control block.
virtual std::string	description() const Long-form description; defaults to toString().
virtual std::string	debugString() const Debug-oriented string including refcount and handle when present.
	EntropyObject() =default
	EntropyObject(EntropyObject && ) =delete
	EntropyObject(const EntropyObject & ) =delete

Protected Functions inherited from EntropyEngine::Core::EntropyObject

	Name
void	_setHandleIdentity(void * owner, uint32_t index, uint32_t generation)
void	_clearHandleIdentity()

Protected Attributes inherited from EntropyEngine::Core::EntropyObject

	Name
std::atomic< WeakControlBlock * >	_weakBlock Lazily allocated control block for weak refs.
std::atomic< uint32_t >	_refCount Thread-safe retain/release counter.
struct EntropyEngine::Core::EntropyObject::HandleCore	_handle

Friends inherited from EntropyEngine::Core::EntropyObject

	Name
struct	HandleAccess

Detailed Description

class EntropyEngine::Networking::SessionHandle;

EntropyObject-stamped handle for network sessions.

SessionHandle is the primary entry point for protocol-level operations. It wraps a ConnectionHandle and provides high-level message sending:

The handle follows the WorkContractHandle pattern - stamped with (manager + index + generation) and delegates to SessionManager.

Copy semantics:

Copying a handle copies its stamped identity (not ownership transfer)
SessionManager owns lifetime; handles become invalid when freed

Typical workflow:

Create via SessionManager::createSession(connectionHandle)
Use for protocol operations (sendEntityCreated, etc.)
After release, valid() returns false

ConnectionManager connMgr(1024);
SessionManager sessMgr(&connMgr, 512);

auto conn = connMgr.openLocalConnection("/tmp/entropy.sock");
conn.connect().wait();

auto sess = sessMgr.createSession(conn);
sess.sendEntityCreated(entityId, appId, typeName, parentId);

Public Functions Documentation

function valid

bool valid() const

Checks whether this handle still refers to a live session.

Return: true if handle is valid and refers to an allocated session

Validates that the handle’s owner, index, and generation match the SessionManager’s current slot state.

function toString

virtual std::string toString() const override

Human-readable short string (class@ptr by default).

Reimplements: EntropyEngine::Core::EntropyObject::toString

function supportsMultipleChannels

bool supportsMultipleChannels() const

Check if connection supports multiple data channels.

Return: true if WebRTC-style multi-channel is available

function sendSceneSnapshot

Result< void > sendSceneSnapshot(
    const std::vector< uint8_t > & snapshotData
) const

Sends scene snapshot.

Parameters:

snapshotData Serialized scene snapshot

Return: Result indicating success or failure

Sends complete scene state for initialization or synchronization.

function sendPropertyUpdateBatch

Result< void > sendPropertyUpdateBatch(
    const std::vector< uint8_t > & batchData
) const

Sends batched property updates.

Parameters:

batchData Serialized property update batch

Return: Result indicating success or failure

Sends pre-serialized batch of property updates. Used by BatchManager.

function sendPropertyUpdate

Result< void > sendPropertyUpdate(
    PropertyHash hash,
    PropertyType type,
    const PropertyValue & value
) const

Sends single property update.

Parameters:

hash Pre-computed property hash
type Property type
value Property value

Return: Result indicating success or failure

Sends individual property change. For bulk updates, use sendPropertyUpdateBatch().

function sendHeartbeat

Result< void > sendHeartbeat() const

Sends heartbeat message.

Return: Result indicating success or failure

Sends a heartbeat to the remote peer. The peer will respond with a HeartbeatResponse. Used for connection liveness detection.

function sendEntityDestroyed

Result< void > sendEntityDestroyed(
    uint64_t entityId
) const

Sends EntityDestroyed protocol message.

Parameters:

entityId Entity to destroy

Return: Result indicating success or failure

Notifies remote peer of entity destruction.

function sendEntityCreated

Result< void > sendEntityCreated(
    uint64_t entityId,
    const std::string & appId,
    const std::string & typeName,
    uint64_t parentId,
    const std::vector< NetworkSession::ComponentGroupData > & components ={},
    uint64_t targetSceneId =0,
    const std::string & entityName =""
) const

Sends EntityCreated protocol message.

Parameters:

entityId Unique entity identifier
appId Application identifier
typeName Entity type name
parentId Parent entity ID (0 for root)
components Component groups with their properties
targetSceneId Scene to add entity to (0 = use session’s default scene)
entityName Flecs entity name for client-side identification

Return: Result indicating success or failure

Notifies remote peer of new entity creation.

function sendComponentRemoved

Result< void > sendComponentRemoved(
    uint64_t entityId,
    ComponentTypeHash typeHash
) const

Sends ComponentRemoved protocol message.

Parameters:

entityId Entity that lost the component
typeHash Type hash of the removed component

Return: Result indicating success or failure

Notifies remote peer that a component was removed from an entity.

function sendComponentAdded

Result< void > sendComponentAdded(
    uint64_t entityId,
    const NetworkSession::ComponentGroupData & component
) const

Sends ComponentAdded protocol message.

Parameters:

entityId Entity that received the component
component Component data including type hash and properties

Return: Result indicating success or failure

Notifies remote peer that a component was added to an entity.

function sendAssetWithdrawAll

Result< void > sendAssetWithdrawAll(
    const std::string & appId,
    uint64_t requestId =0
) const

Sends AssetWithdrawAll request.

Parameters:

appId Application identifier
requestId Request ID for response correlation

Return: Result indicating success or failure

function sendAssetWithdraw

Result< void > sendAssetWithdraw(
    const std::vector< std::array< uint8_t, 32 > > & assetIds,
    uint64_t requestId =0
) const

Sends AssetWithdraw request.

Parameters:

assetIds Asset IDs to withdraw
requestId Request ID for response correlation

Return: Result indicating success or failure

function sendAssetUploadComplete

Result< void > sendAssetUploadComplete(
    const NetworkSession::AssetUploadCompleteData & data
) const

Completes a chunked upload session.

Parameters:

data Completion data with upload ID and total chunks

Return: Result indicating success or failure

function sendAssetUploadChunk

Result< void > sendAssetUploadChunk(
    const NetworkSession::AssetUploadChunkData & data
) const

Sends a chunk of data during chunked upload.

Parameters:

data Chunk data with upload ID, offset, and payload

Return: Result indicating success or failure

function sendAssetUploadCancel

Result< void > sendAssetUploadCancel(
    const std::array< uint8_t, 16 > & uploadId
) const

Cancels an in-progress chunked upload.

Parameters:

uploadId 16-byte upload session ID

Return: Result indicating success or failure

function sendAssetUploadBegin

Result< void > sendAssetUploadBegin(
    const NetworkSession::AssetUploadBeginData & data
) const

Begins a chunked upload session.

Parameters:

data Upload parameters

Return: Result indicating success or failure

function sendAssetUpload

Result< void > sendAssetUpload(
    const std::string & appId,
    const std::vector< uint8_t > & data,
    uint8_t contentType,
    bool persistent,
    uint64_t requestId =0
) const

Sends AssetUpload request.

Parameters:

appId Application identifier
data Asset data
contentType Content type
persistent Whether asset survives app disconnect
requestId Request ID for response correlation

Return: Result indicating success or failure

function sendAssetUpload

Result< void > sendAssetUpload(
    const std::string & appId,
    const std::vector< uint8_t > & data,
    uint8_t contentType,
    bool persistent,
    uint64_t requestId,
    const NetworkSession::AssetMetadataData & metadata
) const

Sends AssetUpload request with metadata.

Parameters:

appId Application identifier
data Asset data
contentType Content type
persistent Whether asset survives app disconnect
requestId Request ID for response correlation
metadata Type-specific metadata (shader, texture, etc.)

Return: Result indicating success or failure

function sendAssetResolveBatch

Result< void > sendAssetResolveBatch(
    const std::vector< std::array< uint8_t, 32 > > & assetIds,
    uint64_t requestId =0
) const

Sends AssetResolveBatch request.

Parameters:

assetIds Asset IDs to resolve
requestId Request ID for response correlation

Return: Result indicating success or failure

function sendAssetResolve

Result< void > sendAssetResolve(
    const std::array< uint8_t, 32 > & assetId,
    uint64_t requestId =0
) const

Sends AssetResolve request.

Parameters:

assetId Asset ID to resolve
requestId Request ID for response correlation

Return: Result indicating success or failure

function sendAssetProvideKey

Result< void > sendAssetProvideKey(
    const std::array< uint8_t, 32 > & assetId,
    const std::array< uint8_t, 32 > & key,
    uint64_t requestId =0
) const

Sends AssetProvideKey request.

Parameters:

assetId Asset ID
key 32-byte encryption key
requestId Request ID for response correlation

Return: Result indicating success or failure

function sendAssetFetch

Result< void > sendAssetFetch(
    const std::array< uint8_t, 32 > & assetId,
    uint64_t requestId =0
) const

Sends AssetFetch request (for WebRTC delivery).

Parameters:

assetId Asset ID to fetch
requestId Request ID for response correlation

Return: Result indicating success or failure

function sendAssetAdvertise

Result< void > sendAssetAdvertise(
    const std::string & appId,
    const std::vector< NetworkSession::AssetEntryData > & entries,
    uint64_t requestId =0
) const

Sends AssetAdvertise request.

Parameters:

appId Application identifier
entries Asset entries to advertise
requestId Request ID for response correlation

Return: Result indicating success or failure

function performHandshake

Result< void > performHandshake(
    const std::string & clientType,
    const std::string & clientId
) const

Initiates protocol handshake with remote peer.

Parameters:

clientType Type identifier for this client (e.g., “EntropyClient”, “CanvasViewer”)
clientId Unique identifier for this client instance

Return: Result indicating success or failure

Sends handshake message to establish protocol-level communication. This method should be called AFTER setting up callbacks (setHandshakeCallback, setEntityCreatedCallback, etc.) to ensure notifications are received.

Server-side: NetworkSession automatically responds to incoming handshakes, so this method is typically not needed on the server.

Client-side: Call this method after the underlying connection is established and callbacks are configured.

function operator=

inline SessionHandle & operator=(
    const SessionHandle & other
)

function operator=

inline SessionHandle & operator=(
    SessionHandle && other
)

function openChannel

Result< void > openChannel(
    const std::string & channel
) const

Open a named data channel for bulk data transfer.

Parameters:

channel Channel name (use NetworkConnection::CHANNEL_* constants)

Return: Result indicating success or failure

For WebRTC connections, creates a dedicated data channel. For other backends, this is a no-op.

function isConnected

bool isConnected() const

Checks if underlying connection is established.

Return: true if connection is in Connected state

function getPropertyRegistry

PropertyRegistry & getPropertyRegistry()

Gets the property registry for this session.

Return: Reference to property registry

Registry tracks entity properties and provides hash-based lookups.

function getPropertyRegistry

const PropertyRegistry & getPropertyRegistry() const

Gets the property registry (const version).

Return: Const reference to property registry

function getConnectionStats

ConnectionStats getConnectionStats() const

Gets connection statistics.

Return: Stats with byte/message counts

function getConnectionState

ConnectionState getConnectionState() const

Gets underlying connection state.

Return: Connection state, or Disconnected if handle is invalid

function getConnection

ConnectionHandle getConnection() const

Gets the underlying connection handle.

Return: ConnectionHandle for this session

For advanced use cases that need direct connection access.

function className

inline virtual const char * className() const override

Runtime class name for diagnostics and reflection.

Reimplements: EntropyEngine::Core::EntropyObject::className

function classHash

virtual uint64_t classHash() const override

Stable type hash for cross-language identification.

Reimplements: EntropyEngine::Core::EntropyObject::classHash

function SessionHandle

SessionHandle() =default

function SessionHandle

inline SessionHandle(
    const SessionHandle & other
)

function SessionHandle

inline SessionHandle(
    SessionHandle && other
)

Friends

friend SessionManager

friend class SessionManager(
    SessionManager
);

Updated on 2026-01-26 at 17:14:35 -0500