PrivMXInbox | PrivMX Docs

Protocol declaring methods of InboxApi using Swift types, enabling interaction with PrivMX Inboxes and Entries, as well as Files assigned to them.

Methods

createInbox(in:for:managedBy:withPublicMeta:withPrivateMeta:withFilesConfig:withPolicies:)

Creates an inbox in a specified context for a group of users, managed by a set of managers. This method creates an inbox associated with a given context ID, assigning users and managers to it, while attaching metadata and configuration for files if needed.

Params

contextId

String

The unique identifier for the context in which the inbox is being created.

users

[privmx.endpoint.core.UserWithPubKey]

An array of UserWithPubKey objects representing the users who will have access to the inbox.

managaers

[privmx.endpoint.core.UserWithPubKey]

An array of UserWithPubKey objects representing the managers responsible for managing the inbox.

publicMeta

Data

Public metadata to be associated with the inbox, provided as Data.

privateMeta

Data

Private metadata to be associated with the inbox, provided as Data.

filesConfig

privmx.endpoint.inbox.FilesConfig?

Optional configuration for managing files in the inbox, provided as FilesConfig.

policies

privmx.endpoint.core.ContainerPolicyWithoutItem?

The policies governing the Container.

func createInbox(
in contextId: String,
for users: [privmx.endpoint.core.UserWithPubKey],
managedBy managaers: [privmx.endpoint.core.UserWithPubKey],
withPublicMeta publicMeta: Data,
withPrivateMeta privateMeta: Data,
withFilesConfig filesConfig: privmx.endpoint.inbox.FilesConfig?,
withPolicies policies: privmx.endpoint.core.ContainerPolicyWithoutItem?
) throws -> String

Returns

String · A String representing the ID of the newly created inbox.

updateInbox(_:replacingUsers:replacingManagers:replacingPublicMeta:replacingPrivateMeta:replacingFilesConfig:atVersion:force:forceGenerateNewKey:replacingPolicies:)

Updates an existing inbox by replacing its users, managers, metadata, and configuration with new values. This method updates the specified inbox, replacing its current users, managers, and metadata (both public and private) with the new ones provided. It also allows updating the files configuration, optionally forcing the update and generating a new key if necessary.

Params

inboxId

String

The unique identifier of the inbox to be updated, provided as a String.

users

[privmx.endpoint.core.UserWithPubKey]

An array of UserWithPubKey representing the new users for the inbox.

managers

[privmx.endpoint.core.UserWithPubKey]

An array of UserWithPubKey representing the new managers for the inbox.

publicMeta

Data

The new public metadata associated with the inbox, passed as Data.

privateMeta

Data

The new private metadata associated with the inbox, passed as Data.

filesConfig

privmx.endpoint.inbox.FilesConfig?

Optional new configuration for managing files in the inbox, provided as FilesConfig.

version

Int64

The current version of the inbox, provided as an Int64. This is used for version control to ensure updates are applied correctly.

force

Bool

A Bool indicating whether the update should be forced, even if there are version conflicts.

forceGenerateNewKey

Bool

A Bool indicating whether a new key should be generated for the inbox during the update.

policies

privmx.endpoint.core.ContainerPolicyWithoutItem?

The policies governing the Container.

func updateInbox(
_ inboxId: String,
replacingUsers users: [privmx.endpoint.core.UserWithPubKey],
replacingManagers managers: [privmx.endpoint.core.UserWithPubKey],
replacingPublicMeta publicMeta: Data,
replacingPrivateMeta privateMeta: Data,
replacingFilesConfig filesConfig: privmx.endpoint.inbox.FilesConfig?,
atVersion version: Int64,
force: Bool,
forceGenerateNewKey: Bool,
replacingPolicies policies: privmx.endpoint.core.ContainerPolicyWithoutItem?
) throws -> Void

Returns

`` · This method returns Void and does not provide any result on success.

getInbox(_:)

Retrieves the inbox associated with the given inbox ID. This method fetches an inbox based on its unique identifier, returning detailed information about the inbox, such as its users, managers, and metadata.

Params

inboxId

String

The unique identifier of the inbox to retrieve, provided as a String.

func getInbox(
_ inboxId: String
) throws -> privmx.endpoint.inbox.Inbox

Returns

privmx.endpoint.inbox.Inbox · An Inbox object representing the detailed state of the requested inbox.

listInboxes(from:basedOn:)

Lists all inboxes in the specified context, based on the given paging query. This method retrieves a list of inboxes associated with a specific context, with the results potentially being paginated according to the provided PagingQuery.

Params

contextId

String

The unique identifier of the context from which inboxes will be listed.

pagingQuery

privmx.endpoint.core.PagingQuery

