Windows Ping Class

7/27/2019 Windows Ping Class

1/12

Inheritance Hierarchy

Syntax

Constructors

Properties

Methods

Ping Class.NET Framework 4

Allows an application to determine whether a remote computer is accessible over the network.

System.Object1

System.MarshalByRefObject2

System.ComponentModel.Component3

System.Net.NetworkInformation.Ping

Namespace: System.Net.NetworkInformation4

Assembly: System (in System.dll)

The Ping type exposes the following members.

Name Description

Ping5 Initializes a new instance of the Ping class.

Top

Name Description

CanRaiseEvents6 Gets a value indicating whether the component can raise an event.

(Inherited from Component3.)

Container7 Gets the IContainer

8that contains the Component

3. (Inherited from

Component3.)

DesignMode9 Gets a value that indicates whether the Component

3is currently in design

mode. (Inherited from Component

3

.)

Events10 Gets the list of event handlers that are attached to this Component

3.


Site11

Gets or sets the ISite12

of the Component3. (Inherited from Component

3.)

Top

Name Description

publicclass Ping : Component

C# C++ F# VB

Page 1 of 12Ping Class (System.Net.NetworkInformation)

10/20/2011http://msdn.microsoft.com/en-us/library/system.net.networkinformation.ping(d=printer).a...


2/12

CreateObjRef13

Creates an object that contains all the relevant informationrequired to generate a proxy used to communicate with a

remote object. (Inherited from MarshalByRefObject2.)

Dispose14 Releases all resources used by the Component

3. (Inherited from

Component3.)

Dispose(Boolean)15

Releases the unmanaged resources used by the Ping object, and

optionally disposes of the managed resources. (Overrides

Component.Dispose(Boolean)16.)

Equals(Object)17 Determines whether the specified Object

1is equal to the current

Object1. (Inherited from Object

1.)

Finalize18

Releases unmanaged resources and performs other cleanup

operations before the Component3

is reclaimed by garbage

collection. (Inherited from Component3.)

GetHashCode19 Serves as a hash function for a particular type. (Inherited from

Object1.)

GetLifetimeService20

Retrieves the current lifetime service object that controls thelifetime policy for this instance. (Inherited from

MarshalByRefObject2.)

GetService21 Returns an object that represents a service provided by the

Component3

or by its Container22

. (Inherited from Component3.)

GetType23 Gets the Type

24of the current instance. (Inherited from

Object1.)

InitializeLifetimeService25 Obtains a lifetime service object to control the lifetime policy for

this instance. (Inherited from MarshalByRefObject2.)

MemberwiseClone26 Creates a shallow copy of the current Object

1. (Inherited from

Object1.)

MemberwiseClone(Boolean)27

Creates a shallow copy of the current MarshalByRefObject2

object. (Inherited from MarshalByRefObject2.)

OnPingCompleted28 Raises the PingCompleted29 event.

Send(IPAddress)30

Attempts to send an Internet Control Message Protocol (ICMP)echo message to the computer that has the specified

IPAddress31

, and receive a corresponding ICMP echo replymessage from that computer.

Send(String)32

Attempts to send an Internet Control Message Protocol (ICMP)

echo message to the specified computer, and receive acorresponding ICMP echo reply message from that computer.

Send(IPAddress, Int32)33

Attempts to send an Internet Control Message Protocol (ICMP)

echo message with the specified data buffer to the computer

that has the specified IPAddress31

, and receive a corresponding

ICMP echo reply message from that computer. This methodallows you to specify a time-out value for the operation.

Send(String, Int32)34

Attempts to send an Internet Control Message Protocol (ICMP)echo message to the specified computer, and receive a

corresponding ICMP echo reply message from that computer.This method allows you to specify a time-out value for theoperation.

Send(IPAddress, Int32, Byte

())35

Attempts to send an Internet Control Message Protocol (ICMP)echo message with the specified data buffer to the computer


, and receive a corresponding




3/12

ICMP echo reply message from that computer. This overloadallows you to specify a time-out value for the operation.

Send(String, Int32, Byte())36

Attempts to send an Internet Control Message Protocol (ICMP)echo message with the specified data buffer to the specifiedcomputer, and receive a corresponding ICMP echo replymessage from that computer. This overload allows you tospecify a time-out value for the operation.

