4.8 GetChildPaths Call Example

  • Article

The client initiates a connection to the server through standard DCOM calls, as specified in [MS-DCOM].

 The client uses the OpenKey method and provides the following parameters to get a handle to the metabase data:

  • METADATA_MASTER_ROOT_HANDLE, which causes the server to open a key relative to the root.

  • "/LM/W3SVC", which tells the server to open the lm/w3svc key under the root.

  • METADATA_PERMISSION_READ, which asks the server to open the key with read privileges.

  • 10, which tells the server to time out after 10 milliseconds if it cannot open the key.

  • A pointer to a handle that the server will fill in with the handle to the node that has been opened.

If the OpenKey call is successful, the client calls the GetChildPaths method, providing the following parameters to determine from the server how much space is required for a successful call to the GetChildPaths method:

  • The handle to the key opened by the OpenKey method.

  • An empty string, which is used by the server to locate the child paths relative to the handle passed in the first parameter.

  • Zero, which indicates the size of the buffer passed in the next parameter. In this first call to the GetChildPaths method, the buffer size is set to zero, because the client is attempting to determine the correct size for the buffer.

  • NULL. While this parameter is normally used as the buffer to hold the child paths, on this first call to the GetChildPaths method, the client is only attempting to determine how large the buffer has to be, and therefore this parameter is set to NULL.

  • A pointer to a DWORD. The server will fill in the DWORD with the correct number of bytes to be used as the buffer size in the subsequent call to the GetChildPaths method.

The call to the GetChildPaths method is expected to return an ERROR_INSUFFICIENT_BUFFER error code and, in the last parameter, the number of bytes needed by the buffer in order to hold all of the child paths. If the call to the GetChildPaths method fails for any other reason, the client will exit.

Once the client has been informed of the number of bytes needed to hold all of the child paths, it will allocate a buffer of that size.

The client then calls the GetChildPaths method again to provide the following parameters:

  • The handle to the key opened by the OpenKey method.

  • An empty string, which is used by the server to locate the child paths relative to the handle passed in the first parameter.

  • The number of bytes to allocate for the buffer that will hold the child paths. The number of bytes to allocate was returned by the first call to the GetChildPaths method.

  • The allocated buffer that will hold the child paths. The size of the buffer is specified in the previous parameter.

  • A pointer to a DWORD. If the server determines that the number of bytes specified in the third parameter is not sufficient to allocate a buffer large enough to hold all the child paths, the server will fill in the DWORD with the correct number of bytes to allocate for the buffer.

 If the child paths were successfully retrieved, the client parses the buffer to locate each child path string. The client searches for an occurrence of double terminating null characters and, when found, processes the child path. The client continues parsing the buffer until the end of the data is reached.