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,the total size of the file that will be uploaded, and set up a flag that tells whether the file has the random write feature enabled.

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.

Creating a File

// ...

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

// ...

Creating a File with Random Write Support

// ...

auto sampleData {core::Buffer::from("some sample data")};
auto fh {storeApi.createFile(STORE_ID, core::Buffer::from(""), core::Buffer::from(""), sampleData.size(), true)};	
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
);
// ...

Updating a File

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);
// ...

Updating a File with Random Write Support

To update the data of the particular file, that has random write flag enabled, you have to use the openFile(...) method. The openFile(...) method is used when you want to modify a fragment of file data. It requires the file to have random write support and creates a read/write handle, allowing you to write new data to any position in the file. When using the read/write handle, data is always sent to the server after each writeToFile(...) call.

// ...
auto fileNewData {core::Buffer::from("some new data")};

// opening a file
auto readWriteHandle {storeApi.openFile(fileId)};

// overwriting part of an open file with new data from the beginning
storeApi.seekInFile(readWriteHandle, 0);
storeApi.writeToFile(readWriteHandle, fileNewData);

// reading from an open file from the beginning
storeApi.seekInFile(readWriteHandle, 0);
core::Buffer newReadData {storeApi.readFromFile(readWriteHandle, fileNewData.size())};
std::cout << newReadData.stdString() << std::endl;
// ...

Deleting a File

To delete a file, you need to use the deleteFile(...) method.

// ...
storeApi.deleteFile(fileId);
// ...