WriteData Event
Fires when the cache needs to write file data to external storage.
Syntax
public event OnWriteDataHandler OnWriteData; public delegate void OnWriteDataHandler(object sender, FilecacheWriteDataEventArgs e); public class FilecacheWriteDataEventArgs : EventArgs { public string FileId { get; } public long Size { get; } public long Position { get; } public int Flags { get; } public byte[] Buffer { get; } public int BytesToWrite { get; } public int BytesWritten { get; set; } public long FileContext { get; } public int ResultCode { get; set; } }
Public Event OnWriteData As OnWriteDataHandler Public Delegate Sub OnWriteDataHandler(sender As Object, e As FilecacheWriteDataEventArgs) Public Class FilecacheWriteDataEventArgs 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 BytesToWrite As Integer Public Property BytesWritten As Integer Public ReadOnly Property FileContext As Long Public Property ResultCode As Integer End Class
Remarks
This event fires when the cache needs to write data for the cached file identified by FileId to 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) at which the application should start writing 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 WriteData 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 properly, applications must write BytesToWrite bytes of data from Buffer to the real file in external storage, starting at the specified Position. When writing is complete, applications must set BytesWritten to reflect the actual number of bytes written to the real file. Applications must not attempt to copy more than BytesToWrite bytes of data from 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.