PrivMXEndpoint | PrivMX Docs

A wrapper class that manages a connection to PrivMX Bridge and provides access to various APIs, including Threads, Stores, and Inboxes. The PrivMXEndpoint class is designed to encapsulate and manage a single connection to PrivMX. It provides access to different APIs for handling Threads, Stores, and Inboxes, based on the modules that are enabled during initialization. It also supports asynchronous operations like uploading and downloading files, and allows for managing callbacks for events.

Fields

id

Int64 The stable identity of the entity associated with this instance.

anonymous

Bool Marks the endpoint as connected using no authorisation.

connection

any PrivMXConnection Provides handling of network and events through PrivMXConnection.

threadApi

(any PrivMXThread)? API for handling Threads.

storeApi

(any PrivMXStore)? API for handling Stores.

inboxApi

(any PrivMXInbox)? API for handling Inboxes.

eventApi

EventApi? API for handling Custom Events

kvdbApi

KvdbApi? API for handling KVDBs

Methods

init(modules:userPrivKey:solutionId:platformUrl:)

Initializes a new instance of PrivMXEndpoint with a connection to PrivMX Bridge and optional modules. This method sets up the connection and, based on the provided modules, initializes the APIs for handling Threads, Stores, and Inboxes.

Params

modules

Set<PrivMXModule>

A set of modules to initialize (of type PrivMXModule).

userPrivKey

String

The user’s private key in WIF format.

solutionId

String

The unique identifier of PrivMX Solution.

platformUrl

String

The URL of PrivMX Bridge instance.

public init(
modules:Set<PrivMXModule>,
userPrivKey:String,
solutionId:String,
platformUrl:String
) throws

init(modules:userPrivKey:solutionId:bridgeUrl:)

Params

modules

Set<PrivMXModule>

A set of modules to initialize (of type PrivMXModule).

userPrivKey

String

The user’s private key in WIF format.

solutionId

String

The unique identifier of PrivMX Solution.

bridgeUrl

String

The URL of PrivMX Bridge instance.

public init(
modules:Set<PrivMXModule>,
userPrivKey:String,
solutionId:String,
bridgeUrl:String
) throws

init(modules:solutionId:platformUrl:)

Initializes a new instance of PrivMXEndpoint with a public connection to the PrivMX Bridge and optional modules. This method sets up the connection and, based on the provided modules, initializes the APIs for handling threads, stores, and inboxes. Using a Public (anonymous) connection. Take note that this is only useful for Inboxes

Params

modules

Set<PrivMXModule>

A set of modules to initialize (of type PrivMXModule).

solutionId

String

The unique identifier of the PrivMX solution.

platformUrl

String

The URL of the PrivMX Bridge instance.

public init(
modules:Set<PrivMXModule>,
solutionId:String,
platformUrl:String
) throws

init(modules:solutionId:bridgeUrl:)

Params

modules

Set<PrivMXModule>

A set of modules to initialize (of type PrivMXModule).

solutionId

String

The unique identifier of the PrivMX solution.

bridgeUrl

String

The URL of the PrivMX Bridge instance.

public init(
modules:Set<PrivMXModule>,
solutionId:String,
bridgeUrl:String
) throws

startUploadingNewFile(_:to:withPublicMeta:withPrivateMeta:sized:withChunksOf:onChunkUploaded:)

Begins uploading a new file using PrivMXStoreFileHandler, which manages file uploads. This method uploads a file to a specified store using a FileHandle. It supports uploading large files in chunks and provides a callback for tracking the progress.

Params

file

FileHandle

A local FileHandle representing the file to be uploaded.

store

String

The identifier of the destination store.

publicMeta

Data

Public, unencrypted metadata for the file.

privateMeta

Data

Encrypted metadata for the file.

size

Int64

The size of the file in bytes.

chunkSize

Int64

The size of individual chunks, by default set to PrivMXStoreFileHandler.RecommendedChunkSize

onChunkUploaded

(@escaping @Sendable (Int) -> Void)

A callback that is called after each chunk upload is completed.

public func startUploadingNewFile(
_ file:FileHandle,
to store:String,
withPublicMeta publicMeta: Data,
withPrivateMeta privateMeta: Data,
sized size:Int64,
withChunksOf chunkSize: Int64 = PrivMXStoreFileHandler.RecommendedChunkSize,
onChunkUploaded: (@escaping @Sendable (Int) -> Void) = {_ in}
) async throws -> String

Returns

String · The identifier of the uploaded file as a String.

startUploadingNewFileFromBuffer(_:to:withPublicMeta:withPrivateMeta:sized:withChunksOf:onChunkUploaded:)

Begins uploading a new file from an in-memory buffer using PrivMXStoreFileHandler. This method uploads file content from a Data buffer to a specified Store. It supports chunked uploads and provides a callback for progress tracking.

