CreateFileAsBinaryDataStorage

return_code_t PLATFORM_NATIVE_CALLING_CONVENTION CreateFileAsBinaryDataStorage(const char* pFileName, std::size_t cbFileName, std::uint32_t nAccess, std::uint32_t nCreationDisposition, IDataStorage** ppDataStorage) noexcept;

Создает представление файла в виде источника последовательных бинарных данных с произвольным доступом.

Параметры

[in]	pFileName	Имя файла, заданное UTF-8 строкой.
	cbFileName	Размер имени файла, в байтах.
	nAccess	Битовая маска флагов запрашиваемого доступа к файлу. Значения флагов: Символическое имя Целочисленное значение Семантика FileRead 1 Право на чтение из файла. FileWrite 2 Право на запись в файл. FileReadWrite 3 Право на чтение и запись в файл.
	nCreationDisposition	Метод создания файла. Может одно из следующих значений. Символическое имя Целочисленное значение Семантика FileCreateAlways 0 Создание файла - всегда. В случае если файл существует, его содержимое удаляется. FileOpenAlways 1 Открытие файла - всегда. Если файл не существует, он создается. FileCreateNew 2 Создание нового файла. Если файл не существует, возвращается ошибка CHSVERROR_ALREADY_EXISTS. FileOpenExisting 3 Открытие существующего файла. Если файл не существует, возвращается ошибка CHSVERROR_NOT_FOUND. FileTruncateExisting 4 Открытие существующего файла с удалением его содержимого. Если файл не существует, возвращается ошибка CHSVERROR_NOT_FOUND.
[out]	ppDataStorage	Указатель, который на выходе успешно завершившегося вызова принимает указатель на реализацию интерфейса IBinaryDataBase, который по окончанию использования необходимо закрывать методом Release. В случае ошибки, выходное значение устанавливается в 0.

Возвращаемое значение:

32-битовый целый код ошибки, который в случае успешного выполнения является неотрицательным (т.е. старший бит значения является сброшенным).

Возвращаемое представление источника данных имеет программный интерфейс IDataStorage, который необходимо конкретизировать вызовами методов IsInterfaceAvailable и RepresentAs к конкретному типу. Гарантируется поддержка как минимум одного из интерфейсов IContiguousDataStorageInput, IContiguousDataStorageOutput и/или IContiguousDataStorage в зависимости от значения параметра nAccess. Элементом файлового накопителя, создаваемого функцией CreateFileAsBinaryDataStorage, является байт, а потоки чтения и записи поддерживают интерфейсы IFileInputByteStream и IFileOutputByteStream.

Возможно открытие нескольких представлений для одного и того же файла. В случае разделения доступа к файлу, синхронизация доступа осуществляется средствами клиента. Гарантируется безопасное параллельное чтение из файла. Безопасность параллельной записи гарантируется лишь в случае, если изменяемые области файла не пересекаются, и размер файла в результате записи не изменяется (т.е. не осуществляется его увеличение при записи в/за конец файла или его уменьшение вызовом методов IContiguousDataStorage::DeleteBlock или IContiguousDataStorage::EraseContent).

Каждый из успешно полученных экземпляров источника данных, включая экземпляры, полученные с помощью метода RepresentAs необходимо закрывать вызовом соответствующего метода Release.

Пример:

	char l_filename[] = "./somefile";
	std::size_t cb_filename = sizeof(l_filename) - 1 /*term. 0*/;

	IContiguousDataStorage* pIO = nullptr;
	IDataStorage* pStorage = nullptr;
	return_code_t err = CreateFileAsBinaryDataStorage(l_filename, cb_filename, FileRead | FileWrite, FileCreateAlways, &pStorage);
	if (err < 0)
		goto cleanup; //failure of CreateFileAsBinaryDataStorage
	err = pStorage->IsInterfaceAvailable(ContiguousDataStorageType);
	if (err < 0)
		goto cleanup; //failure of IsInterfaceAvailable
	err = pStorage->RepresentAs(ContiguousDataStorageType, (void**) &pIO);
	if (err < 0)
		goto cleanup; //failure of RepresentAs
	
	//access the file via pIO...
	
cleanup:
	if (pStorage)
		pStrorage->Release();
	if (pIO)
		pIO->Release();