ITaskScheduler::AddWorkItem method (mstask.h)

Article
02/22/2024

[[This API may be altered or unavailable in subsequent versions of the operating system or product. Please use the Task Scheduler 2.0 Interfaces instead.] ]

The AddWorkItem method adds a task to the schedule of tasks.

Syntax

HRESULT AddWorkItem(
  [in] LPCWSTR            pwszTaskName,
  [in] IScheduledWorkItem *pWorkItem
);

Parameters

[in] pwszTaskName

A null-terminated string that specifies the name of the task to add. The task name must conform to Windows NT file-naming conventions, but cannot include backslashes because nesting within the task folder object is not allowed.

[in] pWorkItem

A pointer to the task to add to the schedule.

Return value

The AddWorkItem method returns one of the following values.

Return code	Description
S_OK	The operation was successful.
ERROR_FILE_EXISTS	A task with the specified name already exists. The actual return value is HRESULT_FROM_WIN32(ERROR_FILE_EXISTS).
E_INVALIDARG	One or more of the arguments is not valid.
E_OUTOFMEMORY	Not enough memory is available to complete the operation.

Remarks

Task scheduler provides two methods for adding work items: NewWorkItem and AddWorkItem. Of these methods, each has its specific advantage. AddWorkItem prevents naming collisions, but it also requires two disk write operations per call. One write operation is performed when the call to AddWorkItem creates an empty work item object on the disk, followed by another write operation when IPersistFile::Save is called.

NewWorkItem does not prevent naming collisions, but it requires only one disk write operation when IPersistFile::Save is called. Although NewWorkItem is more efficient with disk write operations, the application runs the risk of having another application create a work item with the same name before the call to IPersistFile::Save is made.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	mstask.h
Library	Mstask.lib
DLL	Mstask.dll
Redistributable	Internet Explorer 4.0 or later on Windows NT 4.0 and Windows 95