IcmpCloseHandle function (icmpapi.h)

Article
02/22/2024

The IcmpCloseHandle function closes a handle opened by a call to the IcmpCreateFile or Icmp6CreateFile functions.

Syntax

IPHLPAPI_DLL_LINKAGE BOOL IcmpCloseHandle(
  [in] HANDLE IcmpHandle
);

Parameters

[in] IcmpHandle

The handle to close. This handle must have been returned by a call to IcmpCreateFile or Icmp6CreateFile.

Return value

If the handle is closed successfully the return value is TRUE, otherwise FALSE. Call the GetLastError function for extended error information.

Remarks

The IcmpCloseHandle function is exported from the Icmp.dll on Windows 2000. The IcmpCloseHandle function is exported from the Iphlpapi.dll on Windows XP and later. Windows version checking is not recommended to use this function. Applications requiring portability with this function across Windows 2000, Windows XP, Windows Server 2003 and later Windows versions should not statically link to either the Icmp.lib or the Iphlpapi.lib file. Instead, the application should check for the presence of IcmpCloseHandle in the Iphlpapi.dll with calls to LoadLibrary and GetProcAddress. Failing that, the application should check for the presence of IcmpCloseHandle in the Icmp.dll with calls to LoadLibrary and GetProcAddress.

Note that the include directive for Iphlpapi.h header file must be placed before the Icmpapi.h header file.

Examples

The following example opens and closes a handle on which ICMP echo requests can be issued.

#include <windows.h>
#include <iphlpapi.h>
#include <icmpapi.h>
#include <stdio.h>

#pragma comment(lib, "iphlpapi.lib")

void main()
{
    HANDLE hIcmpFile;
    BOOL bRetVal; 

    hIcmpFile = IcmpCreateFile();
    if (hIcmpFile == INVALID_HANDLE_VALUE)
      printf("IcmpCreateFile failed with error: %ld\n", GetLastError() );
    else 
    {
      printf("\tHandle created.\n");

      bRetVal = IcmpCloseHandle(hIcmpFile);
      if (bRetVal)
          printf("\tHandle was closed\n");
      else
          printf("IcmpCloseHandle failed with error: %ld\n", GetLastError() );
    }
}

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps \| UWP apps]
Minimum supported server	Windows 2000 Server [desktop apps \| UWP apps]
Target Platform	Windows
Header	icmpapi.h
Library	Iphlpapi.lib
DLL	Iphlpapi.dll on Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP; Icmp.dll on Windows 2000 Server and Windows 2000 Professional

Share via