IBackgroundCopyManager::CreateJob method (bits.h)

Article
10/13/2021

Creates a job.

Syntax

HRESULT CreateJob(
  [in]  LPCWSTR            DisplayName,
  [in]  BG_JOB_TYPE        Type,
  [out] GUID               *pJobId,
  [out] IBackgroundCopyJob **ppJob
);

Parameters

[in] DisplayName

Null-terminated string that contains a display name for the job. Typically, the display name is used to identify the job in a user interface. Note that more than one job may have the same display name. Must not be NULL. The name is limited to 256 characters, not including the null terminator.

[in] Type

Type of transfer job, such as BG_JOB_TYPE_DOWNLOAD. For a list of transfer types, see the BG_JOB_TYPE enumeration.

[out] pJobId

Uniquely identifies your job in the queue. Use this identifier when you call the IBackgroundCopyManager::GetJob method to get a job from the queue.

[out] ppJob

An IBackgroundCopyJob interface pointer that you use to modify the job's properties and specify the files to be transferred. To activate the job in the queue, call the IBackgroundCopyJob::Resume method. Release ppJob when done.

Return value

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

Return code	Description
S_OK	Successfully generated the new job.
E_INVALIDARG	The display name is too long.
BG_E_TOO_MANY_JOBS_PER_MACHINE	The MaxJobsPerMachine Group Policy setting determines how many jobs can be created on the computer. Adding this job exceeds the MaxJobsPerMachine limit.
BG_E_TOO_MANY_JOBS_PER_USER	The MaxJobsPerUser Group Policy setting determines how many jobs a user can create. Adding this job exceeds the MaxJobsPerUser limit.

Remarks

Only the user who creates the job or a user with administrator privileges can add files to the job and change the job's properties.

By default, BITS supports a maximum of 300 jobs at one time. A single user can create a maximum of 60 jobs at one time. The user limit does not apply to administrators or service accounts. To change these defaults, set the MaxJobsPerMachine and MaxJobsPerUser group policies, respectively.

Prior to Windows Vista: There is no limit on the number of jobs that BITS supports or that a user can create.

For scalability concerns, see Best Practices When Using BITS.

Examples

For an example that creates a new job, see Creating a Job.

Requirements

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