The query object that defines the pagination settings, such as limit, offset (skip) and sortOrder.

func listInboxes(
from contextId: String,
basedOn pagingQuery: privmx.endpoint.core.PagingQuery
) throws -> privmx.InboxList

Returns

privmx.InboxList · An InboxList object that contains the list of inboxes and associated pagination details.

getInboxPublicView(for:)

Retrieves the public view of the specified inbox. This method fetches the public view of an inbox, which includes public metadata that can be accessed without privileged access.

Params

inboxId

String

The unique identifier of the inbox to retrieve the public view for, provided as a String.

func getInboxPublicView(
for inboxId:String
) throws -> privmx.endpoint.inbox.InboxPublicView

Returns

privmx.endpoint.inbox.InboxPublicView · An InboxPublicView object containing the public metadata and details of the requested inbox.

deleteInbox(_:)

Deletes the inbox with the specified ID. This method removes the inbox identified by the given inbox ID, effectively deleting all associated data.

Params

inboxId

String

The unique identifier of the inbox to delete, provided as a String.

func deleteInbox(
_ inboxId: String
) throws -> Void

Returns

`` · This method returns Void and does not provide any result on success.

prepareEntry(in:containing:attaching:as:)

Prepares an entry to be sent to the specified inbox, optionally attaching file handles. This method prepares a new entry to be sent to the inbox identified by inboxId. The entry can contain metadata and optional files, represented by InboxFileHandle objects. A private key may be provided for encryption purposes.

Params

inboxId

String

The unique identifier of the inbox to which the entry will be sent, provided as a String.

data

Data

The main content of the entry, provided as Data.

inboxFilesHandles

[privmx.InboxFileHandle]

An array of InboxFileHandle objects representing any files that should be attached to the entry.

userPrivateKey

String?

An optional private key for encryption, provided as a String. Otherwise random key is used.

func prepareEntry(
in inboxId: String,
containing data: Data,
attaching inboxFilesHandles: [privmx.InboxFileHandle],
as userPrivateKey: String?
) throws -> privmx.InboxHandle

Returns

privmx.InboxHandle · An InboxHandle object representing the prepared entry that can be sent.

sendEntry(to:)

Sends a previously prepared entry to its corresponding inbox. This method sends an entry that has been prepared using prepareEntry. The InboxHandle must be passed, which represents the entry that was previously prepared for submission.

Params

inboxHandle

privmx.InboxHandle

The handle of the prepared entry to be sent, provided as an InboxHandle.

func sendEntry(
to inboxHandle: privmx.InboxHandle
) throws -> Void

Returns

`` · This method returns Void and does not provide any result on success.

readEntry(_:)

Reads the content of a specific inbox entry identified by its entry ID. This method retrieves the content and metadata of an inbox entry based on its unique identifier. Read access to the Inbox is required to successfully read its content.

Params

inboxEntryId

String

The unique identifier of the inbox entry to read, provided as a String.

func readEntry(
_ inboxEntryId: String
) throws -> privmx.endpoint.inbox.InboxEntry

Returns

privmx.endpoint.inbox.InboxEntry · An InboxEntry object representing the full content and metadata of the specified entry.

listEntries(from:basedOn:)

Lists all entries in the specified inbox, based on the provided paging query. This method retrieves a list of inbox entries associated with a specific inbox ID, with the results potentially being paginated according to the provided PagingQuery.

Params

inboxId

String

The unique identifier of the inbox from which entries will be listed, provided as a String.

pagingQuery

privmx.endpoint.core.PagingQuery

The query object that defines the pagination settings, such as limit and offset.

func listEntries(
from inboxId: String,
basedOn pagingQuery: privmx.endpoint.core.PagingQuery
) throws -> privmx.InboxEntryList

Returns

privmx.InboxEntryList · An InboxEntryList object containing the list of entries and associated pagination details.

deleteEntry(_:)

Deletes a specific inbox entry identified by its entry ID. This method removes the inbox entry identified by the provided entry ID, deleting its content and metadata. Full access to the inbox is required to successfully perform the deletion.

Params

inboxEntryId

String

The unique identifier of the inbox entry to delete, provided as a String.

func deleteEntry(
_ inboxEntryId: String
) throws -> Void

Returns

`` · This method returns Void and does not provide any result on success.

createFileHandle(withPublicMeta:withPrivateMeta:forSize:)

Creates a file handle for attaching files to an inbox entry. This method prepares a file handle, including public and private metadata, as well as the file size. The file handle is used when attaching files to an inbox entry before sending.

Params

publicMeta

Data

Public metadata for the file, provided as Data.

privateMeta

Data

Private metadata for the file, provided as Data.

