Network Diagnostics Framework

Purpose The Network Diagnostics Framework (NDF) provides a way for component and application developers to simplify network troubleshooting for users. Users can attempt to diagnose and repair a network problem using a single troubleshooting tool. Microsoft provides NDF helper classes, some of which are extensible so that developers can create troubleshooting units called helper class extensions to provide more detailed diagnoses specific to particular software or hardware components.

Where applicable NDF can be used by any vendor's software which relies on network connectivity.

Developer audience The NDF API is designed for C/C++ developers.

Run-time requirements NDF is available for computers running Windows Vista, Windows Server 2008, or later.

About NDF The Network Diagnostics Framework (NDF) reduces the involvement of network administrators and computer users by handling common network issues as they occur. By using NDF's diagnostic and repair capabilities, users and administrators do not need additional tools in order to handle some relatively common problems. NDF ships as part of Windows Vista, Windows Server 2008, and later. It is available whenever a system is booted (but cannot run in Safe Mode).

Using NDF Functionality Microsoft provides access to NDF functionality through a public API. When a problem occurs, the application can use this API to leverage this functionality within the context of a specific application. There are three stages of performing diagnosis with NDF: creating an incident, running diagnosis and repairs, and closing the incident. This overview indicates which NDF functions may be relevant for a specific scenario. Detailed information on each function can be found in the NDF Reference section.

1.Creating an Incident An NDF diagnostics session requires a specific incident to diagnose. There are several functions which can be used to create an incident. Choose the function which most closely matches what the application was trying to do when the failure occurred.

Incident types NdfCreateConnectivityIncident: General Internet connectivity problems which do not need additional information. NdfCreateWebIncident/NdfCreateWebIncidentEx: Connecting to an HTTP or HTTPS URL. NdfCreateSharingIncident: Accessing a UNC path or file share. NdfCreateDNSIncident: Resolving a DNS host name. NdfCreatePnrpIncident: Resolving a PNRP peer name. NdfCreateGroupingIncident: Joining a peer-to-peer group. NdfCreateWinSockIncident: Connecting to a destination by using a socket (when none of the other functions specifically apply). NdfCreateIncident: Used when no other scenario is appropriate and the specific NDF helper class to be invoked is known (along with the arguments it requires). Primarily used for testing purposes by application developers who have written their own helper class.

NdfCreateConnectivityIncident The NdfCreateConnectivityIncident function diagnoses generic Internet connectivity problems. Syntax (handle)Type: NDFHANDLE* - Handle to the Network Diagnostics Framework incident.

NdfCreateWebIncident The NdfCreateWebIncident function diagnoses web connectivity problems concerning a specific URL. Syntax (url)Type: LPCWSTR - The URL with which there is a connectivity issue.

NdfCreateSharingIncident The NdfCreateSharingIncident function diagnoses network problems in accessing a specific network share. Syntax (UNCPath)Type: LPCWSTR - The full UNC string (for example, "\server\folder\file.ext") for the shared asset with which there is a connectivity issue.

NdfCreateDNSIncident The NdfCreateDNSIncident function diagnoses name resolution issues in resolving a specific host name. Syntax (hostname)Type: LPCWSTR - The host name with which there is a name resolution issue. (queryType)Type: WORD - The numeric representation of the type of record that was queried when the issue occurred. For more information and a complete listing of record set types and their numeric representations, see the windns.h header file. This parameter should be set to DNS_TYPE_ZERO for generic DNS resolution diagnosis.

NdfCreatePnrpIncident The NdfCreatePnrpIncident function creates a session to diagnose issues with the Peer Name Resolution Protocol (PNRP) service. Syntax (cloundName)Type: LPCWSTR -The name of the cloud to be diagnosed. (peername)Type: LPCWSTR - Optional name of a peer node which PNRP can attempt to resolve. The results will be used to help diagnose any problems. (diagnosePublish)Type: BOOL - Specifies whether the helper class should verify that the node can publish IDs. If FALSE, this diagnostic step will be skipped. (appId)Type: LPCWSTR - Application ID for the calling application.

NdfCreateGroupingIncident The NdfCreateGroupingIncident function creates a session to diagnose peer-to-peer grouping functionality issues. Syntax

Type: SOCKET_ADDRESS_LIST* CloudName Type: LPCWSTR The name of the Peer Name Resolution Protocol (PNRP) cloud where the group is created. If NULL, the session will not attempt to diagnose issues related to PNRP. GroupName Type: LPCWSTR The name of the group to be diagnosed. If NULL, the session will not attempt to diagnose issues related to group availability. Identity Type: LPCWSTR The identity that a peer uses to access the group. If NULL, the session will not attempt to diagnose issues related to the group's ability to register in PNRP. Invitation Type: LPCWSTR An XML invitation granted by another peer. An invitation is created when the inviting peer calls PeerGroupCreateInvitation or PeerGroupIssueCredentials. If this value is present, the invitation will be checked to ensure its format and expiration are valid. Addresses Type: SOCKET_ADDRESS_LIST* Optional list of addresses of the peers to which the application is trying to connect. If this parameter is used, the helper class will diagnose connectivity to these addresses. appId Type: LPCWSTR Application ID for the calling application.

NdfCreateWinSockIncident The NdfCreateDNSIncident function diagnoses name resolution issues in resolving a specific host name. Syntax

A descriptor identifying a connected socket. Type: SOCKET A descriptor identifying a connected socket. host Type: LPCWSTR A pointer to the local host. port Type: USHORT The port providing Winsock access. appId Type: LPCWSTR Unique identifier associated with the application. userId Type: SID* Unique identifier associated with the user.

NdfCreateIncident Syntax The NdfCreateIncident function is used internally by application developers to test the NDF functionality incorporated into their application. Syntax (helperClassName)Type: LPCWSTR - The name of the helper class to be used in the diagnoses of the incident. (celt)Type: ULONG - A count of elements in the attributes array. (*attributes)Type: HELPER_ATTRIBUTE* - The applicable HELPER_ATTRIBUTE structure.

Running Diagnosis and Repairs There are two ways to launch the diagnosis and repair functionality. Using the Windows User Interface (Recommended) Using a Custom User Interface (Windows 7 and later only)

Using the Windows User Interface When running in the standard Windows user interface, you can simply call the NdfExecuteDiagnosis function. The NDF Wizard will launch and assist the user in identifying (and if possible, and resolving) the problem. The function will return after this process has finished. The user interface is optionally modal to your application. (hwnd) Type: HWND Handle to the window that is intended to display the diagnostic information. If specified, the NDF UI is modal to the window. If NULL, the UI is non-modal.

Using a Custom User Interface (Windows 7 and later only) Different functions are available to use in scenarios where no user interface is being shown, or where the standard Windows experience is not being used (such as Media Center, embedded applications, and the command prompt). This option bypasses the user experience functionality provided in the NDF Wizard, which includes limiting the results to fully-supported root causes, as well as heuristics to present repairs to the user in recommended order. When using these functions, you must provide any such functionality yourself. You must also make sure to free memory used by the diagnosis results.

Closing an Incident When you are finished diagnosing an incident, call NdfCloseIncident to free system resources associated with performing diagnostics on that incident.

Summary Three main stages of performing diagnosis with NDF tool: 1. Creating an incident 2. Running diagnosis and repairs 3. Closing an incident

Thank you for your attention 