3.5.4.1 GetChildPaths (Opnum 40)

  • Article

The GetChildPaths method returns all child nodes of a specified path from a supplied metadata handle.

 HRESULT GetChildPaths(
     [in] METADATA_HANDLE hMDHandle,
     [unique, in, string] LPCWSTR pszMDPath,
     [in] DWORD cchMDBufferSize,
     [in, out, unique, size_is(cchMDBufferSize)] WCHAR *pszBuffer,
     [in, out, unique] DWORD *pcchMDRequiredBufferSize
 );

hMDhandle: An unsigned 32-bit integer value specifying a handle to a node in the metabase with read permissions as returned by the OpenKey method, or the METADATA_MASTER_ROOT_HANDLE.

pszMDPath: A pointer to a Unicode string that contains the path of the node to be opened, relative to the hMDHandle parameter.

cchMDBufferSize: The size, in WCHAR, of the pszBuffer buffer to hold the paths for all child nodes under the path specified.

pszBuffer: A pointer to a Unicode character buffer passed in by the caller to store the retrieved child paths. The return data will be a set of WCHAR strings, where each includes two terminating null characters.

pcchMDRequiredBufferSize: An integer value indicating the required size of the buffer if the supplied buffer proves to be insufficient. If the supplied buffer is sufficient, this value will not be adjusted.

Return Values: A signed 32-bit value that indicates return status. If the method returns a negative value, it failed. If the 12-bit facility code (bits 16–27) is set to 0x007, the value contains a Win32 error code in the lower 16 bits. Zero or positive values indicate success, with the lower 16 bits in positive nonzero values containing warnings or flags defined in the method implementation. For more information about Win32 error codes and HRESULT values, see [MS-ERREF].

Return value/code

Description

0x80070000

S_OK

The call was successful.

0x80070003

ERROR_PATH_NOT_FOUND

The system cannot find the path specified.

0x80070057

E_INVALIDARG

One or more arguments are invalid.

0x80070005

ERROR_ACCESS_DENIED

Access is denied.

0x80070008

ERROR_NOT_ENOUGH_MEMORY

Not enough storage is available to process this command.

0x8007000E

E_OUTOFMEMORY

There was not enough memory to complete the method call.

0x8007007A

ERROR_INSUFFICIENT_BUFFER

The data area passed to a system call is too small.

0x800700A0

ERROR_BAD_ARGUMENTS

One or more arguments are not correct.

0x80004005

E_FAIL

An unspecified error occurred.

0x80070006

E_HANDLE

An invalid handle was passed.

0x800CC800

MD_ERROR_NOT_INITIALIZED

Metadata has not been initialized.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].

The opnum field value for this method is 40.

 When processing this call, the server MUST do the following:

  • The server returns all child paths that are relative to the path provided under the node that is represented by the hMDHandle parameter. The server MUST return these as a list of WCHAR strings, where each string includes the terminating null character, and the entire list is also followed by a terminating null character.

  • The strings returned by the server MUST be compatible with the format used by the OpenKey method to open those nodes for retrieving data.

  • If the hMDHandle parameter is not a valid open handle to the metadata (retrieved by calling OpenKey), the server MUST return an E_HANDLE error code.

  • If the path requested does not exist in the metadata, the server MUST return the HRESULT derived from the ERROR_PATH_NOT_FOUND error code.

  • If the cchMDBufferSize parameter is not large enough to contain the child path strings that include the terminating null character, the server MUST return the HRESULT derived from the ERROR_INSUFFICIENT_BUFFER error code, and the server MUST set the pcchMDRequiredBufferSize value to the size needed.