3.2.5.1.1 OnNewTrackingInfo (Opnum 3)

The OnNewTrackingInfo method handles a tracker event from the server.

 HRESULT OnNewTrackingInfo(
   [in] IUnknown* pToplevelCollection
 );

pToplevelCollection: An interface pointer of a DCOM object. This MUST be a TrackingInfoCollection OBJREF_CUSTOM (section 2.2.5.5). This collection SHOULD be of type TRKCOLL_PROCESSES (as specified in section 2.2.5.5), and each TrackingInfoObject in the collection SHOULD represent a process on the server. Each process TrackingInfoObject structure SHOULD have the following properties.

Property name	vt value	Meaning
ProcessID	0x00000013	The process identifier.
ExeName	0x00000008	Implementation-specific identifier of the type of process.<25>
Paused	0x00000013	TRUE (0x00000001) if the distinguished container for the process is paused; otherwise, FALSE (0x00000000).
Recycling	0x00000013	TRUE (0x00000001) if the distinguished instance container for the process is recycled; otherwise, FALSE (0x00000000).
IsService	0x00000013	TRUE (0x00000001) if the process is a system service; otherwise, FALSE (0x00000000). The definition of system service is implementation-specific.<26>
Applications	0x0000000D	A TrackingInfoCollection (section 2.2.5.5) of type TRKCOLL_CONTAINERS that represents the instance containers in the process.

Each instance container TrackingInfoObject SHOULD have the following properties.

Property name	vt value	Meaning
ApplicationID	0x00000008	The CurlyBraceGuidString (section 2.2.1) representation of the conglomeration identifier of the conglomeration that is associated with the instance container.
ApplInstanceID	0x00000008	The CurlyBraceGuidString (section 2.2.1) representation of the container identifier of the instance container.
ApplicationType	0x00000013	An implementation-specific<27> integer that identifies the type of instance container.
PartitionID	0x00000008	The CurlyBraceGuidString (section 2.2.1) representation of the Partition ID of the conglomeration.
Name	0x00000008	An implementation-specific<28> Unicode string that provides a human-readable name for the conglomeration that is associated with the instance container.
Components	0x0000000D	A TrackingInfoCollection (section 2.2.5.5) of type TRKCOLL_COMPONENTS that represents the components instantiated in the instance container.

Each component TrackingInfoObject SHOULD have the following properties:

Property name	vt value	Meaning
CLSID	0x00000008	The CurlyBraceGuidString (section 2.2.1) representation of the CLSID of the component.
Objects	0x00000013	The number of component instances for the component in an instance container.
Activated	0x00000013	The number of active component instances for the component in an instance container.
Pooled	0x00000013	The number of pooled component instances for the component in an instance container.
InCall	0x00000013	The number of component instances for the component in an instance container that are currently performing a method call.
CallTime	0x00000013	A value that indicates the average amount of time, in milliseconds, that it takes to complete method calls to component instances for the component. The calculation of this value is implementation-specific.<29>
Name	0x00000008	An implementation-specific Unicode string that provides a human-readable name for the component.<30>

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

Upon receiving a call to the OnNewTrackingInfo method, the client MUST attempt to unmarshal the TrackingInfoCollection OBJREF_CUSTOM received in pToplevelCollection and fail the call if it cannot. The client SHOULD then return before performing any further actions. Any further implementation-specific processing SHOULD be done asynchronously.