Share via

3.1.4.2.2 DumpProcess (Opnum 8)

  • Article

This method is called by a client to request a process dump for the process containing a particular instance container.

 [id(2)] HRESULT DumpProcess(
   [in] BSTR bstrContainerID,
   [in] BSTR bstrDirectory,
   [in] DWORD dwMaxFiles,
   [out, retval] BSTR* pbstrDumpFile
 );

bstrContainerID: The CurlyBraceGuidString (section 2.2.1) representation of a container identifier for a distinguished container.

bstrDirectory: Either a path, in the convention of the server's file system, to a location in which the file produced by process dump is to be written, or NULL to indicate that the client wants the COMT server to write the file to an implementation-specific default location.

dwMaxFiles: The maximum number of process dump files associated with the conglomeration of the instance container identified by the bstrContainerID parameter that the client requests the COMT server to leave in the location specified by the bstrDirectory parameter before the server begins deleting previously written files. A value of 0x00000000 indicates that the COMT server is to use an implementation-specific default limit.

pbstrDumpFile: A pointer to a variable that, upon successful completion, contains a fully qualified path, in the convention of the server's file system, to the process dump file written.

Return Values: This method MUST return S_OK (0x00000000) on success and a failure result (as specified in [MS-ERREF] section 2.1) on failure.

When this method is invoked, if the server does not support process dump, it MUST simply return E_NOTIMPL (0x80004001). Otherwise, the server MUST verify that the bstrContainerID parameter identifies a tracked instance container, and that this instance container is a distinguished container, and fail the call if not.

The server then MUST verify that the bstrDirectory parameter, if not NULL, is in a file path syntax supported<20> by the server and fail the call if not. If bstrDirectory is not NULL, the server MUST select the location specified by this parameter as the dump file location, the use of which is described later in this section. Otherwise, the server MUST select an implementation-specific <21> default location.

The server then MUST select the dump file limit, the use of which is described later in this section, as the value specified by the dwMaxFiles parameter if this parameter is nonzero, and an implementation-specific <22> default limit if this parameter is zero.

The server SHOULD<23> impersonate the client while performing any file access specified in the remainder of the method behavior.

The server then SHOULD attempt to determine the number of previously written process dump files that are associated with the conglomeration of the instance container identified in bstrContainerID in the dump file location, and MAY fail the call if it cannot do so. If the number of previously written files is greater than or equal to the dump file limit, the server SHOULD attempt to delete at least one of the previously written files, and MAY fail the call if it cannot do so. If more than one previously written file exists, the server SHOULD attempt to determine which of these files was written least recently, and SHOULD select that file for deletion.

The server then MUST attempt to perform an implementation-specific <24> process dump procedure by writing a file to the dump file location, and fail the call if it cannot.

The server then MUST set the pbstrDumpFile parameter to the fully qualified path to the file written, and return success.