ITaskScheduler::NewWorkItem method

[[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 NewWorkItem method creates a new work item, allocating space for the work item and retrieving its address.

Syntax


HRESULT NewWorkItem(
  [in]  LPCWSTR  pwszTaskName,
  [in]  REFCLSID rclsid,
  [in]  REFIID   riid,
  [out] IUnknown **ppunk
);

Parameters

pwszTaskName [in]

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

rclsid [in]

The class identifier of the work item to be created. The only class supported at this time, the task class, has the identifier CLSID_Ctask.

riid [in]

The reference identifier of the interface being requested. The only interface supported at this time, ITask, has the identifier IID_ITask.

ppunk [out]

A pointer to an interface pointer that receives the requested interface. See Remarks for information on saving the work item to disk.

Return value

The NewWorkItem method returns one of the following values.

Return codeDescription
S_OK

The operation was successful.

ERROR_FILE_EXISTS

A work item 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.

E_ACCESSDENIED

The caller does not have permission to perform the operation. For more information, see Scheduled Work Items.

 

Remarks

This method handles memory allocation automatically when creating the new work item.

To save the work item to disk, call IPersistFile::Save . This COM interface is supported by all work item interfaces (currently ITask is the only supported work item interface).

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 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.

You can create a task by calling AddWorkItem or NewWorkItem. When use AddWorkItem, it is your responsibility to create an instance of the Task object (which supports the ITask interface) and then add the task with the name you supply.

NewWorkItem does not prevent naming collisions, but requires only one disk write operation when IPersistFile::Save is called. Although NewWorkItem is more efficient with respect to 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.

For a complete example ofSee
Creating a new task Creating a Task Using NewWorkItem Example

 

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Redistributable

Internet Explorer 4.0 or later on Windows NT 4.0 and Windows 95

Header

Mstask.h

Library

Mstask.lib

DLL

Mstask.dll

See also

IPersistFile::Save
ITask
ITaskScheduler
ITaskScheduler::AddWorkItem

 

 

Show: