FilePasswordNeeded Event

Fires if a password is needed to open an encrypted file.

Syntax

• C++
• Objective-C
• C

ANSI (Cross Platform)
virtual int FireFilePasswordNeeded(CBDriveFilePasswordNeededEventParams *e);

typedef struct {
  const char *FileName;
  char *Password;
  int lenPassword;
  int ResultCode;
  int reserved;
} CBDriveFilePasswordNeededEventParams;

Unicode (Windows)
virtual INT FireFilePasswordNeeded(CBDriveFilePasswordNeededEventParams *e);

typedef struct {
  LPCWSTR FileName;
  LPWSTR Password;
  INT lenPassword;
  INT ResultCode;
  INT reserved;
} CBDriveFilePasswordNeededEventParams;

- (void)onFilePasswordNeeded:(NSString*)fileName :(NSString**)password :(int*)resultCode;

#define EID_CBDRIVE_FILEPASSWORDNEEDED 7

virtual INT CBFSSTORAGE_CALL FireFilePasswordNeeded(LPWSTR &lpszFileName, LPWSTR &lpPassword, INT &lenPassword, INT &iResultCode);

Remarks

This event fires when the encrypted file specified by FileName is being opened if a valid password has not been provided (either directly, or via the DefaultFilePassword property or CacheFilePassword method). This event will not fire if a valid password has already been provided, or if the file specified by FileName does not exist in the vault.

To allow access to the specified file, set the Password parameter to the correct password. Note that the value must be copied to Password; set lenPassword to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

To prevent access to the specified file, return the CBFSSTORAGE_ERR_INVALID_PASSWORD error code via ResultCode.

Note that this event can be fired on different threads, and possibly even on several threads concurrently. As an alternative to handling this event, applications can provide a default file encryption password using the DefaultFilePassword property, and/or call the CacheFilePassword method (before a file is opened) to specify a one-time-use password.

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.

Note: when a storage is opened concurrently in read-only mode by several applications using CBDrive or CBMemDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.