OffloadReadFile Event

Fires when the OS wants the virtual filesystem to perform an offloaded data transfer (ODX) read operation.

Syntax

virtual int FireOffloadReadFile(CBFSOffloadReadFileEventParams *e);
typedef struct {
const char *FileName;
int TokenTimeToLive;
int64 Position;
int64 CopyLength;
int64 *pTransferLength;
int TokenType;
void *TokenBuffer;
int64 BufferLength;
int TokenLength;
int ResultFlags;
int64 HandleInfo;
void *FileContext;
void *HandleContext;
int ResultCode; int reserved; } CBFSOffloadReadFileEventParams;
virtual INT FireOffloadReadFile(CBFSOffloadReadFileEventParams *e);
typedef struct {
LPCWSTR FileName;
INT TokenTimeToLive;
LONG64 Position;
LONG64 CopyLength;
LONG64 *pTransferLength;
INT TokenType;
LPVOID TokenBuffer;
LONG64 BufferLength;
INT TokenLength;
INT ResultFlags;
LONG64 HandleInfo;
LPVOID FileContext;
LPVOID HandleContext;
INT ResultCode; INT reserved; } CBFSOffloadReadFileEventParams;

Remarks

This events fires when the OS wants the virtual filesystem to perform an offload read for the file specified by FileName as part of an offloaded data transfer.

To handle this event properly, applications should first verify whether the specified file supports offload operations, returning the ERROR_OFFLOAD_READ_FILE_NOT_SUPPORTED error code via ResultCode if not. Assuming the file does support offload operations, the application should perform any actions needed to prepare for the offloaded read based on the specified parameters, and then return the requested information. Please refer to the parameter descriptions below for more information.

The TokenTimeToLive parameter indicates the duration, in milliseconds, that the offload read operation remains valid. Multiple writes can be performed with the token returned in TokenBuffer until this time expires.

The Position and CopyLength parameters specify the byte offset and length (respectively) of a data chunk in the specified file that should be read, or in some other way prepared, for transferring.

The TransferLength parameter must be set to the number of bytes actually read/prepared as a result of this request. It may be less than CopyLength.

The TokenType parameter must be set to either the Microsoft-defined value of STORAGE_OFFLOAD_TOKEN_TYPE_ZERO_DATA (0xFFFF0001) if the token represents data which is all zeros; or an application-defined value outside of the reserved range 0xFFFF0002 to 0xFFFFFFFF to denote an application-defined token format. (Note: Use of the STORAGE_OFFLOAD_TOKEN_TYPE_ZERO_DATA token type is not required.)

The TokenBuffer parameter points to a memory buffer that receives some application-defined token that identifies the data that has been read/prepared for transfer. The returned token will be passed to an offload write operation in order to actually transfer the data it represents. The BufferLength parameter specifies the capacity, in bytes, of TokenBuffer; applications must set the TokenLength parameter to the number of bytes written to TokenBuffer.

Please refer to the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The ResultFlags parameter must be set to a combination of zero or more of the flags described in the FSCTL_OFFLOAD_READ_OUTPUT structure's documentation.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken. (This parameter may be absent, in which case it will be 0.)

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (HandleContext may be absent, in which case it will be NULL.)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

 
 
Copyright (c) 2020 Callback Technologies, Inc. - All rights reserved.
CBFS Connect 2020 C++ Edition - Version 20.0 [Build 7545]