Files

Stores allow you to exchange and save files. In this section, we'll take a closer look at file structures and how to manage them effectively. We'll also cover some best practices when working with Stores.

publicMeta and privateMeta fields in Files support any kind of data formats encoded to byte arrays.
Examples in this section use JSON format serialization, which is available directly in Swift.\

Sample code on this page is based on the initial assumptions.

FilePrivateMeta structure used in the code below is defined as such:

Swift

struct FilePrivateMeta:Codable{
    let name: String
    let mimetype: String
}

About Files

Along with a file's main content, additional metadata is stored to allow easy file management. Below is the structure of the metadata associated with each file:

field	type	encrypted	description
`info`	ServerFileInfo	yes	additional information assigned by the server e.g. author, `creationDate`, `storeID` and `fileID`
`publicMeta`	binary	no	additional public information about the message, also accessible through PrivMX Bridge API
`privateMeta`	binary	yes	additional information about the message
`size`	number	yes	The size of file in getBytes
`authorPubKey`	string	yes	The public key of the author of the file
`statusCode`	number	no	0 if the file was decrypted successfully

Uploading Files

The uploading process involves both uploading the file content and managing its associated metadata. Storing metadata, such as the file's name, and type, allows for easier identification and retrieval of files when needed.

We highly recommend storing the file's metadata along with the file content to make it easier to manage and interact with the uploaded file in the future.

The most basic way of uploading a File to a Store:

Swift

let storeID = "STORE_ID"
let fileContentData = Data("Text file content".utf8)

guard let storeFileHandle = try? endpointSession?.storeApi?.createFile(
    in: storeID,
    withPublicMeta: Data(),
    withPrivateMeta: Data(),
    ofSize: Int64(fileContentData.count),
	randomWriteSupport: false)
else {return}

try? endpointSession?.storeApi?.writeToFile(
	withHandle: storeFileHandle,
	uploading: fileContentData,
	truncate: false)
let storeFileId = try? endpointSession?.storeApi?.closeFile(withHandle: storeFileHandle)

Retrieving Files

Downloading information about Files

To retrieve information about a singular File call getFile(_:) method:

Swift

let fileID = "FILE_ID"
guard let file = try? endpointSession?.storeApi?
    .getFile(fileID) else {return}

Downloading a File

You can simply call the startDownloadingToFile(_:from:) method on the PrivMXEndpoint instance.
This utilizes the PrivMXStoreFileHandler under the hood.

Swift

let fileID = "FILE_ID"

let URL = URL(fileURLWithPath: "/path/to/file/Filename.txt")

guard let fileHandle =  try? FileHandle(forWritingTo: URL) else { return }

Task{
    try? await endpointSession?.startDownloadingToFile(fileHandle, from: fileID)
}

Seeking in a File

Once you acquire a handle to the File by calling openFile(_:), you can move the handle to point at any byte of the file by calling seekInFile(withHandle:toPosition:):

Swift

let fileId = "FILE_ID"
guard let readHandle = try? endpointSession?.storeApi?.openFile(fileId)
else {return}
 
try? endpointSession?.storeApi?.seekInFile(
    withHandle: readHandle,
    toPosition: 128)

Modifying Files

Updating a File

There are two ways to update a File. You can either only update its metadata, or you can reupload a new version of the File. The latter can be done in three ways similar to uploading a new file.

To only update the File's metadata call updateFileMeta(of:replacingPublicMeta:replacingPrivateMeta:):

Swift

let fileID = "FILE_ID"
let newFilePrivateMeta = FilePrivateMeta(name: "New Filename.txt", mimetype: "text/plain")

guard let file = try? endpointSession?.storeApi?.getFile(fileID),
      let newFilePrivateMetaData = try? JSONEncoder().encode(newFilePrivateMeta),
      let filePublicMetaData = file.publicMeta.getData()
else {return}

try? endpointSession?.storeApi?
    .updateFileMeta(
        of: fileID,
        replacingPublicMeta:  filePublicMetaData,
        replacingPrivateMeta: newFilePrivateMetaData)

Deleting Files

To delete a File call deleteFile(_:) method.

Swift

let fileID = "FILE_ID"
try? endpointSession?.storeApi?.deleteFile(fileID)

Working with Random Write Files

Working with a Random Write File starts from acquiring a handle.

Swift

let fileId = "FILE_ID_WITH_RW_SUPPORT"
guard let rwHandle = try? endpointSession?.storeApi?.openFile(fileId) 
else {return}

Once you have a handle you can read the File you can Read from it...

Swift

var readData = try? endpointSession?.storeApi?.readFromFile(withHandle: rwHandle, length: 128)

... move the handle to any byte of the File...

Swift

try? endpointSession?.storeApi?.seekInFile(
    withHandle: rwHandle,
    toPosition: 64)

... or overwrite parts of the File.

Swift

try? endpointSession?.storeApi?.writeToFile(
	withHandle: rwHandle,
	uploading: Data("some new data".utf8),
	truncate: true)

The size of a File with Random Write functionality adjusts dynamically.

Once you finish working with the File you should close it.

Swift

try? endpointSession?.storeApi?.closeFile(withHandle: rwHandle)

Notes

Metadata: helps you identify files later on by storing additional information about them. You can use both private metadata (which might contain sensitive or internal data) and public metadata (which can be shared publicly).
Error Handling: During the streaming process, it's important to handle potential errors, such as network interruptions, by using try-catch blocks and the ability to abort the upload.
Progress Monitoring: Streaming enables you to monitor the progress of the file upload, allowing you to display the current upload percentage to the user.

On this page