RenameOrMoveFile Event

Fires when the OS wants to rename or move a file or directory within the virtual filesystem.

Syntax

ANSI (Cross Platform)
virtual int FireRenameOrMoveFile(CBFSRenameOrMoveFileEventParams *e);
typedef struct {
const char *FileName;
const char *NewFileName;
void *FileContext;
int ResultCode; int reserved; } CBFSRenameOrMoveFileEventParams; Unicode (Windows) virtual INT FireRenameOrMoveFile(CBFSRenameOrMoveFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LPCWSTR NewFileName;
LPVOID FileContext;
INT ResultCode; INT reserved; } CBFSRenameOrMoveFileEventParams;
#define EID_CBFS_RENAMEORMOVEFILE 37

virtual INT CBFSCONNECT_CALL FireRenameOrMoveFile(LPWSTR &lpszFileName, LPWSTR &lpszNewFileName, LPVOID &lpFileContext, INT &iResultCode);

Remarks

This event fires when the OS wants to rename or move the specified file or directory from FileName to NewFileName, both of which are fully-qualified and located in the virtual filesystem.

This event only fires if a file or directory with the specified NewFileName does not exist; or if such a file does exist, and an overwrite was requested. Cases where a file with the specified NewFileName exists, and an overwrite was not requested, are handled by the class internally. (Note that Windows only allows files to be overwritten, and denies a rename or move request automatically if the destination is an existing directory.)

To handle this event properly, applications must perform any actions needed to rename or move the specified file or directory in their backend storage, overwriting the destination file if necessary. An application may also, for its own reasons, decide not to overwrite a destination file, in which case it must deny the operation by returning an appropriate error code via ResultCode.

When the FastRenameMove configuration setting is disabled, any handles to the file being renamed are closed before the rename operation and re-opened after the operation. If the rename operation fails, then the file handles are re-opened using the old name. If any of re-open operations fail, the re-opening process is stopped, and any handles that have been re-opened already are closed again.

In any case, the value specified by the ResultCode parameter is passed back to the system.

The FileContext parameter is a placeholder for application-defined data associated with the file. Please refer to the Contexts topic for more information.

Note: If the FastRenameMove config setting is disabled, all handles would be closed before the event fires; so, FileContext will be empty. To receive the correct value in this parameter, you need to enable the FastRenameMove config setting.

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) 2022 Callback Technologies, Inc. - All rights reserved.
CBFS Connect 2020 C++ Edition - Version 20.0 [Build 8348]