Class Presence

Readonly ditto

connectionRequestHandler

• get connectionRequestHandler(): ConnectionRequestHandler

• 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 peerKey, peerMetadata, and identityServiceMetadata. The handler can then accept or reject the request by returning an according 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 timeout is currently 10 seconds but may be subject to change in future releases.

  Returns ConnectionRequestHandler

  See

  peerMetadata()

• set connectionRequestHandler(handler): void

• Parameters

  • handler: ConnectionRequestHandler

  Returns void

  Throws

  TypeError: if the given handler is not a function.

graph

• get graph(): PresenceGraph

• Returns the current presence graph capturing all known peers and connections between them.

  Returns PresenceGraph

peerMetadata

• get peerMetadata(): Record<string, any>

• This is a convenience property that wraps peerMetadataJSONString().

  Returns Record<string, any>

  See

  peerMetadataJSONString() for details.

peerMetadataJSONString

• get peerMetadataJSONString(): string

• Metadata associated with the current peer. Other peers in the same mesh can access this user-provided object of metadata via the presence graph and when evaluating connection requests using connectionRequestHandler().

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

  Uses UTF-8 encoding.

  Returns string

  See

  peerMetadata() for a convenience property that provides access to parsed metadata.

observe

• observe(didChangeHandler): Observer

• Request information about Ditto peers in range of this device.

  This method returns an observer which should be held as long as updates are required. A newly registered observer will have a peers update delivered to it immediately. From then on it will be invoked repeatedly when Ditto devices come and go, or the active connections to them change.

  Parameters

  • didChangeHandler: ((presenceGraph) => void)

    • • (presenceGraph): void

      • Parameters

        • presenceGraph: PresenceGraph

        Returns void

  Returns Observer

setPeerMetadata

• setPeerMetadata(peerMetadata): Promise<void>

• This is a convenience method that wraps setPeerMetadataJSONString().

  Parameters

  • peerMetadata: Record<string, any>

  Returns Promise<void>

  Throws

  DittoError validation/not-an-object: if peerMetadata is not an object.

  Throws

  DittoError validation/not-json-compatible: if peerMetadata is not JSON serializable.

  Throws

  DittoError validation/size-limit-exceeded: if the size limit for peerMetadata has been exceeded.

  See

  setPeerMetadataJSONString() for details.

setPeerMetadataJSONString

• setPeerMetadataJSONString(jsonString): Promise<void>

• Set arbitrary metadata to be associated with the current peer.

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

  Parameters

  • jsonString: string

  Returns Promise<void>

  Throws

  DittoError validation/invalid-json: if jsonString does not contain valid JSON.

  Throws

  DittoError validation/not-an-object: if jsonString does not contain an object.

  Throws

  DittoError validation/size-limit-exceeded: if the size limit for jsonString has been exceeded.

  See

  peerMetadataJSONString() for details on usage of metadata.