Send(IPAddress, Int32, Byte

(), PingOptions)37

Attempts to send an Internet Control Message Protocol (ICMP)echo message with the specified data buffer to the computer


and receive a correspondingICMP echo reply message from that computer. This overloadallows you to specify a time-out value for the operation and

control fragmentation and Time-to-Live values for the ICMPecho message packet.

Send(String, Int32, Byte(),

PingOptions)38

Attempts to send an Internet Control Message Protocol (ICMP)echo message with the specified data buffer to the specifiedcomputer, and receive a corresponding ICMP echo replymessage from that computer. This overload allows you to

specify a time-out value for the operation and controlfragmentation and Time-to-Live values for the ICMP packet.

SendAsync(IPAddress,

Object)39

Asynchronously attempts to send an Internet Control MessageProtocol (ICMP) echo message to the computer that has the

specified IPAddress31

, and receive a corresponding ICMP echoreply message from that computer.

SendAsync(String, Object)40

Asynchronously attempts to send an Internet Control Message

Protocol (ICMP) echo message to the specified computer, andreceive a corresponding ICMP echo reply message from thatcomputer.

SendAsync(IPAddress, Int32,

Object)41

Asynchronously attempts to send an Internet Control MessageProtocol (ICMP) echo message to the computer that has the

specified IPAddress31

, and receive a corresponding ICMP echo

reply message from that computer. This overload allows you tospecify a time-out value for the operation.

SendAsync(String, Int32,

Object)42

Asynchronously attempts to send an Internet Control Message

Protocol (ICMP) echo message to the specified computer, andreceive a corresponding ICMP echo reply message from thatcomputer. This overload allows you to specify a time-out value

for the operation.


Byte(), Object)43

Asynchronously attempts to send an Internet Control MessageProtocol (ICMP) echo message with the specified data buffer to

the computer that has the specified IPAddress31

, and receive acorresponding ICMP echo reply message from that computer.This overload allows you to specify a time-out value for the

operation.

SendAsync(String, Int32,

Byte(), Object)44


the specified computer, and receive a corresponding ICMP echoreply message from that computer. This overload allows you tospecify a time-out value for the operation.


Byte(), PingOptions, Object)45


the computer that has the specified IPAddress31

, and receive acorresponding ICMP echo reply message from that computer.




4/12

Events

Remarks

This overload allows you to specify a time-out value for theoperation and control fragmentation and Time-to-Live values forthe ICMP echo message packet.

SendAsync(String, Int32,Byte(), PingOptions, Object)46

Asynchronously attempts to send an Internet Control MessageProtocol (ICMP) echo message with the specified data buffer tothe specified computer, and receive a corresponding ICMP echoreply message from that computer. This overload allows you to

specify a time-out value for the operation and controlfragmentation and Time-to-Live values for the ICMP packet.

SendAsyncCancel47

Cancels all pending asynchronous requests to send an InternetControl Message Protocol (ICMP) echo message and receives acorresponding ICMP echo reply message.

ToString48

Returns a String49

containing the name of the Component3, if

any. This method should not be overridden. (Inherited from

Component3.)

Top

Name Description

Disposed50 Occurs when the component is disposed by a call to the Dispose

51method.


PingCompleted29

Occurs when an asynchronous operation to send an Internet Control MessageProtocol (ICMP) echo message and receive the corresponding ICMP echo reply

message completes or is canceled.

Top

Applications use the Ping class to detect whether a remote computer is reachable.

Network topology can determine whether Ping can successfully contact a remote host. Thepresence and configuration of proxies, network address translation (NAT) equipment, or firewalls

can prevent Ping from succeeding. A successful Ping indicates only that the remote host can bereached on the network; the presence of higher level services (such as a Web server) on theremote host is not guaranteed.

This class provides functionality similar to the Ping.exe command line tool. The Send52

and

SendAsync53

methods send an Internet Control Message Protocol (ICMP) echo request messageto a remote computer and waits for an ICMP echo reply message from that computer. For a

detailed description of ICMP messages, see RFC 792, available at http://www.ietf.org54

.

The following types are used with the Ping class and are described in detail below.

Type name Description

