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.

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

See also

IBackgroundCopyJob3::GetFileACLFlags

IBackgroundCopyJob3