UpdateHeaderUnsafe and UpdateHeaderUnsafeFQP methods

This method is deprecated.

Provides a mechanism to update the header of an encrypted file, even if the file is currently in use by another process.

Syntax

HRESULT

UpdateHeaderUnsafe(

  [in] REFGUID VolumeGuid,

  [in] BSTR RelativePath,

  [in] VARIANT *OldHeader,

  [in] VARIANT *NewHeader

)

HRESULT

UpdateHeaderUnsafeFQP(

  [in] BSTR Fqp,

        [in] VARIANT *OldHeader,

  [in] VARIANT *NewHeader

)

Parameters

VolumeGuid[in]

GUID representing a local volume.  This GUID must not be the FESF Network Volume GUID (FE_NETWORK_GUID) or the FESF Shadow Volume GUID (FE_SHADOW_VOLUME_GUID) and must not be NULL or empty.

RelativePath [in]

A path, relative to the supplied Volume GUID.

FQP [in]

A Fully Qualified (Windows) Path to a file on a local volume. File must not be located on a network share.

OldHeader [in]

The current file header.

NewHeader [in]

The new file header.

Return value

If the method succeeds, S_OK is returned.

If the method fails for any reason, an appropriate error code is returned.

Remarks

Important: This method is deprecated and is pending removal from FESF. Do not use it. Convert existing code that uses it as soon as possible. Use the equivalent function provided by the FesfUtil2 Library.

This method will change the file header of a currently open file.  It is an extra-ordinarily dangerous method to call since the rest of the stack is unaware that the header has changed and so such a change must not involve a change to the encryption key – otherwise the file will have been hopelessly and irretrievably corrupted.

After a successful call to this method, the updated header is passed to the Policy DLL callbacks on subsequent opens of the file.

The call will fail if:

•      The new header size is not the same as the old header size.

•      The provided old header does not match the current (on disk) header.

•      The file is not on a local disk.

•      The caller does not have SeRestorePrivilege.

•      The file is not FESF encrypted.

The caller of this API is responsible for protecting a file against multiple, simultaneous header updates. The results are undefined if simultaneous calls to UpdateHeaderUnsafe/UpdateHeaderUnsafeFQP are made to a file.

Examples

See Also

Requirements