3.2.5.4.8 SchRpcEnumTasks (Opnum 7)

The SchRpcEnumTasks method MUST return the list of tasks in a specific folder.

MUST returns S_FALSE if there are more tasks to enumerate.

Note that if client requests items 1-10 and then 11-20, the second call can return duplicate entries if the task list has changed in between calls.

 HRESULT SchRpcEnumTasks(
   [in, string] const wchar_t* path,
   [in] DWORD flags,
   [in, out] DWORD* startIndex,
   [in] DWORD cRequested,
   [out] DWORD* pcNames,
   [out, string, size_is(, *pcNames)] 
     TASK_NAMES* pNames
 );

path: MUST contain the full path associated with a folder as specified in section 2.3.11.

flags: The flags parameter MUST contain individual bit flags that MUST have one or more of the following values:

0	1	2	3	4	5	6	7	8	9	1 0	1	2	3	4	5	6	7	8	9	2 0	1	2	3	4	5	6	7	8	9	3 0	1
0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	H

Value	Description
H TASK_ENUM_HIDDEN	If set to 1, the server MUST include hidden tasks in the enumeration, otherwise the server MUST exclude hidden tasks from the enumeration.

startIndex: MUST contain the index at which to start enumeration. If the server returns S_FALSE, the server MUST update startIndex to contain the index at which the enumeration MUST resume.

cRequested: MUST contain the number of entries requested. The server MUST NOT return more than cRequested entries.

pcNames: The server MUST set pcNames to equal the number of enumerated tasks returned in the pNames parameter.

pNames: Buffer that MUST contain returned task names.

Return Values: For more information on return codes, see section 2.3.14, or Win32 Error Codes in [MS-ERREF] section 2.1.

Upon receipt of the SchRpcEnumTasks call, the server MUST:

• Return E_INVALIDARG if the out parameters are NULL or if any bit other than TASK_ENUM_HIDDEN is set in the flags parameter.

  Note When passing NULL as a value for parameters, behavior can change based upon the RPC Runtime Check. See RPC Runtime Check Notes (section 3.3).

• Return the value 0x8007007B, the HRESULT form of the Win32 error ERROR_INVALID_NAME, if the specified path is not in the format specified in section 2.3.11.

• Return the value 0x80070003, the HRESULT form of the Win32 error ERROR_PATH_NOT_FOUND, if the specified path does not exist on the server in the XML task store.

• Return the HRESULT version of the Win32 error ERROR_FILE_NOT_FOUND if the path parameter does not name a folder in the XML task store, or if the caller does not have either read or write access to that folder.

• Enumerate the tasks in that folder, starting the enumeration at the ordinal position given by the DWORD value pointed to by the pStartIndex parameter. The server MUST NOT enumerate more than cRequested tasks. The server MUST enumerate as many tasks as are available, up to a total of cRequested tasks. The server MUST skip tasks that the caller does not have read or write access to. The server MUST skip tasks that are hidden (section 2.5.4.12) unless the TASK_ENUM_HIDDEN bit is set in the flags parameter.<72>

• Return an array of pointers to the enumerated null-terminated task names in the pNames parameter.

• Return the number of enumerated task names in the pcNames parameter.

• Increment the value pointed to by the pStartIndex parameter by the number of enumerated task names.

• Return S_OK if there are no more names to enumerate, else return S_FALSE.