PrivMXStore

Protocol declaring methods of StoreApi using Swift types, enabling interaction with PrivMX Stores and Files.

Methods

listStores(from:basedOn:)

Lists the Stores that the user has access to within a specified context. This method retrieves a list of all Stores accessible to the user in the given context. The list can be filtered and paginated using the provided query.

func listStores(
	from contextId: String,
	basedOn query: privmx.endpoint.core.PagingQuery
) throws -> privmx.StoreList

Name	Type	Description
contextId	String	The unique identifier of the context from which Stores should be listed.
query	privmx.endpoint.core.PagingQuery	A paging query object to filter and paginate the results.

Type	Description
privmx.StoreList	A `endpoint::core::PagingList<endpoint::store::Store> (`privmx.StoreList`) instance containing the list of Stores.

getStore(_:)

Retrieves detailed information about a specific Store. This method returns the details of a Store, such as its metadata and associated users, identified by its unique store ID.

func getStore(
	_ storeId: String
) throws -> privmx.endpoint.store.Store

Name	Type	Description
storeId	String	The unique identifier of the Store to retrieve.

Type	Description
privmx.endpoint.store.Store	A `privmx.endpoint.store.Store` instance containing the Store’s metadata and details.

createStore(in:for:managedBy:withPublicMeta:withPrivateMeta:)

Creates a new Store in the specified context, with defined users and managers. This method creates a new Store within a specific context, associating users and managers with it. The Store will also have public and private metadata attached to it.

func createStore(
	in contextId: String,
	for users: [privmx.endpoint.core.UserWithPubKey],
	managedBy managers: [privmx.endpoint.core.UserWithPubKey],
	withPublicMeta publicMeta: Data,
	withPrivateMeta privateMeta: Data
) throws -> String

Name	Type	Description
contextId	String	The unique identifier of the context in which the Store will be created.
users	[privmx.endpoint.core.UserWithPubKey]	A list of `UserWithPubKey` objects representing users who will have access to the Store.
managers	[privmx.endpoint.core.UserWithPubKey]	A list of `UserWithPubKey` objects representing managers responsible for the Store.
publicMeta	Data	The public metadata associated with the Store, which will not be encrypted.
privateMeta	Data	The private metadata associated with the Store, which will be encrypted.

Type	Description
String	A `String` representing the ID of the newly created Store.

deleteStore(_:)

Deletes a specific Store identified by its unique ID. This method removes the Store along with its associated data from the Bridge.

func deleteStore(
	_ storeId: String
) throws -> Void

Name	Type	Description
storeId	String	The unique identifier of the Store to be deleted.

updateStore(_:atVersion:replacingUsers:replacingManagers:replacingPublicMeta:replacingPrivateMeta:force:forceGenerateNewKey:)

Updates an existing Store by replacing its users, managers, and metadata. This method updates an existing Store with new values, overriding the previous users, managers, and metadata. The update can be forced, and a new key can be generated if required.

func updateStore(
	_ storeId: String,
	atVersion version:Int64,
	replacingUsers users: [privmx.endpoint.core.UserWithPubKey],
	replacingManagers managers: [privmx.endpoint.core.UserWithPubKey],
	replacingPublicMeta publicMeta: Data,
	replacingPrivateMeta privateMeta: Data,
	force: Bool,
	forceGenerateNewKey: Bool
) throws -> Void

Name	Type	Description
storeId	String	The unique identifier of the Store to be updated.
version	Int64	The current version of the Store, used to ensure version consistency.
users	[privmx.endpoint.core.UserWithPubKey]	A new list of `UserWithPubKey` objects representing users who will have access to the Store.
managers	[privmx.endpoint.core.UserWithPubKey]	A new list of `UserWithPubKey` objects representing managers responsible for the Store.
publicMeta	Data	The new public metadata for the Store, which will be unencrypted.
privateMeta	Data	The new private metadata for the Store, which will be encrypted.
force	Bool	A boolean indicating whether the update should be forced, bypassing version control.
forceGenerateNewKey	Bool	A boolean indicating whether a new key should be generated for the Store.

getFile(_:)

Retrieves information about a specific File in a Store. This method returns details about a File, such as its metadata, associated with the given file ID.

func getFile(
	_ fileId: String
) throws -> privmx.endpoint.store.File

Name	Type	Description
fileId	String	The unique identifier of the File to retrieve.

Type	Description
privmx.endpoint.store.File	A `privmx.endpoint.store.File` instance containing the File’s metadata and details.

listFiles(from:basedOn:)

Lists all Files in a specified Store. This method retrieves a list of Files associated with a Store. It only provides metadata and information about the files, not their contents. To download the files themselves, use `openFile()` and `readFromFile()`.

func listFiles(
	from storeId: String,
	basedOn query: privmx.endpoint.core.PagingQuery
) throws -> privmx.FileList

Name	Type	Description
storeId	String	The unique identifier of the Store from which to list Files.
query	privmx.endpoint.core.PagingQuery	A paging query object to filter and paginate the results.

Type	Description
privmx.FileList	A `privmx.endpoint.core.FilesList` instance containing the list of Files.

createFile(in:withPublicMeta:withPrivateMeta:ofSize:)

Creates a new file handle for writing data to a File in a Store. This method creates a new file handle, which can be used to write data to a new File in the Store. Once the file is created, data can be uploaded using `writeToFile()` and finalized with `closeFile()`.

func createFile(
	in storeId: String,
	withPublicMeta publicMeta: Data,
	withPrivateMeta privateMeta: Data,
	ofSize size: Int64
) throws -> privmx.StoreFileHandle

Name	Type	Description
storeId	String	The unique identifier of the Store in which the File will be created.
publicMeta	Data	Public metadata for the File, which will be unencrypted.
privateMeta	Data	Private metadata for the File, which will be encrypted.
size	Int64	The size of the File in bytes.

Type	Description
privmx.StoreFileHandle	A `privmx.StoreFileHandle` used for writing data to the File.

updateFile(_:replacingPublicMeta:replacingPrivateMeta:replacingSize:)

Updates an existing File by overwriting its content and metadata. This method creates a new file handle for updating an existing File, allowing the content and metadata to be replaced. The file can then be written using `writeToFile()` and finalized with `closeFile()`.

func updateFile(
	_ fileId: String,
	replacingPublicMeta publicMeta: Data,
	replacingPrivateMeta privateMeta: Data,
	replacingSize size: Int64
) throws -> privmx.StoreFileHandle

Name	Type	Description
fileId	String	The unique identifier of the File to be updated.
publicMeta	Data	New public metadata for the File, which will be unencrypted.
privateMeta	Data	New private metadata for the File, which will be encrypted.
size	Int64	The new size of the File in bytes.

Type	Description
privmx.StoreFileHandle	A `privmx.StoreFileHandle` for writing data to the updated File.

openFile(_:)

Opens a File for reading and returns a file handle (`StoreFileHandle`). This method opens an existing File, identified by its file ID, and returns a handle that can be used to read the file’s content.

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

Name	Type	Description
fileId	String	The unique identifier of the File to open.

Type	Description
privmx.StoreFileHandle	A `privmx.StoreFileHandle` for reading the File’s content.

readFromFile(withHandle:length:)

Reads a specified number of bytes from an open File. This method reads a defined amount of data from a file that has been opened using a StoreFileHandle.

func readFromFile(
	withHandle handle: privmx.StoreFileHandle,
	length: Int64
) throws -> Data

Name	Type	Description
handle	privmx.StoreFileHandle	The StoreFileHandle of the opened File.
length	Int64	The number of bytes to read from the File.

Type	Description
Data	A `Data` object containing the bytes read from the File.

writeToFile(withHandle:uploading:)

Writes a chunk of data to an open File. This method uploads a chunk of data to a file that has been opened for writing using a file handle.

func writeToFile(
	withHandle handle: privmx.StoreFileHandle,
	uploading dataChunk: Data
) throws -> Void

Name	Type	Description
handle	privmx.StoreFileHandle	The handle of the opened File.
dataChunk	Data	The data to write to the File.

seekInFile(withHandle:toPosition:)

Moves the read/write cursor within an open File. This method repositions the read/write cursor in a file, allowing for random access operations such as reading or writing from a specific position.

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

Name	Type	Description
handle	privmx.StoreFileHandle	The handle of the opened File.
position	Int64	The new position for the cursor, in bytes.

closeFile(withHandle:)

Closes an open File and finalizes any pending operations. This method closes a file that was opened using `openFile()` or created with `createFile()`. It ensures that all pending write operations are completed and releases the file handle.

func closeFile(
	withHandle handle: privmx.StoreFileHandle
) throws -> String

Name	Type	Description
handle	privmx.StoreFileHandle	The handle of the opened File to close.

Type	Description
String	A `String` representing the ID of the closed File.

deleteFile(_:)

Permanently deletes a File from the platform. This method removes a file, identified by its file ID, and all its associated data from the platform.

func deleteFile(
	_ fileId: String
) throws -> Void

Name	Type	Description
fileId	String	The unique identifier of the File to delete.

subscribeForStoreEvents()

Subscribes to events related to Stores. This method allows the client to receive notifications about changes to Stores, such as updates or new Stores being created, by subscribing to Store-related events.

func subscribeForStoreEvents(
) throws -> Void

subscribeForFileEvents(in:)

Subscribes to events related to Files in a specific Store. This method subscribes to file-related events for a specific Store, enabling the client to receive notifications about changes to Files, such as uploads or deletions.

func subscribeForFileEvents(
	in storeId:String
) throws -> Void

Name	Type	Description
storeId	String	The unique identifier of the Store for which to subscribe to file events.

unsubscribeFromStoreEvents()

Unsubscribes from events related to Stores. This method stops the client from receiving notifications about Store-related events.

func unsubscribeFromStoreEvents(
) throws -> Void

unubscribeFromFileEvents(in:)

Unsubscribes from events related to Files in a specific Store. This method stops the client from receiving notifications about file-related events in a specific Store.

func unubscribeFromFileEvents(
	in storeId:String
) throws -> Void

Name	Type	Description
storeId	String	The unique identifier of the Store for which to unsubscribe from file events.