IPStatus55 Defines status codes that describe the outcome of an ICMP echo

request message.




5/12

PingOptions56

Allows you to configure or retrieve the settings that control how

many times the request packet can be forwarded (Ttl57

), and

whether it can be fragmented (DontFragment58

).

PingReply59 Contains the results of an ICMP echo request.

PingException60 Thrown if an unrecoverable error occurs.

PingCompletedEventArgs61 Contains the data associated with PingCompleted

29events, which

are raised when a SendAsync53

call completes or is canceled.

PingCompletedEventHandler62 The delegate that provides the callback method invoked when a

SendAsync53

call completes or is canceled.

The Send52 and SendAsync53 methods return the reply in a PingReply59 object. ThePingReply.Status

63property returns an IPStatus

55value to indicate the outcome of the request.

When sending the request, you must specify the remote computer. You can do this by providing a

host name string, an IP address in string format, or an IPAddress31

object.

You can also specify any of the following types of information:

Data to accompany the request. Specifying bufferallows you to learn the amount of time

required for a packet of a particular size to travel to and from the remote host and the

maximum transmission unit of the network path. (See the Send52

or SendAsync53

overloadsthat take a bufferparameter.)

Whether the ICMP Echo packet can be fragmented in transit. (See the DontFragment58

property and the Send52

or SendAsync53

overloads that take an options parameter.)

How many times routing nodes, such as routers or gateways, can forward the packet

before it either reaches the destination computer or is discarded. (See Ttl57

and the Send52

or SendAsync53

overloads that take an options parameter.)

The time limit within which the reply must be received. (See the Send52

or SendAsync53

overloads that take a timeoutparameter.

The Ping class offers both synchronous and asynchronous methods for sending the request. If

your application should block while waiting for a reply, use the Send52

methods; these methods

are synchronous. If your application should not block, use the asynchronous SendAsync53methods. A call to SendAsync

53executes in its own thread that is automatically allocated from

the thread pool. When the asynchronous operation completes, it raises the PingCompleted29

event. Applications use a PingCompletedEventHandler62

delegate to specify the method that is

called for PingCompleted29

events. You must add a PingCompletedEventHandler62

delegate to the

event before calling SendAsync53

. The delegate's method receives a PingCompletedEventArgs61

object that contains a PingReply59

object that describes the result of the SendAsync53

call.




6/12

Examples

You cannot use the same instance of the Ping class to generate multiple simultaneous ICMP Echo

requests. Calling Send52

while a SendAsync53

call is in progress or calling SendAsync53

multiple

times before all previous calls have completed causes an InvalidOperationException64

.

The following code example demonstrates using the Ping class synchronously.

The following code example demonstrates using the Ping class asynchronously.

using System;using System.Net;using System.Net.NetworkInformation;

using System.Text;

namespace Examples.System.Net.NetworkInformation.PingTest{

publicclass PingExample{

// args[0] can be an IPaddress or host name.publicstaticvoid Main (string[

] args){

Ping pingSender = new Ping ();PingOptions options = new PingOptions ();

// Use the default Ttl value which is 128,// but change the fragmentation behavior.

options.DontFragment = true;

// Create a buffer of 32 bytes of data to be transmitted.string data ="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";

byte[] buffer = Encoding.ASCII.GetBytes (data);int timeout = 120;

PingReply reply = pingSender.Send (args[0], timeout, buffer, options);if (reply.Status == IPStatus.Success){

Console.WriteLine ("Address: {0}", reply.Address.ToString ());Console.WriteLine ("RoundTrip time: {0}", reply.RoundtripTime);

Console.WriteLine ("Time to live: {0}", reply.Options.Ttl);Console.WriteLine ("Don't fragment: {0}", reply.Options.DontFragme

nt);Console.WriteLine ("Buffer size: {0}", reply.Buffer.Length);

}}

}}

using System;using System.Text;

C# C++ VB

C# C++ VB




7/12

using System.Net;using System.Net.NetworkInformation;using System.ComponentModel;using System.Threading;

