CreateFileAsBinaryDataStorage

 return_code_t CreateFileAsBinaryDataStorage(const char* pszFileName, std::size_t cbFileName, std::uint32_t nAccess, FileCreationDisposition nCreationDisposition, IBinaryDataBase** ppDataStorage) noexcept;

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

Параметры

[in]	pszFileName	Имя файла, заданное 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-битовый целый код ошибки, который в случае успешного выполнения является неотрицательным (т.е. старший бит значения является сброшенным).

Возвращаемое представление источника данных имеет программный интерфейс IBinaryDataBase, который необходимо конкретизировать вызовами методов IsInterfaceAvailable и RepresentAs к конкретному типу.

Возвращаемый через параметр ppDataStorage экземпляр источника данных может поддерживать интерфейсы произвольного доступа: IInputBinaryDataContiguousAccess, IOutputBinaryDataContiguousAccess или IIOBinaryDataContiguousAccess (а также их базовые интерфейсы) - в зависимости от разрешенного доступа.

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

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

Пример:

char l_filename[] = "./somefile";
IIOBinaryData* pIO; //uninitialized pointer
{
   IBinaryDataBase* pStorage; //uninitialized pointer
   int32_t err = CreateFileAsBinaryDataStorage(l_filename, sizeof(l_filename), FileRead | FileWrite, FileCreateAlways, std::addressof(pStorage)) noexcept;

   if (err < 0)
      return -1; //failure
   if (pStorage->IsInterfaceAvailable(IOBinaryDataType) == 1)
      return 0; //Interface is not available
   err = pStorage->RepresentAs(IOBinaryDataType, std::addressof(pIO));
   if (err < 0)
      return -1; //failure of RepresentAs
}
//access file via pIO...