System Diagnostics API Reference

You are here: Windows > API Reference > System > Diagnostics

Overview

This section provides documentation for the Windows API functions related to system diagnostics. These APIs allow developers to monitor system performance, gather diagnostic information, and interact with various system monitoring tools and services.

Key areas covered include:

  • Performance counter access
  • Event logging
  • System information retrieval
  • Debugging APIs
  • Resource monitoring

Core Diagnostic Functions

Performance Counters

The Performance Data Helper (PDH) functions provide a comprehensive way to query and manage performance counters on a Windows system.

PdhOpenQuery

Opens a query for performance data.

DWORD PdhOpenQuery( _In_opt_ LPCWSTR szDataSource, _In_opt_ LPCWSTR szMachineName, _Out_ PPHQUERY phQuery );
Parameters:
  • szDataSource: [in, optional] Path to a performance data log file. If NULL, current system performance data is queried.
  • szMachineName: [in, optional] Name of the computer on which to query performance data. If NULL, the local computer is queried.
  • phQuery: [out] Handle to the performance data query.
Return Value: Returns ERROR_SUCCESS on success, or a Windows error code otherwise.
Note: Use PdhCloseQuery to close the query handle when done.

PdhAddCounter

Adds a performance counter to an existing query.

DWORD PdhAddCounter( _In_ PPHQUERY hQuery, _In_ LPCWSTR szCounterPath, _In_opt_ LPVOID dwData, _Out_ PPHCOUNTER hCounter );
Parameters:
  • hQuery: Handle to the performance data query.
  • szCounterPath: [in] String that specifies the counter path.
  • dwData: [in, optional] Application-defined value to be passed to the counter.
  • hCounter: [out] Handle to the performance counter.
Return Value: Returns ERROR_SUCCESS on success.

PdhCollectQueryData

Collects the latest data for all counters in the specified query.

DWORD PdhCollectQueryData( _In_ PPHQUERY hQuery );
Parameters:
  • hQuery: Handle to the performance data query.
Return Value: Returns ERROR_SUCCESS on success.

PdhGetFormattedCounterValue

Retrieves the formatted value of a performance counter.

DWORD PdhGetFormattedCounterValue( _In_ PPHCOUNTER hCounter, _In_ DWORD dwFormSpec, _Out_opt_ LPDWORD pdwAsAction, _Inout_ PPDH_FMT_COUNTERVALUE pValue );
Parameters:
  • hCounter: Handle to the performance counter.
  • dwFormSpec: A bitmask specifying the desired output format.
  • pdwAsAction: [out, optional] Receives a value indicating the type of calculation performed on the counter value.
  • pValue: [in, out] Pointer to a PDH_FMT_COUNTERVALUE structure that receives the formatted counter value.
Return Value: Returns ERROR_SUCCESS on success.

Event Logging

The Event Logging API allows applications to write event messages to the Windows event log.

RegisterEventSource

Retrieves a handle to the event log for a specified computer and application.

HANDLE RegisterEventSource( _In_opt_ LPCTSTR lpUNCServerName, _In_ LPCTSTR lpSourceName );
Parameters:
  • lpUNCServerName: [in, optional] The UNC path of the server.
  • lpSourceName: [in] The name of the application or driver that is logging the event.
Return Value: A handle to the event log if successful, or NULL otherwise.

ReportEvent

Writes an event log entry to the specified event log.

BOOL ReportEvent( _In_ HANDLE hEventLog, _In_ WORD wType, _In_ WORD wCategory, _In_ DWORD dwEventID, _In_opt_ PSID lpUserSecurityDescriptor, _In_ WORD wNumStrings, _In_ DWORD dwDataSize, _In_reads_(_In_) LPCTSTR *lpStrings, _In_reads_bytes_opt_(_In_) LPVOID lpRawData );
Parameters:
  • hEventLog: Handle to the event log.
  • wType: The type of event.
  • wCategory: The category of the event.
  • dwEventID: The event identifier.
  • lpUserSecurityDescriptor: [in, optional] Security descriptor.
  • wNumStrings: Number of strings in the lpStrings array.
  • dwDataSize: Size of the raw data in bytes.
  • lpStrings: [in] Array of null-terminated strings.
  • lpRawData: [in, optional] Binary data.
Return Value: TRUE if successful, FALSE otherwise.
Important: Ensure the event source is registered in the registry before calling ReportEvent.

System Information

APIs for retrieving general system information.

GetSystemInfo

Fills the specified SYSTEM_INFO structure with information about the current system.

VOID GetSystemInfo( _Out_ LPSYSTEM_INFO lpSystemInfo );
Parameters:
  • lpSystemInfo: [out] Pointer to the SYSTEM_INFO structure that receives information about the current system.

GlobalMemoryStatusEx

Fills the specified MEMORYSTATUSEX structure with information about the current memory utilization.

BOOL GlobalMemoryStatusEx( _Inout_ LPMEMORYSTATUSEX lpBuffer );
Parameters:
  • lpBuffer: [in, out] Pointer to a MEMORYSTATUSEX structure.
Return Value: TRUE if successful, FALSE otherwise.

See Also