1 out of 1 rated this helpful - Rate this topic

IcmpCreateFile function

Applies to: desktop apps only

The IcmpCreateFile function opens a handle on which IPv4 ICMP echo requests can be issued.

Syntax

Copy

HANDLE IcmpCreateFile(void);

Parameters

This function has no parameters.

Return value

The IcmpCreateFile function returns an open handle on success. On failure, the function returns INVALID_HANDLE_VALUE. Call the GetLastError function for extended error information.

Remarks

The IcmpCreateFile function is exported from the Icmp.dll on Windows 2000. The IcmpCreateFile 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 IcmpCreateFile in the Iphlpapi.dll with calls to LoadLibrary and GetProcAddress. Failing that, the application should check for the presence of IcmpCreateFile in the Icmp.dll with calls to LoadLibrary and GetProcAddress.

For IPv6, use the Icmp6CreateFile, Icmp6SendEcho2, and Icmp6ParseReplies functions.

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

Examples

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

C++

Copy


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

// Need to link with Iplhlapi.lib
#pragma comment(lib, "IPHLPAPI.lib")

void main()
{
    HANDLE hIcmpFile;

    hIcmpFile = IcmpCreateFile();
    if (hIcmpFile == INVALID_HANDLE_VALUE) {
      printf("\tUnable to open handle.\n");
      printf("IcmpCreatefile returned error: %ld\n", GetLastError() );
    }
    else {
      printf("\tHandle created.\n");
      // Need to close the handle when done using it
      IcmpCloseHandle(hIcmpFile);
    }  
}

Requirements

Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
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

The Remarks section should, like most other documented functions, have a line indicating what, if anything, should be done with the returned handle. The documentation does not say that you need to call IcmpCloseHandle, so i don't actually know if you can, should, or must, close the handle.

Something like, "When an application is finished using the object handle returned by IcmpCreateFile, use the IcmpCloseHandle function to close the handle." And then a reason why..."Failure to do so will result in a kernel mode exception the next time IcmpCreateHandle is called..." or whatever

"Do not call IcmpCloseHandle with the returned handle. And then a reason why... "The handle is a per-process system allocated resource. Closing the handle will result in WinSock calls no longer being available for the process."

"The application can optionally call IcmpCloseHandle when it is finished with the handle. The returned handle is system resource that is freed when the processes closes. The function IcmpCloseHandle is provided for backwards compatibility only, and can safely be omitted.

History

8/5/2010
Jack Tripper

8/5/2010
Thomas Lee

Closing the handle

need to close the handle using IcmpCloseHandle() in the example