NdfDiagnoseIncident function (ndfapi.h)
The NdfDiagnoseIncident function diagnoses the root cause of an incident without displaying a user interface.
Syntax
void NdfDiagnoseIncident(
[in] NDFHANDLE Handle,
[out] ULONG *RootCauseCount,
[out] RootCauseInfo **RootCauses,
DWORD dwWait,
DWORD dwFlags
);
Parameters
[in] Handle
Type: NDFHANDLE
A handle to the Network Diagnostics Framework incident.
[out] RootCauseCount
Type: ULONG*
The number of root causes that could potentially have caused this incident. If diagnosis does not succeed, the contents of this parameter should be ignored.
[out] RootCauses
Type: RootCauseInfo**
A collection of RootCauseInfo structures that contain a detailed description of the root cause. If diagnosis succeeds, this parameter contains both the leaf root causes identified in the diagnosis session and any non-leaf root causes that have an available repair. If diagnosis does not succeed, the contents of this parameter should be ignored.
Memory allocated to these structures should later be freed. For an example of how to do this, see the Microsoft Windows Network Diagnostics Samples.
dwWait
Type: DWORD
The length of time, in milliseconds, to wait before terminating the diagnostic routine. INFINITE may be passed to this parameter if no time-out is desired.
dwFlags
Type: DWORD
Possible values:
| Value | Meaning |
|---|---|
|
Turns on network tracing during diagnosis. Diagnostic results will be included in the Event Trace Log (ETL) file returned by NdfGetTraceFile. |
|
Applies filtering to the returned root causes so that they are consistent with the in-box scripted diagnostics behavior. Without this flag, root causes will not be filtered. This flag must be set by the caller, so existing callers will not see a change in behavior unless they explicitly specify this flag.
Note Available only in Windows 8 and Windows Server 2012.
|
Return value
Type: HRESULT
Possible return values include, but are not limited to, the following.
| Return code | Description |
|---|---|
|
The operation succeeded. |
|
The NDF incident handle is not valid. |
|
The diagnostic routine has terminated because it has taken longer than the time-out specified in dwWait. |
Remarks
This function is intended for use with scenarios where no user interface is shown, or where the standard Windows experience is not being used (as with Media Center and embedded applications). NdfExecuteDiagnosis will launch the diagnostics user interface, and should be used in scenarios using the standard Windows experience. You can call either NdfExecuteDiagnosis or NdfDiagnoseIncident, but not both.
Before using this API, an application must call an incident creation function such as NdfCreateWebIncident to begin the NDF diagnostics process. The application then calls NdfDiagnoseIncident to diagnose the issue. If the diagnostics process identifies some possible repairs, the application can call NdfRepairIncident to repair the problem without displaying a user interface. NdfCancelIncident can optionally be called from a separate thread if the application wants to cancel an ongoing NdfDiagnoseIncident call. Finally, the application calls NdfCloseIncident.
The following table shows some examples of root causes and their corresponding repairs.
| Root cause GUID | Repair GUID | Root cause description | Repair description |
| {4DA030B8-86E5-4b6a-A879-2FFF8443B527} | {1296DFF0-D04E-4be1-A512-90F04DDFA3E6} | A network cable is not properly plugged in or may be broken. | Plug an Ethernet cable into this computer.\nAn Ethernet cable looks like a telephone cable but with larger connectors on the ends. Plug this cable into the opening on the back or side of the computer.\nMake sure the other end of the cable is plugged into the router. If that does not help, try using a different cable. |
| {60372FD2-AD60-45c2-BD83-6B827FC438DF} | {07d37f7b-fa5e-4443-bda7-ab107b29afb6} | The %InterfaceName% adapter is disabled. | Enable the %FriendlyInterfaceName% adapter. |
| {245A9D66-AE9C-4518-A5B4-655752B0A5BD} | {07d37f7b-fa5e-4443-bda7-ab107b29afb9} | %InterfaceName%"" doesn't have a valid IP configuration. | Reset the ""%InterfaceName%"" adapter.\nThis can sometimes resolve an intermittent problem. |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 7 [desktop apps only] |
| Minimum supported server | Windows Server 2008 R2 [desktop apps only] |
| Target Platform | Windows |
| Header | ndfapi.h |
| Library | Ndfapi.lib |
| DLL | Ndfapi.dll |