Params

buffer

Data

The in-memory file content as Data.

store

String

The identifier of the destination store.

publicMeta

Data

Public, unencrypted metadata for the file.

privateMeta

Data

Encrypted metadata for the file.

size

Int64

The size of the file in bytes.

chunkSize

Int64

The size of each chunk to be uploaded.

onChunkUploaded

(@escaping @Sendable (Int) -> Void)

A callback that is called after each chunk upload is completed.

public func startUploadingNewFileFromBuffer(
_ buffer:Data,
to store:String,
withPublicMeta publicMeta: Data,
withPrivateMeta privateMeta: Data,
sized size:Int64,
withChunksOf chunkSize: Int64 = PrivMXStoreFileHandler.RecommendedChunkSize,
onChunkUploaded: (@escaping @Sendable (Int) -> Void) = {_ in}
) async throws -> String

Returns

String · The identifier of the uploaded file as a String.

startUploadingUpdatedFile(_:as:replacingPublicMeta:replacingPrivateMeta:replacingSize:withChunksOf:onChunkUploaded:)

/ Begins uploading an updated file using PrivMXStoreFileHandler. This method updates an existing file in a store with new content and metadata, supporting chunked uploads for large files.

Params

file

FileHandle

A local FileHandle representing the updated file.

storeFile

String

The identifier of the file in the store to be updated.

publicMeta

Data

Public metadata to overwrite the existing metadata.

privateMeta

Data

Encrypted metadata to overwrite the existing metadata.

size

Int64

The size of the updated file in bytes.

chunkSize

Int64

The size of individual chunks, by default set to PrivMXStoreFileHandler.RecommendedChunkSize

onChunkUploaded

(@escaping @Sendable (Int) -> Void)

A callback that is called after each chunk upload is completed.

public func startUploadingUpdatedFile(
_ file:FileHandle,
as storeFile:String,
replacingPublicMeta publicMeta: Data,
replacingPrivateMeta privateMeta: Data,
replacingSize size:Int64,
withChunksOf chunkSize: Int64 = PrivMXStoreFileHandler.RecommendedChunkSize,
onChunkUploaded: (@escaping @Sendable (Int) -> Void) = {_ in}
) async throws -> String

Returns

String · The identifier of the updated file as a String.

startUploadingUpdatedFileFromBuffer(_:as:replacingPublicMeta:replacingPrivateMeta:replacingSize:withChunksOf:onChunkUploaded:)

Begins uploading an updated file from an in-memory buffer using PrivMXStoreFileHandler. This method updates an existing file in a store with new content and metadata, supporting chunked uploads for large files.

Params

buffer

Data

The in-memory content of the updated file as Data.

storeFile

String

The identifier of the file in the store to be updated.

publicMeta

Data

Public metadata to overwrite the existing metadata.

privateMeta

Data

Encrypted metadata to overwrite the existing metadata.

size

Int64

The size of the updated file in bytes.

chunkSize

Int64

The size of each chunk to be uploaded.

onChunkUploaded

(@escaping @Sendable (Int) -> Void)

A callback that is called after each chunk upload is completed.

public func startUploadingUpdatedFileFromBuffer(
_ buffer:Data,
as storeFile:String,
replacingPublicMeta publicMeta: Data,
replacingPrivateMeta privateMeta: Data,
replacingSize size:Int64,
withChunksOf chunkSize: Int64 = PrivMXStoreFileHandler.RecommendedChunkSize,
onChunkUploaded: (@escaping @Sendable (Int) -> Void) = {_ in}
) async throws -> String

Returns

String · The identifier of the updated file as a String.

startDownloadingToFile(_:from:withChunksOf:onChunkDownloaded:)

Begins downloading a file to the local filesystem using PrivMXStoreFileHandler. This method downloads a file from a Store to the local filesystem using a FileHandle. It supports downloading files in chunks and provides a callback for progress tracking.

Params

file

FileHandle

A local FileHandle representing the destination file.

fileId

String

The identifier of the file to be downloaded.

chunkSize

Int64

The size of individual chunks, by default set to PrivMXStoreFileHandler.RecommendedChunkSize

onChunkDownloaded

(@escaping @Sendable (Int) -> Void)

A callback that is called after each chunk download is completed.

public func startDownloadingToFile(
_ file:FileHandle,
from fileId:String,
withChunksOf chunkSize: Int64 = PrivMXStoreFileHandler.RecommendedChunkSize,
onChunkDownloaded: (@escaping @Sendable (Int) -> Void) = {_ in}
) async throws -> String

Returns

String · The identifier of the downloaded file as a String.

startDownloadingToFileFromInbox(_:from:withChunksOf:onChunkDownloaded:)