namespace Examples.System.Net.NetworkInformation.PingTest{

publicclass PingExample

{publicstaticvoid Main (string[] args){

if (args.Length == 0)

thrownew ArgumentException ("Ping needs a host or IP Address.");

string who = args[0];AutoResetEvent waiter = new AutoResetEvent (false);

Ping pingSender = new Ping ();

// When the PingCompleted event is raised,// the PingCompletedCallbackmethod is called.

pingSender.PingCompleted += new PingCompletedEventHandler (PingCompletedCallback);

// Create a buffer of 32 bytes of data to be transmitted.string data ="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";

byte[] buffer = Encoding.ASCII.GetBytes (data);

// Wait 12 seconds for a reply.int timeout = 12000;

// Set options for transmission:// The data can go through 64 gatewaysor routers// before it is destroyed, and the data packet// cannot be fragmented.

PingOptions options = new PingOptions (64, true);

Console.WriteLine ("Time to live: {0}", options.Ttl);Console.WriteLine ("Don't fragment: {0}", options.DontFragment);

// Send the ping asynchronously.// Use the waiter as the user token.//When the callback completes, it can wake up this thread.

pingSender.SendAsync(who, timeout, buffer, options, waiter);

// Prevent this example application from ending.// A real applicationshould do something useful// when possible.

waiter.WaitOne ();Console.WriteLine ("Ping example completed.");

}

privatestaticvoid PingCompletedCallback (object sender, PingCompletedEventArgs e)

{// If the operation was canceled, display a message to the user.if (e.

Cancelled){

Console.WriteLine ("Ping canceled.");

// Let the main thread resume. // UserToken is the AutoResetEventobject that the main thread // is waiting for.

((AutoResetEvent)e.UserState).Set ();




8/12

Version Information

Platforms

.NET Framework

Supported in: 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, WindowsServer 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with

SP1 or later), Windows Server 2003 SP2

// If an error occurred, display the exception to the user.if (e.Error!= null)

{Console.WriteLine ("Ping failed:");Console.WriteLine (e.Error.ToString ());

// Let the main thread resume.((AutoResetEvent)e.UserState).Set();

}

PingReply reply = e.Reply;

DisplayReply (reply);

// Let the main thread resume.((AutoResetEvent)e.UserState).Set();

}

publicstaticvoid DisplayReply (PingReply reply)

{ if (reply == null)return;

Console.WriteLine ("ping status: {0}", reply.Status);if (reply.Status == IPStatus.Success){

Console.WriteLine ("Address: {0}", reply.Address.ToString ());Console.WriteLine ("RoundTrip time: {0}", reply.RoundtripTime);Console.WriteLine ("Time to live: {0}", reply.Options.Ttl);Console.WriteLine ("Don't fragment: {0}", reply.Options.DontFragme

nt);Console.WriteLine ("Buffer size: {0}", reply.Buffer.Length);

}}

}}




9/12

Thread Safety

See Also

The .NET Framework does not support all versions of every platform. For a list of the supported

versions, see .NET Framework System Requirements65

.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instancemembers are not guaranteed to be thread safe.

Reference

System.Net.NetworkInformation Namespace4

Other Resources

How to: Ping a Host66

Network Programming67

Network Programming Samples68

NetworkInformation

69

Ping Client Technology Sample70

Links Table

1http://msdn.microsoft.com/en-us/library/system.object.aspx

2http://msdn.microsoft.com/en-us/library/system.marshalbyrefobject.aspx

3http://msdn.microsoft.com/en-us/library/system.componentmodel.component.aspx

4http://msdn.microsoft.com/en-us/library/system.net.networkinformation.aspx

5

http://msdn.microsoft.com/en-us/library/system.net.networkinformation.ping.ping.aspx6http://msdn.microsoft.com/en-us/library/system.componentmodel.component.canraiseevents.aspx

7http://msdn.microsoft.com/en-us/library/system.componentmodel.component.container.aspx

8http://msdn.microsoft.com/en-us/library/system.componentmodel.icontainer.aspx

9http://msdn.microsoft.com/en-us/library/system.componentmodel.component.designmode.aspx

10http://msdn.microsoft.com/en-us/library/system.componentmodel.component.events.aspx

11

http://msdn.microsoft.com/en-us/library/system.componentmodel.component.site.aspx12http://msdn.microsoft.com/en-us/library/system.componentmodel.isite.aspx

