Uploading Files

In this section, we will guide you through the process of uploading a file to a Store. This 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.

Small Files

Writing whole file at once:

	// add file to the specified Store
	auto sampleFileMeta {core::Buffer::from("sample file data")};
 
    std::string exampleFileMeta = "{\"name\":\"some_file_name\"}";
 
	auto fileHandle {storesApi.createFile(storeId, 
	        core::Buffer::from("file's public meta-data"), 
        	core::Buffer::from(exampleFileMeta),
			sampleFileData.size()
	)};
 
	storesApi.writeToFile(fileHandle, sampleFileData);
	auto fileId {storesApi.closeFile(fileHandle)};

Streaming

For larger files or scenarios where you need more control over the upload process (e.g. managing upload progress, pausing, or canceling uploads), we recommend using streaming. Streaming allows you to upload the file in chunks, enabling better interactivity, monitoring, and control.

Streaming is especially useful when:

• You need to upload large files and a single upload might take a long time;
• You need the ability to cancel the upload in the middle of the process.

Uploading large file - writing to Store chunk by chunks:

	std::string filePath {"file.zip"};
	std::string filePrivMeta = "{\"name\":\"" +filePath+ "\"}";
	auto sizeTotal = std::filesystem::file_size(filePath);
 
	auto binaryFileHandle {storesApi.createFile(storeId, core::Buffer::from("file's public meta-data"), 
        core::Buffer::from(filePrivMeta), sizeTotal
	)};
	
	// read from disk and upload chunks to the Bridge
	std::ifstream fin(filePath, std::ios::binary);
    std::vector<char> buffer (1024,0);
 
	while(!fin.eof()) {
		auto chunkSize {fin.read(buffer.data(), buffer.size()).gcount()};
		storesApi.writeToFile(binaryFileHandle, core::Buffer::from(buffer.data(), chunkSize));
		if (!fin.good()) {
			break;
		}
	}
	auto binaryFileId {storesApi.closeFile(binaryFileHandle)};
	fin.close();

Notes

• Metadata: helps you identify files later on by storing additional information about them. You can use both private metada (which might contain sensitive or internal data) and public metada (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.