1 {******************************************************************************}
2 { }
3 { ICMP Echo API interface Unit for Object Pascal }
4 { }
5 { Portions created by Microsoft are Copyright (C) 1995-2001 Microsoft }
6 { Corporation. All Rights Reserved. }
7 { }
8 { The original file is: icmpapi.h, released Feb 2003. The original Pascal }
9 { code is: IcmpApi.pas, released December 2003. The initial developer of the }
10 { Pascal code is Marcel van Brakel (brakelm att chello dott nl). }
11 { }
12 { Portions created by Marcel van Brakel are Copyright (C) 1999-2001 }
13 { Marcel van Brakel. All Rights Reserved. }
14 { }
15 { Obtained through: Joint Endeavour of Delphi Innovators (Project JEDI) }
16 { }
17 { You may retrieve the latest version of this file at the Project JEDI }
18 { APILIB home page, located at http://jedi-apilib.sourceforge.net }
19 { }
20 { The contents of this file are used with permission, subject to the Mozilla }
21 { Public License Version 1.1 (the "License"); you may not use this file except }
22 { in compliance with the License. You may obtain a copy of the License at }
23 { http://www.mozilla.org/MPL/MPL-1.1.html }
24 { }
25 { Software distributed under the License is distributed on an "AS IS" basis, }
26 { WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for }
27 { the specific language governing rights and limitations under the License. }
28 { }
29 { Alternatively, the contents of this file may be used under the terms of the }
30 { GNU Lesser General Public License (the "LGPL License"), in which case the }
31 { provisions of the LGPL License are applicable instead of those above. }
32 { If you wish to allow use of your version of this file only under the terms }
33 { of the LGPL License and not to allow others to use your version of this file }
34 { under the MPL, indicate your decision by deleting the provisions above and }
35 { replace them with the notice and other provisions required by the LGPL }
36 { License. If you do not delete the provisions above, a recipient may use }
37 { your version of this file under either the MPL or the LGPL License. }
38 { }
39 { For more information about the LGPL: http://www.gnu.org/copyleft/lesser.html }
40 { }
41 {******************************************************************************}
42
43 // $Id: JwaIcmpApi.pas,v 1.17 2007/09/14 06:48:45 marquardt Exp $
44 {$IFNDEF JWA_OMIT_SECTIONS}
45 unit JwaIcmpApi;
46
47 {$WEAKPACKAGEUNIT}
48 {$ENDIF JWA_OMIT_SECTIONS}
49
50 {$HPPEMIT ''}
51 {$HPPEMIT '#include "icmpapi.h"'}
52 {$HPPEMIT ''}
53
54 {$IFNDEF JWA_OMIT_SECTIONS}
55 {$I jediapilib.inc}
56
57 interface
58
59 uses
60 JwaWinType, JwaIpExport, JwaNative, JwaWS2tcpip;
61 {$ENDIF JWA_OMIT_SECTIONS}
62
63 {$IFNDEF JWA_IMPLEMENTATIONSECTION}
64
65 // Declarations for the Win32 ICMP Echo request API.
66
67 //
68 // Exported Routines.
69 //
70
71 //++
72 //
73 // Routine Name:
74 //
75 // IcmpCreateFile
76 //
77 // Routine Description:
78 //
79 // Opens a handle on which ICMP Echo Requests can be issued.
80 //
81 // Arguments:
82 //
83 // None.
84 //
85 // Return Value:
86 //
87 // An open file handle or INVALID_HANDLE_VALUE. Extended error information
88 // is available by calling GetLastError().
89 //
90 //--
91
IcmpCreateFilenull92 function IcmpCreateFile: HANDLE; stdcall;
93 {$EXTERNALSYM IcmpCreateFile}
94
95 //++
96 //
97 // Routine Name:
98 //
99 // Icmp6CreateFile
100 //
101 // Routine Description:
102 //
103 // Opens a handle on which ICMPv6 Echo Requests can be issued.
104 //
105 // Arguments:
106 //
107 // None.
108 //
109 // Return Value:
110 //
111 // An open file handle or INVALID_HANDLE_VALUE. Extended error information
112 // is available by calling GetLastError().
113 //
114 //--
115
Icmp6CreateFilenull116 function Icmp6CreateFile: HANDLE; stdcall;
117 {$EXTERNALSYM Icmp6CreateFile}
118
119 //++
120 //
121 // Routine Name:
122 //
123 // IcmpCloseHandle
124 //
125 // Routine Description:
126 //
127 // Closes a handle opened by ICMPOpenFile.
128 //
129 // Arguments:
130 //
131 // IcmpHandle - The handle to close.
132 //
133 // Return Value:
134 //
135 // TRUE if the handle was closed successfully, otherwise FALSE. Extended
136 // error information is available by calling GetLastError().
137 //
138 //--
139
IcmpCloseHandlenull140 function IcmpCloseHandle(IcmpHandle: HANDLE): BOOL; stdcall;
141 {$EXTERNALSYM IcmpCloseHandle}
142
143 //++
144 //
145 // Routine Name:
146 //
147 // IcmpSendEcho
148 //
149 // Routine Description:
150 //
151 // Sends an ICMP Echo request and returns any replies. The
152 // call returns when the timeout has expired or the reply buffer
153 // is filled.
154 //
155 // Arguments:
156 //
157 // IcmpHandle - An open handle returned by ICMPCreateFile.
158 //
159 // DestinationAddress - The destination of the echo request.
160 //
161 // RequestData - A buffer containing the data to send in the
162 // request.
163 //
164 // RequestSize - The number of bytes in the request data buffer.
165 //
166 // RequestOptions - Pointer to the IP header options for the request.
167 // May be NULL.
168 //
169 // ReplyBuffer - A buffer to hold any replies to the request.
170 // On return, the buffer will contain an array of
171 // ICMP_ECHO_REPLY structures followed by the
172 // options and data for the replies. The buffer
173 // should be large enough to hold at least one
174 // ICMP_ECHO_REPLY structure plus
175 // MAX(RequestSize, 8) bytes of data since an ICMP
176 // error message contains 8 bytes of data.
177 //
178 // ReplySize - The size in bytes of the reply buffer.
179 //
180 // Timeout - The time in milliseconds to wait for replies.
181 //
182 // Return Value:
183 //
184 // Returns the number of ICMP_ECHO_REPLY structures stored in ReplyBuffer.
185 // The status of each reply is contained in the structure. If the return
186 // value is zero, extended error information is available via
187 // GetLastError().
188 //
189 //--
190
IcmpSendEchonull191 function IcmpSendEcho(
192 IcmpHandle: HANDLE;
193 DestinationAddress: IpAddr;
194 RequestData: LPVOID;
195 RequestSize: WORD;
196 RequestOptions: PIP_OPTION_INFORMATION;
197 ReplyBuffer: LPVOID;
198 ReplySize: DWORD;
199 Timeout: DWORD): DWORD; stdcall;
200 {$EXTERNALSYM IcmpSendEcho}
201
202 //++
203 //
204 // Routine Description:
205 //
206 // Sends an ICMP Echo request and the call returns either immediately
207 // (if Event or ApcRoutine is NonNULL) or returns after the specified
208 // timeout. The ReplyBuffer contains the ICMP responses, if any.
209 //
210 // Arguments:
211 //
212 // IcmpHandle - An open handle returned by ICMPCreateFile.
213 //
214 // Event - This is the event to be signalled whenever an IcmpResponse
215 // comes in.
216 //
217 // ApcRoutine - This routine would be called when the calling thread
218 // is in an alertable thread and an ICMP reply comes in.
219 //
220 // ApcContext - This optional parameter is given to the ApcRoutine when
221 // this call succeeds.
222 //
223 // DestinationAddress - The destination of the echo request.
224 //
225 // RequestData - A buffer containing the data to send in the
226 // request.
227 //
228 // RequestSize - The number of bytes in the request data buffer.
229 //
230 // RequestOptions - Pointer to the IP header options for the request.
231 // May be NULL.
232 //
233 // ReplyBuffer - A buffer to hold any replies to the request.
234 // On return, the buffer will contain an array of
235 // ICMP_ECHO_REPLY structures followed by options
236 // and data. The buffer must be large enough to
237 // hold at least one ICMP_ECHO_REPLY structure.
238 // It should be large enough to also hold
239 // 8 more bytes of data - this is the size of
240 // an ICMP error message.
241 //
242 // ReplySize - The size in bytes of the reply buffer.
243 //
244 // Timeout - The time in milliseconds to wait for replies.
245 // This is NOT used if ApcRoutine is not NULL or if Event
246 // is not NULL.
247 //
248 // Return Value:
249 //
250 // Returns the number of replies received and stored in ReplyBuffer. If
251 // the return value is zero, extended error information is available
252 // via GetLastError().
253 //
254 // Remarks:
255 //
256 // On NT platforms,
257 // If used Asynchronously (either ApcRoutine or Event is specified), then
258 // ReplyBuffer and ReplySize are still needed. This is where the response
259 // comes in.
260 // ICMP Response data is copied to the ReplyBuffer provided, and the caller of
hasnull261 // this function has to parse it asynchronously. The function IcmpParseReply
262 // is provided for this purpose.
263 //
264 // On non-NT platforms,
265 // Event, ApcRoutine and ApcContext are IGNORED.
266 //
267 //--
268
269 function IcmpSendEcho2(
270 IcmpHandle: HANDLE;
271 Event: HANDLE;
272 ApcRoutine: PIO_APC_ROUTINE;
273 ApcContext: PVOID;
274 DestinationAddress: IpAddr;
275 RequestData: LPVOID;
276 RequestSize: WORD;
277 RequestOptions: PIP_OPTION_INFORMATION;
278 ReplyBuffer: LPVOID;
279 ReplySize: DWORD;
280 Timeout: DWORD): DWORD; stdcall;
281 {$EXTERNALSYM IcmpSendEcho2}
282
Icmp6SendEcho2null283 function Icmp6SendEcho2(
284 IcmpHandle: HANDLE;
285 Event: HANDLE;
286 ApcRoutine: PIO_APC_ROUTINE;
287 ApcContext: PVOID;
288 SourceAddress: Psockaddr_in6;
289 DestinationAddress: Psockaddr_in6;
290 RequestData,
291 RequestSize: WORD;
292 RequestOptions: PIP_OPTION_INFORMATION;
293 ReplyBuffer: LPVOID;
294 ReplySize: DWORD;
295 Timeout: DWORD): DWORD; stdcall;
296 {$EXTERNALSYM Icmp6SendEcho2}
297
298 //++
299 //
300 // Routine Description:
301 //
302 // Parses the reply buffer provided and returns the number of ICMP responses found.
303 //
304 // Arguments:
305 //
306 // ReplyBuffer - This must be the same buffer that was passed to IcmpSendEcho2
307 // This is rewritten to hold an array of ICMP_ECHO_REPLY structures.
308 // (i.e. the type is PICMP_ECHO_REPLY).
309 //
310 // ReplySize - This must be the size of the above buffer.
311 //
312 // Return Value:
313 // Returns the number of ICMP responses found. If there is an errors, return value is
314 // zero. The error can be determined by a call to GetLastError.
315 //
316 // Remarks:
SHOULDnull317 // This function SHOULD NOT BE USED on a reply buffer that was passed to SendIcmpEcho.
318 // SendIcmpEcho actually parses the buffer before returning back to the user. This function
319 // is meant to be used only with SendIcmpEcho2.
320 //--
321
322 function IcmpParseReplies(ReplyBuffer: LPVOID; ReplySize: DWORD): DWORD; stdcall;
323 {$EXTERNALSYM IcmpParseReplies}
324
Icmp6ParseRepliesnull325 function Icmp6ParseReplies(ReplyBuffer: LPVOID; ReplySize: DWORD): DWORD; stdcall;
326 {$EXTERNALSYM Icmp6ParseReplies}
327
328 {$ENDIF JWA_IMPLEMENTATIONSECTION}
329
330 {$IFNDEF JWA_OMIT_SECTIONS}
331 implementation
332 //uses ...
333 {$ENDIF JWA_OMIT_SECTIONS}
334
335 {$IFNDEF JWA_INTERFACESECTION}
336
337 {$IFNDEF JWA_INCLUDEMODE}
338 const
339 icmplib = 'iphlpapi.dll';
340 {$ENDIF JWA_INCLUDEMODE}
341
342 {$IFDEF DYNAMIC_LINK}
343
344 var
345 _IcmpCreateFile: Pointer;
346
IcmpCreateFilenull347 function IcmpCreateFile;
348 begin
349 GetProcedureAddress(_IcmpCreateFile, icmplib, 'IcmpCreateFile');
350 asm
351 MOV ESP, EBP
352 POP EBP
353 JMP [_IcmpCreateFile]
354 end;
355 end;
356
357 var
358 _Icmp6CreateFile: Pointer;
359
Icmp6CreateFilenull360 function Icmp6CreateFile;
361 begin
362 GetProcedureAddress(_Icmp6CreateFile, icmplib, 'Icmp6CreateFile');
363 asm
364 MOV ESP, EBP
365 POP EBP
366 JMP [_Icmp6CreateFile]
367 end;
368 end;
369
370 var
371 _IcmpCloseHandle: Pointer;
372
IcmpCloseHandlenull373 function IcmpCloseHandle;
374 begin
375 GetProcedureAddress(_IcmpCloseHandle, icmplib, 'IcmpCloseHandle');
376 asm
377 MOV ESP, EBP
378 POP EBP
379 JMP [_IcmpCloseHandle]
380 end;
381 end;
382
383 var
384 _IcmpSendEcho: Pointer;
385
IcmpSendEchonull386 function IcmpSendEcho;
387 begin
388 GetProcedureAddress(_IcmpSendEcho, icmplib, 'IcmpSendEcho');
389 asm
390 MOV ESP, EBP
391 POP EBP
392 JMP [_IcmpSendEcho]
393 end;
394 end;
395
396 var
397 _IcmpSendEcho2: Pointer;
398
IcmpSendEcho2null399 function IcmpSendEcho2;
400 begin
401 GetProcedureAddress(_IcmpSendEcho2, icmplib, 'IcmpSendEcho2');
402 asm
403 MOV ESP, EBP
404 POP EBP
405 JMP [_IcmpSendEcho2]
406 end;
407 end;
408
409 var
410 _Icmp6SendEcho2: Pointer;
411
Icmp6SendEcho2null412 function Icmp6SendEcho2;
413 begin
414 GetProcedureAddress(_Icmp6SendEcho2, icmplib, 'Icmp6SendEcho2');
415 asm
416 MOV ESP, EBP
417 POP EBP
418 JMP [_Icmp6SendEcho2]
419 end;
420 end;
421
422 var
423 _IcmpParseReplies: Pointer;
424
IcmpParseRepliesnull425 function IcmpParseReplies;
426 begin
427 GetProcedureAddress(_IcmpParseReplies, icmplib, 'IcmpParseReplies');
428 asm
429 MOV ESP, EBP
430 POP EBP
431 JMP [_IcmpParseReplies]
432 end;
433 end;
434
435 var
436 _Icmp6ParseReplies: Pointer;
437
Icmp6ParseRepliesnull438 function Icmp6ParseReplies;
439 begin
440 GetProcedureAddress(_Icmp6ParseReplies, icmplib, 'Icmp6ParseReplies');
441 asm
442 MOV ESP, EBP
443 POP EBP
444 JMP [_Icmp6ParseReplies]
445 end;
446 end;
447
448 {$ELSE}
449
IcmpCreateFilenull450 function IcmpCreateFile; external icmplib name 'IcmpCreateFile';
Icmp6CreateFilenull451 function Icmp6CreateFile; external icmplib name 'Icmp6CreateFile';
IcmpCloseHandlenull452 function IcmpCloseHandle; external icmplib name 'IcmpCloseHandle';
IcmpSendEchonull453 function IcmpSendEcho; external icmplib name 'IcmpSendEcho';
IcmpSendEcho2null454 function IcmpSendEcho2; external icmplib name 'IcmpSendEcho2';
Icmp6SendEcho2null455 function Icmp6SendEcho2; external icmplib name 'Icmp6SendEcho2';
IcmpParseRepliesnull456 function IcmpParseReplies; external icmplib name 'IcmpParseReplies';
Icmp6ParseRepliesnull457 function Icmp6ParseReplies; external icmplib name 'Icmp6ParseReplies';
458
459 {$ENDIF DYNAMIC_LINK}
460
461 {$ENDIF JWA_INTERFACESECTION}
462
463 {$IFNDEF JWA_OMIT_SECTIONS}
464 end.
465 {$ENDIF JWA_OMIT_SECTIONS}
466