INapSystemHealthAgentCallback::GetSoHRequest method

Article
08/25/2021

Note

The Network Access Protection platform is not available starting with Windows 10

The INapSystemHealthAgentCallback::GetSoHRequest method is called by the NapAgent to query the system health agent's SoH request.

Syntax

HRESULT GetSoHRequest(
  [in] INapSystemHealthAgentRequest *request
);

Parameters

request [in]: A COM pointer to an INapSystemHealthAgentRequest object that identifies the request object.

Return value

Return code	Description
S_OK	Indicates success.
HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE)	If this code is returned by your implementation, the NapAgent then removes the SHA from the bound-SHA list and flushes its cache entry.

When any return value (except HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE)) is returned by your implementation, the NAP system constructs and returns a SoHRequest to the corresponding SHV with the following attribute types and values:

sohAttributeTypeSystemHealthId= <id>
sohAttributeTypeFailureCategory= failureCategoryClientComponent
sohAttributeTypeErrorCodes = <error-code>

Remarks

This callback method is declared by the NAP system and is to be implemented by the SHA writer.

This method must process the request and return immediately. Delaying the return of this method negatively impacts system performance and responsiveness, and may cause other parts of the operating system to time out.

Health state monitoring should not be done as part of this call, especially if it is computation intensive and takes a long time. Health state monitoring and SoH computation should be performed in a separate thread or service. The sole function of this method should be to set the SHA's SoH and return.

If it will take a long time for the SHA to generate a SoH, then the cached SoH should be returned to the NapAgent. If there is no cached SoH to return, then the SHA should immediately return a SoH with the following attribute types and values:

When the SoH has been generated, the SHA must call INapSystemHealthAgentBinding::NotifySoHChange to notify the NapAgent of the system health change.

The NapAgent calls this method to query the system health agent's SoHRequest. The SHA can query the passed INapSystemHealthAgentRequest object for parameters that it needs to compute the SoHRequest. The SHA must set the computed SoHRequest on the request object. The SHA must not hold references to the request object once this call has completed.

When this method is called, if there is a SoH in the NapAgent's cache, then it is set on the request object. The SHA can query for it using GetSoHRequest. If the SHA does not set a new SoH, then the cached one is used.

For unbound SHAs which are registered with the system, the NAP system constructs and sends a SoHRequest to the corresponding SHV with the following attribute types and values:

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Header	NapSystemHealthAgent.h
IDL	NapSystemHealthAgent.idl