////////////////////////////////////////////////////////////
//
// Copyright (c) Microsoft Corporation.
//
// SYNOPSIS
//
//    IDL source for interaction with System health 
//    validators.
//
////////////////////////////////////////////////////////////

#ifndef NAPSYSTEMHEALTHVALIDATOR_IDL
#define NAPSYSTEMHEALTHVALIDATOR_IDL

import "NapTypes.idl";
import "unknwn.idl";

interface INapServerCallback;
interface INapSystemHealthValidationRequest;


// System health validators must implement the following 
// interface so that the NAP system can communicate 
// with it. SHVs must populate registry with registration 
// information, so that the NAP system can 
// instantiate it.
// 
[object, 
uuid(EF43D87C-5B6D-4820-8620-868907FE07D3), 
async_uuid(2516031A-A391-454d-B53D-C5DC84C7F2DB),
pointer_default(unique)]
interface INapSystemHealthValidator : IUnknown
{
   // The NAP system calls this API to validate the 
   // SoHRequest received from a client. 
   // 
   // In order to support intrusion detection, SHVs will be
   // asked to validate the client machine irrespective of 
   // whether or not the client sent an SoHRequest destined
   // for the SHV. 
   //
   // The validator must do the following:
   // 
   // 1). Retrieve the SoHRequest from the 'request' object.
   // 
   // 2). If the SoHRequest packet is null, then 
   //     a). If the SHV is an intrusion detection system, 
   //         then populate an SoH-Response packet with the 
   //         appropriate error code as to why the client 
   //         machine is malicious.
   //     b). All other SHVs should populate an SoHResponse 
   //         packet with an error code of 
   //         NAP_E_MISSING_SOH.
   //
   // 3). If the napAgentGenerated value is TRUE, the SHV
   //      should expect an SoH packet with the following
   //      3 TLVs :
   //      napAttributeTypeSystemHealthId,
   //      napAttributeTypeFailureCategory,
   //      napAttributeTypeErrorCodes
   //      This SoHRequest is generated by the NapAgent on
   //      behalf of the SHA since there was an error in 
   //      retrieving a request packet from the SHA.
   //      
   // 4). Validate the format of the SoH-Request packet. 
   //     If the SoHRequest is malformed, then construct
   //     an SoHResponse packet with error code 
   //     NAP_E_INVALID_PACKET.
   //
   // 5). Validate the SoHRequest packet.
   //     a). If the SHV is only using cached information to
   //         validate the SoHRequest packet (i.e. no I/O is 
   //         performed), then it can construct the 
   //         SoHResponse, set it on the 'request' object 
   //         and return S_OK.
   //     b). If the SHV is doing I/O to talk to its 
   //         back-end servers to validate the client's 
   //         health, then it must queue up the I/O and 
   //         return this function with E_PENDING. In this 
   //         case, the SHV must call Callback.OnComplete()
   //         on a separate thread within the timeout 
   //         period. Otherwise, the SHV's response 
   //         will be dropped.
   //
   // 6). If any other error code is returned by the SHV 
   //     (eg. some system error), then the packet will be 
   //     discarded.
   // 
   // Parameters:-
   // request: pointer to the validation request object.
   // hintTimeOutInMsec: the SHV should respond within this
   //    timeout; otherwise, the response is dropped.
   // callback: pointer to the callback object.
   // 
   // Return values:-
   // S_OK: indicates that the validator has set a 
   //       SoHResponse on the 'request' object.
   // E_PENDING: indicates that OnComplete() will be called 
   //       on a separate thread.
   // RPC_S_SERVER_UNAVAILABLE: indicates that the SHV
   //       process terminated without the NapServer actually
   //       releasing a reference to it.
   //       The NapServer will try to re-create a new
   //       reference to the SHV and if re-execute the
   //       Validate call just once.
   //       If the creation of the object or the re-excuted
   //       Validate fails, the SHV is removed from the
   //       list of loaded SHVs.  The only way this SHV can
   //       now be reloaded is to unregister and reregister
   //       the SHV again, or when the NapServer restarts
   // <any other error code>: if any other error code is 
   //       returned, then the system assumes 
   //       serverComponent failure has occured, and the 
   //       appropriate mapping is done to pass/fail.
   // 
   // The SHV must not hold references to the request object
   // or the 'callback' object once the async call completes
   // 
   // 
   // Failure-Category:
   // An SHV can return either one of two TLVs in its 
   // SoH-Response:
   //   1). Compliance-Result-Code TLV: If the SHV could
   //       validate the health of the client (i.e. healthy
   //       or unhealthy), then this TLV is returned.
   //   2). Failure-Category TLV: If there was any component
   //       or communication failure either on the client
   //       or server, then that must be indicated in this 
   //       TLV. This TLV will further be mapped to healthy
   //       or unhealthy using the SHV's config. For more
   //       details, see the INapServerManagement interface.
   //       
   HRESULT
   Validate(
      [in] INapSystemHealthValidationRequest* request,
      [in] UINT32 hintTimeOutInMsec,
      [in] INapServerCallback* callback
      );
};