13http://msdn.microsoft.com/en-us/library/system.marshalbyrefobject.createobjref.aspx

14http://msdn.microsoft.com/en-us/library/3cc9y48w.aspx

15http://msdn.microsoft.com/en-us/library/dd992773.aspx

16http://msdn.microsoft.com/en-us/library/d9yzd5cx.aspx




10/12

17http://msdn.microsoft.com/en-us/library/bsc2ak47.aspx

18http://msdn.microsoft.com/en-us/library/az5741fh.aspx

19http://msdn.microsoft.com/en-us/library/system.object.gethashcode.aspx

20http://msdn.microsoft.com/en-us/library/system.marshalbyrefobject.getlifetimeservice.aspx

21

http://msdn.microsoft.com/en-us/library/system.componentmodel.component.getservice.aspx22http://msdn.microsoft.com/en-us/library/system.componentmodel.container.aspx

23http://msdn.microsoft.com/en-us/library/system.object.gettype.aspx

24http://msdn.microsoft.com/en-us/library/system.type.aspx

25http://msdn.microsoft.com/en-

us/library/system.marshalbyrefobject.initializelifetimeservice.aspx

26http://msdn.microsoft.com/en-us/library/system.object.memberwiseclone.aspx

27http://msdn.microsoft.com/en-us/library/ms131262.aspx

28http://msdn.microsoft.com/en-us/library/system.net.networkinformation.ping.onpingcompleted.aspx


us/library/system.net.networkinformation.ping.pingcompleted.aspx

30http://msdn.microsoft.com/en-us/library/hb7xxkfx.aspx

31http://msdn.microsoft.com/en-us/library/system.net.ipaddress.aspx

32http://msdn.microsoft.com/en-us/library/7hzczzed.aspx

33http://msdn.microsoft.com/en-us/library/yf697k33.aspx

34http://msdn.microsoft.com/en-us/library/dcc2xffs.aspx





39http://msdn.microsoft.com/en-us/library/0e6kc029.aspx

40http://msdn.microsoft.com/en-us/library/xya3e0zf.aspx


42http://msdn.microsoft.com/en-us/library/zxz6dah9.aspx








11/12


us/library/system.net.networkinformation.ping.sendasynccancel.aspx

48http://msdn.microsoft.com/en-us/library/z819d1t5.aspx

49http://msdn.microsoft.com/en-us/library/system.string.aspx

50http://msdn.microsoft.com/en-us/library/system.componentmodel.component.disposed.aspx

51http://msdn.microsoft.com/en-us/library/system.componentmodel.component.dispose.aspx

52http://msdn.microsoft.com/en-us/library/system.net.networkinformation.ping.send.aspx

53http://msdn.microsoft.com/en-us/library/system.net.networkinformation.ping.sendasync.aspx

54http://www.ietf.org/

55http://msdn.microsoft.com/en-us/library/system.net.networkinformation.ipstatus.aspx

56http://msdn.microsoft.com/en-us/library/system.net.networkinformation.pingoptions.aspx

57http://msdn.microsoft.com/en-us/library/system.net.networkinformation.pingoptions.ttl.aspx

58http://msdn.microsoft.com/en-us/library/system.net.networkinformation.pingoptions.dontfragment.aspx

59http://msdn.microsoft.com/en-us/library/system.net.networkinformation.pingreply.aspx

60http://msdn.microsoft.com/en-us/library/system.net.networkinformation.pingexception.aspx


us/library/system.net.networkinformation.pingcompletedeventargs.aspx


us/library/system.net.networkinformation.pingcompletedeventhandler.aspx

63

http://msdn.microsoft.com/en-us/library/system.net.networkinformation.pingreply.status.aspx64http://msdn.microsoft.com/en-us/library/system.invalidoperationexception.aspx

65http://msdn.microsoft.com/en-us/library/8z6watww.aspx


67http://msdn.microsoft.com/en-us/library/4as0wz7t.aspx

68http://msdn.microsoft.com/en-us/library/ee890485.aspx


70

http://go.microsoft.com/fwlink/?LinkID=179565

Community Content

Missing using System.Threading; in the c# example.

The Async C# example is missing the using System.Threading; to allow AutoResetEvent to

function correctly.



Documents

Windows Ping Class