PrjWriteFileData function (projectedfslib.h)

Article
08/23/2022

Provides the data requested in an invocation of the PRJ_GET_FILE_DATA_CB callback.

Syntax

HRESULT PrjWriteFileData(
  [in] PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT namespaceVirtualizationContext,
  [in] const GUID                           *dataStreamId,
  [in] void                                 *buffer,
  [in] UINT64                               byteOffset,
  [in] UINT32                               length
);

Parameters

[in] namespaceVirtualizationContext

Opaque handle for the virtualization instance.

If the provider is servicing a PRJ_GET_FILE_DATA_CB callback, this must be the value from the VirtualizationInstanceHandle member of the callbackData passed to the provider in the callback.

[in] dataStreamId

Identifier for the data stream to write to.

If the provider is servicing a PRJ_GET_FILE_DATA_CB callback, this must be the value from the DataStreamId member of the callbackData passed to the provider in the callback.

[in] buffer

Pointer to a buffer containing the data to write. The buffer must be at least as large as the value of the length parameter in bytes. The provider should use PrjAllocateAlignedBuffer to ensure that the buffer meets the storage device's alignment requirements.

[in] byteOffset

Byte offset from the beginning of the file at which to write the data.

[in] length

The number of bytes to write to the file.

Return value

HRESULT_FROM_WIN32(ERROR_OFFSET_ALIGNMENT_VIOLATION) indicates that the user's handle was opened for unbuffered I/O and byteOffset is not aligned to the sector size of the storage device.

Remarks

The provider uses this routine to provide the data requested in an invocation of its PRJ_GET_FILE_DATA_CB callback.

The provider’s PRJ_GET_FILE_DATA_CB callback is invoked when the system needs to ensure that a file contains data. When the provider calls PrjWriteFileData to supply the requested data the system uses the user’s FILE_OBJECT to write that data to the file. However the system cannot control whether that FILE_OBJECT was opened for buffered or unbuffered I/O. If the FILE_OBJECT was opened for unbuffered I/O, reads and writes to the file must adhere to certain alignment requirements. The provider can meet those alignment requirements by doing two things:

Use PrjAllocateAlignedBuffer to allocate the buffer to pass to buffer.
Ensure that byteOffset and length are integer multiples of the storage device’s alignment requirement (length does not have to meet this requirement if byteOffset + length is equal to the end of the file). The provider can use PrjGetVirtualizationInstanceInfo to retrieve the storage device’s alignment requirement.

The system leaves it up to the provider to calculate proper alignment because when processing a PRJ_GET_FILE_DATA_CB callback the provider may opt to return the requested data across multiple PrjWriteFileData calls, each returning part of the total requested data.

Note that if the provider is going to write the entire file in a single call to PrjWriteFileData, i.e. from byteOffset = 0 to length = size of the file, the provider does not have to do any alignment calculations. However it must still use PrjAllocateAlignedBuffer to ensure that buffer meets the storage device's alignment requirements. See the File Buffering topic for more information on buffered vs unbuffered I/O.

Requirements

Requirement	Value
Minimum supported client	Windows 10, version 1809 [desktop apps only]
Minimum supported server	Windows Server [desktop apps only]
Target Platform	Windows
Header	projectedfslib.h

Share via