fileSize

Int64

The size of the file in bytes, provided as an Int64.

func createFileHandle(
withPublicMeta publicMeta: Data,
withPrivateMeta privateMeta: Data,
forSize fileSize: Int64
) throws -> privmx.InboxFileHandle

Returns

privmx.InboxFileHandle · An InboxFileHandle object representing the prepared file that can be attached to an inbox entry.

writeToFile(_:in:uploading:)

Writes a chunk of data to a file associated with a prepared inbox entry. This method uploads a chunk of data to a file that is part of a prepared inbox entry. The InboxFileHandle represents the file, and the InboxHandle represents the entry being prepared.

Params

inboxFileHandle

privmx.InboxFileHandle

The handle of the file to which data will be written, provided as an InboxFileHandle.

inboxHandle

privmx.InboxHandle

The handle of the inbox entry that the file is associated with, provided as an InboxHandle.

dataChunk

Data

The chunk of data to be uploaded, provided as Data.

func writeToFile(
_ inboxFileHandle: privmx.InboxFileHandle,
in inboxHandle: privmx.InboxHandle,
uploading dataChunk: Data
) throws -> Void

Returns

`` · This method returns Void and does not provide any result on success.

openFile(_:)

Opens a file associated with the given file ID and returns a file handle. This method opens a file based on its unique file ID and returns a handle that can be used to read from or write to the file. The file must be closed using closeFile after operations are completed.

Params

fileId

String

The unique identifier of the file to open, provided as a String.

func openFile(
_ fileId: String
) throws -> privmx.InboxFileHandle

Returns

privmx.InboxFileHandle · An InboxFileHandle object representing the opened file, which can be used for further operations.

readFromFile(withHandle:length:)

Reads a specified number of bytes from an open file. This method reads up to length bytes from a file, starting from the current file pointer position, and returns the data as a Data object.

Params

fileHandle

privmx.InboxFileHandle

The handle of the file to read from, provided as an InboxFileHandle.

length

Int64

The number of bytes to read from the file, provided as an Int64.

func readFromFile(
withHandle fileHandle: privmx.InboxFileHandle,
length: Int64
) throws -> Data

Returns

Data · A Data object containing the bytes read from the file.

seekInFile(withHandle:toPosition:)

Moves the file pointer to a specified position within a file. This method adjusts the file pointer to the given position in a file associated with the provided file handle. It is useful for reading from or writing to a specific part of a file.

Params

fileHandle

privmx.InboxFileHandle

The handle of the file to seek in, provided as an InboxFileHandle.

position

Int64

The position (in bytes) to move the file pointer to, provided as an Int64.

func seekInFile(
withHandle fileHandle: privmx.InboxFileHandle,
toPosition position: Int64
) throws -> Void

Returns

`` · This method returns Void and does not provide any result on success.

closeFile(withHandle:)

Closes an open file associated with the given file handle. This method closes a file that was opened using openFile. It ensures that all pending changes are written and that the file handle is released.

Params

fileHandle

privmx.InboxFileHandle

The handle of the file to close, provided as an InboxFileHandle.

func closeFile(
withHandle fileHandle: privmx.InboxFileHandle
) throws -> String

Returns

String · A String representing the result or status after closing the file.

subscribeForInboxEvents()

Subscribes to receive general inbox events. This method subscribes to receive notifications or events related to all inboxes.

func subscribeForInboxEvents(
) throws -> Void

Returns

`` · This method returns Void and does not provide any result on success.

unsubscribeFromInboxEvents()

Unsubscribes from receiving general inbox events. This method unsubscribes the client from receiving notifications or events related to inboxes.

func unsubscribeFromInboxEvents(
) throws -> Void

Returns

`` · This method returns Void and does not provide any result on success.

subscribeForEntryEvents(in:)

Subscribes to receive entry events for a specific inbox. This method subscribes to receive notifications or events related to entries within the specified inbox. Once subscribed, the client will be notified of any changes or updates to the entries in the inbox.

Params

inboxId

String

The unique identifier of the inbox to subscribe to for entry events, provided as a String.

func subscribeForEntryEvents(
in inboxId: String
) throws -> Void

Returns

`` · This method returns Void and does not provide any result on success.

unsubscribeFromEntryEvents(in:)

Unsubscribes from receiving entry events for a specific inbox. This method unsubscribes the client from receiving notifications or events related to entries within the specified inbox. It stops further event notifications for that inbox.

Params

inboxId

String

The unique identifier of the inbox to unsubscribe from entry events, provided as a String.

func unsubscribeFromEntryEvents(
in inboxId: String
) throws -> Void

Returns

`` · This method returns Void and does not provide any result on success.