IBackgroundCopyJob3::SetFileACLFlags method
Specifies the owner and ACL information to maintain when using SMB to download or upload a file.
Syntax
HRESULT SetFileACLFlags(
[in] DWORD Flags
);
Parameters
Flags [in]
Flags that identify the owner and ACL information to maintain when transferring a file using SMB. Subsequent calls to this method overwrite the previous flags. Specify 0 to remove the flags from the job. You can specify any combination of the following flags.Value Meaning BG_COPY_FILE_OWNER If set, the file's owner information is maintained. Otherwise, the user who calls the Complete method owns the file.
You must have SeRestorePrivilege to set this flag. The administrators group contains the SeRestorePrivilege privilege.
BG_COPY_FILE_GROUP If set, the file's group information is maintained. Otherwise, DO uses the job owner's primary group to assign the group information to the file.
You must have SeRestorePrivilege to set this flag. The administrators group contains the SeRestorePrivilege privilege.
BG_COPY_FILE_DACL If set, DO copies the explicit ACEs from the source file and inheritable ACEs from the destination folder. Otherwise, DO copies the inheritable ACEs from the destination folder. If the destination folder does not contain inheritable ACEs, DO uses the default DACL from the owner's account.
BG_COPY_FILE_SACL If set, DO copies the explicit ACEs from the source file and inheritable ACEs from the destination folder. Otherwise, DO copies the inheritable ACEs from the destination folder.
You must have SeSecurityPrivilege on both the local and remote computers to set this flag. The administrators group contains the SeSecurityPrivilege privilege.
BG_COPY_FILE_ALL If set, DO copies the owner and ACL information. This is the same as setting all the flags individually.
Return value
This method returns the following HRESULT values, as well as others.
| Return code | Description |
|---|---|
| S_OK | Successfully set the flags. |
| BG_E_INVALID_STATE | You must call this method before the job transitions to the BG_JOB_STATE_TRANSFERRED state. |
| E_INVALIDARG | The Flags parameter contains a flag that is not in the list. |
Remarks
These flags apply to remote file names that specify the SMB protocol. DO ignores the flags for HTTP transfers.
DO propagates the file time stamps and attributes (not extended attributes) for SMB files.
DO applies the owner and ACL information to the file at the time the file transfer is complete, not when it creates the temporary transfer file. DO does not specify a security descriptor when it creates the temporary transfer file (the file inherits the ACL information from the destination directory). If the transferred data is sensitive, the application should specify an appropriate ACL on the destination directory to prevent unauthorized access.
To ensure the proper owner and ACL information is set on all files in the job, call this method after you create the job and before calling the IBackgroundCopyJob::Resume method. Otherwise, those files that transferred before the flags were set will not contain the appropriate owner and ACL information.
This method is modeled after the XCopy DOS command.
The owner and ACL information is not maintained if you download to a FAT file system.
If the user does not have privileges on the local and remote computers to copy the owner or ACL information, DO places the job in a transient error state and sets the error code to E_ACCESSDENIED.
Requirements
Minimum supported client |
Windows 10, version 1709 [desktop apps only] |
Minimum supported server |
Windows Server 2016 [desktop apps only] |
Header |
Deliveryoptimization.h |
IDL |
DeliveryOptimization.idl |
Library |
Dosvc.lib |
DLL |
Dosvc.dll |
IID |
IID_IBackgroundCopyJob3 is defined as 443C8934-90FF-48ED-BCDE-26F5C7450042 |