Begins downloading a file to the local filesystem using InboxFileHandler. This method downloads a file from an Inbox to the local filesystem using a FileHandle. It supports downloading files in chunks and provides a callback for progress tracking.

Params

file

FileHandle

A local FileHandle representing the destination file.

fileId

String

The identifier of the file to be downloaded.

chunkSize

Int64

The size of a chunk to be used.

onChunkDownloaded

(@escaping @Sendable (Int) -> Void)

A callback that is called after each chunk download is completed.

public func startDownloadingToFileFromInbox(
_ file:FileHandle,
from fileId:String,
withChunksOf chunkSize: Int64 = InboxFileHandler.RecommendedChunkSize,
onChunkDownloaded: (@escaping @Sendable (Int) -> Void) = {_ in}
) async throws -> String

Returns

String · The identifier of the downloaded file as a String.

startDownloadingToBufferFromInbox(from:withChunksOf:onChunkDownloaded:)

Begins downloading a file to in-memory buffer. This method downloads a file from a store to the local in-memory buffer. It supports downloading files in chunks and provides a callback for progress tracking.

Params

fileId

String

The identifier of the file to be downloaded.

chunkSize

Int64

The size of individual chunks, by default set to PrivMXStoreFileHandler.RecommendedChunkSize

onChunkDownloaded

(@escaping @Sendable (Int) -> Void)

A callback that is called after each chunk download is completed.

public func startDownloadingToBufferFromInbox(
from fileId:String,
withChunksOf chunkSize: Int64 = PrivMXStoreFileHandler.RecommendedChunkSize,
onChunkDownloaded: (@escaping @Sendable (Int) -> Void) = {_ in}
) async throws -> Data

Returns

Data · The identifier of the downloaded file as a String.

startDownloadingToBuffer(_:from:withChunksOf:onChunkDownloaded:)

Params

file

FileHandle

fileId

String

chunkSize

Int64

onChunkDownloaded

(@escaping @Sendable (Int) -> Void)

public func startDownloadingToBuffer(
_ file:FileHandle,
from fileId:String,
withChunksOf chunkSize: Int64 = PrivMXStoreFileHandler.RecommendedChunkSize,
onChunkDownloaded: (@escaping @Sendable (Int) -> Void) = {_ in}
) async throws -> Data

Returns

Data ·

startDownloadingToBuffer(from:withChunksOf:onChunkDownloaded:)

Params

fileId

String

The identifier of the file to be downloaded.

chunkSize

Int64

The size of individual chunks, by default set to PrivMXStoreFileHandler.RecommendedChunkSize

onChunkDownloaded

(@escaping @Sendable (Int) -> Void)

A callback that is called after each chunk download is completed.

public func startDownloadingToBuffer(
from fileId:String,
withChunksOf chunkSize: Int64 = PrivMXStoreFileHandler.RecommendedChunkSize,
onChunkDownloaded: (@escaping @Sendable (Int) -> Void) = {_ in}
) async throws -> Data

Returns

Data · The identifier of the downloaded file as a String.

registerCallback(for:)

Registers a callback for a particular event type from a particular scope. Whenever possible preffer using registerCallbacksInBulk(_:) to minimise the amount of server requests.

Params

request

PMXEventCallbackRegistration

PMXEventCallbackRegistration instance describing EventType and Scope of the callback; as well as assigning it to a group.

public func registerCallback(
for request: PMXEventCallbackRegistration
) throws -> Void

registerCallbacksInBulk(_:)

Mass registration for Events, this method optimises the amount of server requests made and is the recommended way to subscribe for events.

Params

requests

[PMXEventCallbackRegistration]

an arrays of tuples consisting of the callback that will be called when the event arrives, PMXEventRegistration value that describes the particular event and a string representing a group of callbacks

public func registerCallbacksInBulk(
_ requests:[PMXEventCallbackRegistration]
) -> [(any Error)?]

Returns

[<tuple>(any Error)</tuple>?] · array of optional Errors corresponding to the provided requests. If the reques was succesfull the associated index will be nil otherwise it will have the error thrown.

clearCallbacks(for:)

Removes all callbacks for a particular Request.

Params

request

PMXEventSubscriptionRequest

the request specifying Event Type and Scope

public func clearCallbacks(
for request: PMXEventSubscriptionRequest
) throws -> Void

clearCallbacks(in:)

Removes all registered callbacks assigned to group. If this removes the last callback for a subscription, it will automatically unsubscribe.

Params

group

String

the group that has been assigned when registering callbacks.

public func clearCallbacks(
in group:String
) throws -> Void

clearAllCallbacks()

Removes all registered callbacks and subscriptions for Events.

public func clearAllCallbacks(
) throws -> Void

handleEvent(_:)

Params

event

any PMXEvent

public func handleEvent (
_ event: any PMXEvent
) async throws