Files

Managing Files

Uploading a File

To place a file in the Store, you need to create a file handle using the createFile(...) function. The function accepts a StoreId, public and private metadata, and the total size of the file that will be uploaded.

Then you need to call writeToFile(...) providing the created file handle and a portion of data to write. For small files, you can write the entire file with one request. For large files, it's more optimal to write them piece by piece, loading them in portions, for example from the disk, and then calling writeToFile(...) on each piece. To complete the entire file upload process - call closeFile(...) with the file handle as a parameter.

// ...
 
auto sampleData {core::Buffer::from("some sample data")};
auto fh {storeApi.createFile(STORE_ID, core::Buffer::from(""), core::Buffer::from(""), sampleData.size())};	
storeApi.writeToFile(fh, sampleData);
storeApi.closeFile(fh);
 
// ...

Listing Files

To retrieve the contents of the Store, you can call the listFiles(...) function to get a list of files from the specified Store.

// ...
auto filesList {storeApi.listFiles(STORE_ID, defaultListQuery)};
for (auto file: filesList.readItems) {
    std::cout << "FileId: " << file.info.fileId << " / Size: " << file.size << std::endl;
}
// ...

As a result you will receive an object:

// filesList:
{
    readItems: [<fileObject1>, <fileObject2>,..., <fileObjectN>],
    totalAvailable: <number_of_all_files_in_the_Store>
}

A detailed description of the File object fields can be found in API Reference.

Reading a File

To read a file, you can do it with a single request or - which is usually a better solution for large files - by reading it piece by piece. You must start by opening the file for reading using the openFile(fileId) function. As a result, you'll receive a file handle that you then use when calling readFromFile(...) to read portions of data from the file. At the same time, you have the ability to move through the file and indicate from which position you want to read it using the seekInFile(...) function.

// ...
auto lastFile {filesList.readItems[0]};
 
// Reading file
auto readHandle {storeApi.openFile(lastFile.info.fileId)};
core::Buffer read {storeApi.readFromFile(readHandle, lastFile.size)};
std::cout << read.stdString() << std::endl;
// ...

Modifying Files

File modification can be considered in two categories:

1. Modifying file information.
2. Modifying data in the file.

To update information about a file, you need to use the updateFileMeta(...).

// ...
storeApi.updateFileMeta(
    lastFile.info.fileId, 
    core::Buffer::from("new public meta"), 
    lastFile.privateMeta
);
// ...

To update the data of the particular file you have to use updateFile(...) method. This method can also be used to modify metadata (just like updateFileMeta(...)), but additionally it creates a file handle allowing for writing data to the file.

// ...
auto fileNewData {core::Buffer::from("some new data")};
 
auto updateHandle {storeApi.updateFile(
    lastFile.info.fileId,
    lastFile.publicMeta,
    lastFile.privateMeta,
    fileNewData.size()
)};	
storeApi.writeToFile(updateHandle, fileNewData);
storeApi.closeFile(updateHandle);
// ...