IBackgroundCopyJob::TakeOwnership method

Changes ownership of the job to the current user.

Syntax

HRESULT TakeOwnership(

);

Parameters

This method has no parameters.

Return Value

This method returns the following HRESULT values, as well as others.

Return code Description
S_OK
Job ownership was successfully changed.
BG_E_INVALID_STATE
The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.
BG_E_NEW_OWNER_NO_FILE_ACCESS
The new owner has insufficient access to the temporary files on the client computer. BITS creates the temporary files using the owner's security permissions.
BG_E_NEW_OWNER_DIFF_MAPPING
The current owner's network drive mapping for the local file is different from the previous owner's.
E_ACCESSDENIED
User does not have administrator privileges.

Remarks

To take ownership of the job, the user must have administrator privileges on the client. On Windows Vista, the user must run in an elevated state. After taking ownership, any future updates to the job must be done while the user is running in an elevated state. For details, see Users and Network Connections.

An administrator does not have to take ownership of another user's job to change its properties or to add files to the job. Typically, an administrator uses the TakeOwnership method if the user does not have sufficient permission to complete the job or if the user is not logged on and the administrator needs the job to complete.

After ownership of the job has changed, the job is processed only when the new owner is logged on to the client. Call the IBackgroundCopyJob::GetOwner method to retrieve the SID of the new owner.

If the administrator cancels the job after taking ownership, it is possible that the files may be orphaned because the administrator does not have write permission to the files. This can occur if the local file destination is in the previous user's roaming profile.

The TakeOwnership method removes credentials, certificates, custom headers, and command line notification from the job, if set.

If the job specifies event notification, the callback is executed in the context of the user who called the IBackgroundCopyJob::SetNotifyInterface method.

Requirements

   
Minimum supported client Windows XP
Minimum supported server Windows Server 2003
Target Platform Windows
Header bits.h
Library Bits.lib
DLL QmgrPrxy.dll

See Also

IBackgroundCopyJob::GetOwner