DittoPresence

public class DittoPresence

The entrypoint for all actions that relate presence of other peers known by the current peer, either directly or through other peers.

You don’t create one directly but can access it from a particular Ditto instance via its presence property.

Properties

  • 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 DittoPresence.graph and when evaluating connection requests using DittoPresence.connectionRequestHandler. Use setPeerMetadata(_:) or setPeerMetadataJSONData(_:) to set this value.

    This is a convenience property that wraps peerMetadataJSONData.

    Declaration

    Swift

    public var peerMetadata: [String : Any?] { get }

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

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

    This is a convenience method that wraps setPeerMetadataJSONData(_:).

    Throws

    DittoSwiftError > .validationError(.notJSONCompatible) if dictionary contains a value that is not JSON-compatible.

    Throws

    DittoSwiftError > .validationError(.sizeLimitExceeded) if dictionary encoded as JSON exceeds the maximum size as given by 4 KB.

    See also

    peerMetadata for details on usage of metadata.

    Declaration

    Swift

    public func setPeerMetadata(_ peerMetadata: [String : Any?]) throws

    Parameters

    peerMetadata

    A dictionary containing metadata. Keys must be strings and values must be JSON-compatible.

  • Metadata associated with the current peer as JSON-encoded data.

    Other peers in the same mesh can access this user-provided dictionary of metadata via the presence graph at DittoPresence.graph and when evaluating connection requests using DittoPresence.connectionRequestHandler. Use setPeerMetadata(_:) or setPeerMetadataJSONData(_:) to set this value.

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

    Uses UTF-8 encoding.

    See also

    peerMetadata

    Declaration

    Swift

    public var peerMetadataJSONData: Data { get }

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

    The metadata must not exceed 4 KB in size. Expects UTF-8 encoded JSON.

    Throws

    DittoSwiftError > .validationError(.sizeLimitExceeded) if jsonData exceeds the maximum size of 4 KB.

    Throws

    DittoSwiftError > .validationError(.notADictionary) if jsonData decodes to an object that is not a dictionary.

    Throws

    DittoSwiftError > .validationError(.invalidJSON) if jsonData is not a valid JSON string.

    See also

    peerMetadata for details on usage of metadata.

    Declaration

    Swift

    public func setPeerMetadataJSONData(_ jsonData: Data) throws

    Parameters

    jsonData

    JSON-encoded metadata.

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

    Declaration

    Swift

    public var graph: DittoPresenceGraph { get }

Observing

  • 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.

    Declaration

    Swift

    public func observe(didChangeHandler: @escaping (DittoPresenceGraph) -> ()) -> DittoObserver

Authorizing Connection Requests

  • 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 DittoConnectionRequestAuthorization 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

    peerMetadata

    Declaration

    Swift

    public var connectionRequestHandler: DittoConnectionRequestHandler? { get set }

  • A Combine publisher for presence accessible via DittoPresence.

    See more

    Declaration

    Swift

    struct GraphPublisher : Publisher

  • A Combine publisher for the presence graph accessible via ditto.presence.

    Declaration

    Swift

    func graphPublisher() -> GraphPublisher

    Return Value

    A GraphPublisher which has an output of DittoPresenceGraph.