Ping.SendAsync Method (IPAddress, Int32, Byte[], PingOptions, Object)

Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the computer that has the specified IPAddress, and receive a corresponding ICMP echo reply message from that computer. This overload allows you to specify a time-out value for the operation and control fragmentation and Time-to-Live values for the ICMP echo message packet.

Namespace:  System.Net.NetworkInformation
Assembly:  System (in System.dll)

[HostProtectionAttribute(SecurityAction.LinkDemand, ExternalThreading = true)]
public void SendAsync(
	IPAddress address,
	int timeout,
	byte[] buffer,
	PingOptions options,
	Object userToken
)

Parameters

address
Type: System.Net.IPAddress

An IPAddress that identifies the computer that is the destination for the ICMP echo message.

timeout
Type: System.Int32

An Int32 value that specifies the maximum number of milliseconds (after sending the echo message) to wait for the ICMP echo reply message.

buffer
Type: System.Byte[]

A Byte array that contains data to be sent with the ICMP echo message and returned in the ICMP echo reply message. The array cannot contain more than 65,500 bytes.

options
Type: System.Net.NetworkInformation.PingOptions

A PingOptions object used to control fragmentation and Time-to-Live values for the ICMP echo message packet.

userToken
Type: System.Object

An object that is passed to the method invoked when the asynchronous operation completes.

ExceptionCondition
ArgumentNullException

address is null.

-or-

buffer is null.

ArgumentOutOfRangeException

timeout is less than zero.

InvalidOperationException

A call to SendAsync is in progress.

NotSupportedException

address is an IPv6 address and the local computer is running an operating system earlier than Windows 2000.

PingException

An exception was thrown while sending or receiving the ICMP messages. See the inner exception for the exact exception that was thrown.

SocketException

address is not a valid IP address.

ObjectDisposedException

This object has been disposed.

ArgumentException

The size of buffer exceeds 65500 bytes.

The SendAsync method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the SendAsync method when your application must not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the PingCompleted event. Applications use a PingCompletedEventHandler delegate to specify the method that is called when SendAsync raises the event. You must add a PingCompletedEventHandler delegate to the event before calling SendAsync. The delegate's method receives a PingCompletedEventArgs object that contains a PingReply object that describes the result of the SendAsync call. The PingCompletedEventArgs object inherits the UserState property. This property contains the userToken object passed into the SendAsync call.

If your application blocks while waiting for a reply, use the Send methods; these methods are synchronous.

If the ICMP echo reply message is not received within the time specified by the timeout parameter, the ICMP echo fails, and the Status property is set to TimedOut.

NoteNote

When specifying very small numbers for timeout, the Ping reply can be received even if timeout milliseconds have elapsed.

If the DontFragment property is true and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the Status is set to PacketTooBig.

Use the Ttl property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the Status is set to TtlExpired.

NoteNote

The HostProtectionAttribute attribute applied to this type or member has the following Resources property value: ExternalThreading. The HostProtectionAttribute does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the HostProtectionAttribute class or SQL Server Programming and Host Protection Attributes.

The following code example demonstrates how to call this method. For an implementation of the callback method, see the SendAsync method overload example section.

The following code example requires the following namespaces:

using System;
using System.Net;
using System.Net.NetworkInformation;
using System.Text;
using System.Threading;

The following code example sends an ICMP echo message asynchronously.

        public static void AsyncComplexLocalPing ()
        {
            // Get an object that will block the main thread.
            AutoResetEvent waiter = new AutoResetEvent (false);

            // Ping's the local machine.
            Ping pingSender = new Ping ();

            // When the PingCompleted event is raised, 
            // the PingCompletedCallback method is called.
            pingSender.PingCompleted += new PingCompletedEventHandler (PingCompletedCallback);

            IPAddress address = IPAddress.Loopback;

            // Create a buffer of 32 bytes of data to be transmitted. 
            string data = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
            byte[] buffer = Encoding.ASCII.GetBytes (data);

            // Wait 10 seconds for a reply. 
            int timeout = 10000;

            // Set options for transmission: 
            // The data can go through 64 gateways or routers 
            // before it is destroyed, and the data packet 
            // cannot be fragmented.
            PingOptions options = new PingOptions (64, true);

            // Send the ping asynchronously. 
            // Use the waiter as the user token. 
            // When the callback completes, it can wake up this thread.
            pingSender.SendAsync (address, timeout, buffer, options, waiter);

            // Prevent this example application from ending. 
            // A real application should do something useful 
            // when possible.
            waiter.WaitOne ();
            Console.WriteLine ("Ping example completed.");
        }

.NET Framework

Supported in: 4.5, 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

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

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft