ReadData Event
Fires when the cache needs to read file data from external storage.
Syntax
public event OnReadDataHandler OnReadData; public delegate void OnReadDataHandler(object sender, FilecacheReadDataEventArgs e); public class FilecacheReadDataEventArgs : EventArgs { public string FileId { get; } public long Size { get; } public long Position { get; } public int Flags { get; } public byte[] Buffer { get; } public int BytesToRead { get; } public int BytesRead { get; set; } public long FileContext { get; } public int ResultCode { get; set; } }
Public Event OnReadData As OnReadDataHandler Public Delegate Sub OnReadDataHandler(sender As Object, e As FilecacheReadDataEventArgs) Public Class FilecacheReadDataEventArgs Inherits EventArgs Public ReadOnly Property FileId As String Public ReadOnly Property Size As Long Public ReadOnly Property Position As Long Public ReadOnly Property Flags As Integer Public ReadOnly Property Buffer As Byte() Public ReadOnly Property BytesToRead As Integer Public Property BytesRead As Integer Public ReadOnly Property FileContext As Long Public Property ResultCode As Integer End Class
Remarks
This event fires when the cache needs to read data for the cached file identified by FileId from external storage.
The Size parameter reflects the specified file's "real size", as it is currently known by the cache.
The Position parameter reflects the byte offset in the real file (i.e., the one in external storage) from which the application should start reading data.
The Flags parameter provides supplementary information about the nature of the request. This parameter, along with the Size and Position parameters, helps the application to determine which part of the file Buffer represents, and whether additional ReadData events should be expected. It will be a combination of one or more of the following flags:
RWEVENT_IN_PROGRESS | 0x00000001 | A file's data is being transferred into or out of the cache. |
RWEVENT_CANCELED | 0x00000002 | A data transfer has been cancelled for some reasons. |
RWEVENT_WHOLE_FILE | 0x00000004 | The entire file is being transferred. |
RWEVENT_CONTINUOUS_STARTED | 0x00000010 | A continuous transfer has started. |
RWEVENT_CONTINUOUS_RESTARTED | 0x00000020 | A continuous transfer has restarted from the beginning. |
RWEVENT_CONTINUOUS_FINISHED | 0x00000040 | A continuous transfer is finishing (i.e., the current block is the final one). |
RWEVENT_RANDOM_STARTED | 0x00000100 | A random-access transfer has started. |
RWEVENT_RANDOM_FINISHED | 0x00000200 | A random-access transfer is finishing (i.e., the current block is the final one). |
RWEVENT_BEFORE_END | 0x00001000 | The current transfer will finish before the end of the file. |
RWEVENT_TIL_END | 0x00002000 | The current transfer will last until the end of the file. |
To handle this event property, applications must read BytesToRead bytes of data from the real file in external storage, starting at the specified Position, into Buffer. When reading is complete, applications must set BytesRead to reflect the actual number of bytes read from the real file. Applications must not attempt to copy more than BytesToRead bytes of data into Buffer.
The FileContext parameter reflects the application-defined value passed when OpenFile was called.
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 one of the following values to report an appropriate error:
RWRESULT_SUCCESS | 0x00000000 | Success.
Return if all data was successfully transferred. |
RWRESULT_PARTIAL | 0x00000080 | Partial success.
Return if some, but not all, data was successfully transferred. I.e., when BytesRead < BytesToRead (for ReadData), or BytesWritten < BytesToWrite (for WriteData). |
RWRESULT_RANGE_BEYOND_EOF | 0x00000081 | Requested range is beyond the end of the file (EOF).
For the ReadData event, returning this code indicates to the cache that there is no need to request data beyond (Position + BytesRead), and that the tail should be zeroed instead. |
RWRESULT_FILE_MODIFIED_EXTERNALLY | 0x00000082 | The specified file's size was modified externally. |
RWRESULT_FILE_MODIFIED_LOCALLY | 0x00000083 | The requested file's size was modified locally. |
RWRESULT_FAILURE | 0x0000008D | The operation failed for some transient reason.
Returning this code indicates that, while the current request failed, it is safe to continue sending requests for both the specified file and others. (Other operations may continue.) |
RWRESULT_FILE_FAILURE | 0x0000008E | The operation failed for some external-file-related reason.
Returning this code indicates that some failure related to the external file itself has occurred, and it is expected that any further requests made against that file will also fail. The cache will not send any more requests for the specified file until the application calls ResetFileErrors to reset the error state. |
RWRESULT_PERMANENT_FAILURE | 0x0000008F | The operation failed for some external-storage-related reason.
Returning this code indicates that some failure related to the external storage itself has occurred, and it is expected that all further requests will also fail. The cache will not send any more requests until the application calls ResetExternalError to reset the error state. |
Please refer to the Error Reporting and Handling topic for more information.