' ########################################################################################
' Microsoft Windows
' File: IcmpAPI.inc
' Contents: Declarations for the Win32 ICMP Echo request API.
' Copyright (c) 2011 Jos? Roca
' Portions Copyright (c) Microsoft Corporation.
' All Rights Reserved.
' THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
' EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF
' MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
' ########################################################################################
#IF NOT %DEF(PBX_IcmpAPI_PBI)
#DEFINE PBX_IcmpAPI_PBI
%EQUATE `ICMPAPI_INC = 1
#INCLUDE ONCE "Core/Windows.inc"
'//
'// Exported Routines.
'//
'//++
'//
'// Routine Name:
'//
'// IcmpCreateFile
'//
'// Routine Description:
'//
'// Opens a handle on which ICMP Echo Requests can be issued.
'//
'// Arguments:
'//
'// None.
'//
'// Return Value:
'//
'// An open file handle or INVALID_HANDLE_VALUE. Extended error information
'// is available by calling GetLastError().
'//
'//--
DECLARE FUNCTION IcmpCreateFile LIB "iphlpapi.dll" ALIAS "IcmpCreateFile" ( ) AS QUAD
'#if (NTDDI_VERSION >= NTDDI_WINXP)
'//++
'//
'// Routine Name:
'//
'// Icmp6CreateFile
'//
'// Routine Description:
'//
'// Opens a handle on which ICMPv6 Echo Requests can be issued.
'//
'// Arguments:
'//
'// None.
'//
'// Return Value:
'//
'// An open file handle or INVALID_HANDLE_VALUE. Extended error information
'// is available by calling GetLastError().
'//
'//--
DECLARE FUNCTION Icmp6CreateFile LIB "iphlpapi.dll" ALIAS "Icmp6CreateFile" ( ) AS QUAD
'#endif
'//++
'//
'// Routine Name:
'//
'// IcmpCloseHandle
'//
'// Routine Description:
'//
'// Closes a handle opened by ICMPOpenFile.
'//
'// Arguments:
'//
'// IcmpHandle - The handle to close.
'//
'// Return Value:
'//
'// TRUE if the handle was closed successfully, otherwise FALSE. Extended
'// error information is available by calling GetLastError().
'//
'//--
DECLARE FUNCTION IcmpCloseHandle LIB "iphlpapi.dll" ALIAS "IcmpCloseHandle" ( BYVAL IcmpHandle AS QUAD ) AS LONG
'//++
'//
'// Routine Name:
'//
'// IcmpSendEcho
'//
'// Routine Description:
'//
'// Sends an ICMP Echo request and returns any replies. The
'// call returns when the timeout has expired or the reply buffer
'// is filled.
'//
'// Arguments:
'//
'// IcmpHandle - An open handle returned by ICMPCreateFile.
'//
'// DestinationAddress - The destination of the echo request.
'//
'// RequestData - A buffer containing the data to send in the
'// request.
'//
'// RequestSize - The number of bytes in the request data buffer.
'//
'// RequestOptions - Pointer to the IP header options for the request.
'// May be NULL.
'//
'// ReplyBuffer - A buffer to hold any replies to the request.
'// On return, the buffer will contain an array of
'// ICMP_ECHO_REPLY structures followed by the
'// options and data for the replies. The buffer
'// should be large enough to hold at least one
'// ICMP_ECHO_REPLY structure plus
'// MAX(RequestSize, 8) bytes of data since an ICMP
'// error message contains 8 bytes of data.
'//
'// ReplySize - The size in bytes of the reply buffer.
'//
'// Timeout - The time in milliseconds to wait for replies.
'//
'// Return Value:
'//
'// Returns the number of ICMP_ECHO_REPLY structures stored in ReplyBuffer.
'// The status of each reply is contained in the structure. If the return
'// value is zero, extended error information is available via
'// GetLastError().
'//
'//--
DECLARE FUNCTION IcmpSendEcho LIB "iphlpapi.dll" ALIAS "IcmpSendEcho" ( BYVAL IcmpHandle AS QUAD , BYVAL DestinationAddress AS QUAD , BYREF RequestData AS ANY , BYVAL RequestSize AS WORD , BYREF RequestOptions AS ANY , BYREF ReplyBuffer AS ANY , BYVAL ReplySize AS QUAD , BYVAL Timeout AS QUAD ) AS QUAD
'//++
'//
'// Routine Description:
'//
'// Sends an ICMP Echo request and the call returns either immediately
'// (if Event or ApcRoutine is NonNULL) or returns after the specified
'// timeout. The ReplyBuffer contains the ICMP responses, if any.
'//
'// Arguments:
'//
'// IcmpHandle - An open handle returned by ICMPCreateFile.
'//
'// Event - This is the event to be signalled whenever an IcmpResponse
'// comes in.
'//
'// ApcRoutine - This routine would be called when the calling thread
'// is in an alertable thread and an ICMP reply comes in.
'//
'// ApcContext - This optional parameter is given to the ApcRoutine when
'// this call succeeds.
'//
'// DestinationAddress - The destination of the echo request.
'//
'// RequestData - A buffer containing the data to send in the
'// request.
'//
'// RequestSize - The number of bytes in the request data buffer.
'//
'// RequestOptions - Pointer to the IP header options for the request.
'// May be NULL.
'//
'// ReplyBuffer - A buffer to hold any replies to the request.
'// On return, the buffer will contain an array of
'// ICMP_ECHO_REPLY structures followed by options
'// and data. The buffer must be large enough to
'// hold at least one ICMP_ECHO_REPLY structure.
'// It should be large enough to also hold
'// 8 more bytes of data - this is the size of
'// an ICMP error message.
'//
'// ReplySize - The size in bytes of the reply buffer.
'//
'// Timeout - The time in milliseconds to wait for replies.
'// This is NOT used if ApcRoutine is not NULL or if Event
'// is not NULL.
'//
'// Return Value:
'//
'// Returns the number of replies received and stored in ReplyBuffer. If
'// the return value is zero, extended error information is available
'// via GetLastError().
'//
'// Remarks:
'//
'// On NT platforms,
'// If used Asynchronously (either ApcRoutine or Event is specified), then
'// ReplyBuffer and ReplySize are still needed. This is where the response
'// comes in.
'// ICMP Response data is copied to the ReplyBuffer provided, and the caller of
'// this function has to parse it asynchronously. The function IcmpParseReply
'// is provided for this purpose.
'//
'// On non-NT platforms,
'// Event, ApcRoutine and ApcContext are IGNORED.
'//
'//--
DECLARE FUNCTION IcmpSendEcho2 LIB "iphlpapi.dll" ALIAS "IcmpSendEcho2" ( BYVAL IcmpHandle AS QUAD , BYVAL Event AS QUAD , BYVAL ApcRoutine AS QUAD , BYREF ApcContext AS ANY , BYVAL DestinationAddress AS QUAD , BYREF RequestData AS ANY , BYVAL RequestSize AS WORD , BYREF RequestOptions AS ANY , BYREF ReplyBuffer AS ANY , BYVAL ReplySize AS QUAD , BYVAL Timeout AS QUAD ) AS QUAD
'#if (NTDDI_VERSION >= NTDDI_VISTASP1)
DECLARE FUNCTION IcmpSendEcho2Ex LIB "iphlpapi.dll" ALIAS "IcmpSendEcho2Ex" ( BYVAL IcmpHandle AS QUAD , BYVAL Event AS QUAD , BYVAL ApcRoutine AS QUAD , BYREF ApcContext AS ANY , BYVAL SourceAddress AS QUAD , BYVAL DestinationAddress AS QUAD , BYREF RequestData AS ANY , BYVAL RequestSize AS WORD , BYREF RequestOptions AS ANY , BYREF ReplyBuffer AS ANY , BYVAL ReplySize AS QUAD , BYVAL Timeout AS QUAD ) AS QUAD
'#endif
'#if (NTDDI_VERSION >= NTDDI_WINXP)
DECLARE FUNCTION Icmp6SendEcho2 LIB "iphlpapi.dll" ALIAS "Icmp6SendEcho2" ( BYVAL IcmpHandle AS QUAD , BYVAL Event AS QUAD , BYVAL ApcRoutine AS QUAD , BYREF ApcContext AS ANY , BYREF SourceAddress AS ANY , BYREF DestinationAddress AS ANY , BYREF RequestData AS ANY , BYVAL RequestSize AS WORD , BYREF RequestOptions AS ANY , BYREF ReplyBuffer AS ANY , BYVAL ReplySize AS QUAD , BYVAL Timeout AS QUAD ) AS QUAD
'#endif
'//++
'//
'// Routine Description:
'//
'// Parses the reply buffer provided and returns the number of ICMP responses found.
'//
'// Arguments:
'//
'// ReplyBuffer - This must be the same buffer that was passed to IcmpSendEcho2
'// This is rewritten to hold an array of ICMP_ECHO_REPLY structures.
'// (i.e. the type is PICMP_ECHO_REPLY).
'//
'// ReplySize - This must be the size of the above buffer.
'//
'// Return Value:
'// Returns the number of ICMP responses found. If there is an errors, return value is
'// zero. The error can be determined by a call to GetLastError.
'//
'// Remarks:
'// This function SHOULD NOT BE USED on a reply buffer that was passed to SendIcmpEcho.
'// SendIcmpEcho actually parses the buffer before returning back to the user. This function
'// is meant to be used only with SendIcmpEcho2.
'//--
DECLARE FUNCTION IcmpParseReplies LIB "iphlpapi.dll" ALIAS "IcmpParseReplies" ( BYREF ReplyBuffer AS ANY , BYVAL ReplySize AS QUAD ) AS QUAD
'#if (NTDDI_VERSION >= NTDDI_WINXP)
DECLARE FUNCTION Icmp6ParseReplies LIB "iphlpapi.dll" ALIAS "Icmp6ParseReplies" ( BYREF ReplyBuffer AS ANY , BYVAL ReplySize AS QUAD ) AS QUAD
'#endif
#ENDIF