// System health validators use this interface to talk to 
// the NAP system
// 
[object, 
uuid(09C20568-F30C-489b-AE9C-4930AD7F165F), 
pointer_default(unique)]
interface INapServerCallback : IUnknown
{
   // SHVs use this API to signal async request completion.
   // 
   // Parameters:-
   // errorCode: indicates the reason why the validation 
   //    could not be performed. Validators must indicate 
   //    S_OK if SoHRequest validation could be completed 
   //    (whether or not the SoHRequest passed the 
   //    health check).
   // 
   HRESULT
   OnComplete(
      [in] INapSystemHealthValidationRequest* request,
      [in] HRESULT errorCode
      );
};


[object, 
uuid(ADACB3A0-D4F4-4f17-8933-51D60FCCA606), 
pointer_default(unique)]
interface INapSystemHealthValidationRequest : IUnknown
{
   // Validators must log this information
   //
   HRESULT
   GetCorrelationId([out] CorrelationId* correlationId) const;

   // Validators must log this information.
   // 
   HRESULT
   GetStringCorrelationId(
      [out] StringCorrelationId** correlationId
      ) const;

   // Validators must log this information.
   // 
   HRESULT
   GetMachineName([out] CountedString** machineName) const;

   // Validators retrieve the SoHRequest information sent by 
   // their agent counterpart on the client-side using the 
   // following function. This may return null if the client
   // didn't send an SoHRequest destined for the validator.
   // 
   // Parameters:-
   // napAgentGenerated: the SoH was created by the        
   //     NapAgent on behalf of the SHA.  Primarily used to
   //     indicate an SHA failure to the SHV. The format of
   //     the SoH is as follows:
   //      System-Health-Id = <id>
   //      Failure-Category = clientComponentFailure
   //      Error-Codes = <sha-failure-error-code>
   // 
   HRESULT
   GetSoHRequest(
      [out] SoHRequest** sohRequest,
      [out] BOOL* napSystemGenerated
      ) const;

   // Validators set the SoHResponse to be sent to their 
   // agent counterpart on the client-side using the 
   // following function.
   // 
   HRESULT
   SetSoHResponse([in] const SoHResponse* sohResponse);
   HRESULT
   GetSoHResponse([out] SoHResponse** sohResponse) const;

   // NapServer stores some state information here.
   //
   // Parameters:-
   // privateData: blob that only the NapServer can interpret
   //
   HRESULT
   SetPrivateData([in] const PrivateData* privateData);
   HRESULT
   GetPrivateData([out] PrivateData** privateData) const;
};

[object, 
uuid(91A5D706-0CB4-4a84-8315-9380D453E385), 
pointer_default(unique)]
interface INapSystemHealthValidationRequest2 : INapSystemHealthValidationRequest
{
	HRESULT
	GetConfigID([out] UINT32* configID) const;
};


#endif // NAPSYSTEMHEALTHVALIDATOR_IDL