3.2.5.4.7 SchRpcEnumFolders (Opnum 6)

The SchRpcEnumFolders method MUST retrieve a list of folders on the server.

The server MUST return S_FALSE if there are more folders to enumerate.

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

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

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

flags: All bits except TASK_ENUM_HIDDEN MUST be set to zero and the server MUST return an error if undefined bits are set to 1. This field has 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

Where the bits are defined as:

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.

pStartIndex: 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: MUST contain a count of enumerated subfolder names contained in pNames.

pNames: Buffer MUST contain returned folder 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 SchRpcEnumFolders 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 on the RPC Runtime Check. See RPC Runtime Check Notes (section 3.3).

• Return the value 0x80070003, the HRESULT version of the Win32 error ERROR_PATH_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 subfolders 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 subfolders. The server MUST enumerate as many subfolders as are available, up to a total of cRequested subfolders. The server MUST skip subfolders that the caller does not have read or write access to.<71>

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

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

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

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

If any errors are raised during the processing they are returned. For more information on return codes, see section 2.3.14 and Win32 Error Codes in [MS-ERREF] section 2.1.