Ping.SendAsync Method

Definition

Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message to a computer, and receive a corresponding ICMP echo reply message from that computer.

Overloads

SendAsync(String, Int32, Byte[], PingOptions, Object)

Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the specified computer, 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 packet.

SendAsync(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.

SendAsync(String, Int32, Byte[], Object)

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

SendAsync(IPAddress, Int32, Byte[], 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.

SendAsync(IPAddress, Int32, Object)

Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message 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.

SendAsync(String, Object)

Asynchronously 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.

SendAsync(IPAddress, Object)

Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message to the computer that has the specified IPAddress, and receive a corresponding ICMP echo reply message from that computer.

SendAsync(String, Int32, Object)

Asynchronously 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 overload allows you to specify a time-out value for the operation.

Remarks

These methods do not cause your application's main thread to block. If you want to block while waiting for the ICMP echo reply message, use the Send methods.

Note

The IP address returned by any of the SendAsync methods can originate from a malicious remote computer. Do not connect to the remote computer using this. Use DNS to determine the IP address of the machine to which you want to connect.

SendAsync(String, Int32, Byte[], PingOptions, Object)

Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the specified computer, 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 packet.

public:
 void SendAsync(System::String ^ hostNameOrAddress, int timeout, cli::array <System::Byte> ^ buffer, System::Net::NetworkInformation::PingOptions ^ options, System::Object ^ userToken);
public void SendAsync (string hostNameOrAddress, int timeout, byte[] buffer, System.Net.NetworkInformation.PingOptions? options, object? userToken);
public void SendAsync (string hostNameOrAddress, int timeout, byte[] buffer, System.Net.NetworkInformation.PingOptions options, object userToken);
member this.SendAsync : string * int * byte[] * System.Net.NetworkInformation.PingOptions * obj -> unit
Public Sub SendAsync (hostNameOrAddress As String, timeout As Integer, buffer As Byte(), options As PingOptions, userToken As Object)

Parameters

hostNameOrAddress
String

A String that identifies the computer that is the destination for the ICMP echo message. The value specified for this parameter can be a host name or a string representation of an IP address.

timeout
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
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
PingOptions

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

userToken
Object

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

Exceptions

hostNameOrAddress is null or is an empty string ("").

-or-

buffer is null.

timeout is less than zero.

A call to SendAsync is in progress.

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

hostNameOrAddress could not be resolved to a valid IP address.

This object has been disposed.

The size of buffer exceeds 65500 bytes.

.NET 7 and later versions only on Linux: The process is non-privileged, and buffer is not empty.

Examples

The following code example demonstrates how to call this method.

#using <System.dll>

using namespace System;
using namespace System::Text;
using namespace System::Net;
using namespace System::Net::NetworkInformation;
using namespace System::ComponentModel;
using namespace System::Threading;
void PingCompletedCallback( Object^ sender, PingCompletedEventArgs^ e );
void DisplayReply( PingReply^ reply );
int main()
{
   array<String^>^args = Environment::GetCommandLineArgs();
   if ( args->Length == 1 )
      throw gcnew ArgumentException( "Ping needs a host or IP Address." );

   String^ who = args[ 1 ];
   AutoResetEvent^ waiter = gcnew AutoResetEvent( false );
   
   Ping ^ pingSender = gcnew Ping;
   
   // When the PingCompleted event is raised,
   // the PingCompletedCallback method is called.
   pingSender->PingCompleted += gcnew PingCompletedEventHandler( PingCompletedCallback );
   
   // Create a buffer of 32 bytes of data to be transmitted.
   String^ data = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
   array<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 gateways or routers
   // before it is destroyed, and the data packet
   // cannot be fragmented.
   PingOptions ^ options = gcnew 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 application should do something useful
   // when possible.
   waiter->WaitOne();
   Console::WriteLine( "Ping example completed." );
}


void 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 AutoResetEvent object that the main thread 
      // is waiting for.
      (dynamic_cast<AutoResetEvent^>(e->UserState))->Set();
   }

   
   // If an error occurred, display the exception to the user.
   if ( e->Error != nullptr )
   {
      Console::WriteLine( "Ping failed:" );
      Console::WriteLine( e->Error->ToString() );
      
      // Let the main thread resume. 
      (dynamic_cast<AutoResetEvent^>(e->UserState))->Set();
   }

   PingReply ^ reply = e->Reply;
   DisplayReply( reply );
   
   // Let the main thread resume.
   (dynamic_cast<AutoResetEvent^>(e->UserState))->Set();
}


void DisplayReply( PingReply ^ reply )
{
   if ( reply == nullptr )
      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->DontFragment );
      Console::WriteLine( "Buffer size: {0}", reply->Buffer->Length );
   }
}
using System;
using System.Text;
using System.Net;
using System.Net.NetworkInformation;
using System.ComponentModel;
using System.Threading;

namespace Examples.System.Net.NetworkInformation.PingTest
{
    public class PingExample
    {
        public static void Main (string[] args)
        {
            if (args.Length == 0)
                throw new 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 PingCompletedCallback method 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 gateways or 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 application should do something useful
            // when possible.
            waiter.WaitOne ();
            Console.WriteLine ("Ping example completed.");
        }

        private static void 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 AutoResetEvent object that the main thread
                // is waiting for.
                ((AutoResetEvent)e.UserState).Set ();
            }

            // 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();
        }

        public static void 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.DontFragment);
                Console.WriteLine ("Buffer size: {0}", reply.Buffer.Length);
            }
        }
    }
}

Remarks

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 should block 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.

Note

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.

Applies to

SendAsync(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.

public:
 void SendAsync(System::Net::IPAddress ^ address, int timeout, cli::array <System::Byte> ^ buffer, System::Net::NetworkInformation::PingOptions ^ options, System::Object ^ userToken);
public void SendAsync (System.Net.IPAddress address, int timeout, byte[] buffer, System.Net.NetworkInformation.PingOptions? options, object? userToken);
public void SendAsync (System.Net.IPAddress address, int timeout, byte[] buffer, System.Net.NetworkInformation.PingOptions options, object userToken);
member this.SendAsync : System.Net.IPAddress * int * byte[] * System.Net.NetworkInformation.PingOptions * obj -> unit
Public Sub SendAsync (address As IPAddress, timeout As Integer, buffer As Byte(), options As PingOptions, userToken As Object)

Parameters

address
IPAddress

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

timeout
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
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
PingOptions

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

userToken
Object

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

Exceptions

address or buffer is null.

timeout is less than zero.

A call to SendAsync is in progress.

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

address is not a valid IP address.

This object has been disposed.

The size of buffer exceeds 65500 bytes.

.NET 7 and later versions only on Linux: The process is non-privileged, and buffer is not empty.

Examples

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.dll>

using namespace System;
using namespace System::Net;
using namespace System::Net::NetworkInformation;
using namespace System::Text;
using namespace System::Threading;
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.

void AsyncComplexLocalPing()
{
   
   // Get an object that will block the main thread.
   AutoResetEvent^ waiter = gcnew AutoResetEvent( false );
   
   // Ping's the local machine.
   Ping ^ pingSender = gcnew Ping;
   
   // When the PingCompleted event is raised,
   // the PingCompletedCallback method is called.
   pingSender->PingCompleted += gcnew PingCompletedEventHandler( PingCompletedCallback );
   IPAddress^ address = IPAddress::Loopback;
   
   // Create a buffer of 32 bytes of data to be transmitted.
   String^ data = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
   array<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 = gcnew 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." );
}
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.");
}

Remarks

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.

Note

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.

Applies to

SendAsync(String, Int32, Byte[], Object)

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

public:
 void SendAsync(System::String ^ hostNameOrAddress, int timeout, cli::array <System::Byte> ^ buffer, System::Object ^ userToken);
public void SendAsync (string hostNameOrAddress, int timeout, byte[] buffer, object? userToken);
public void SendAsync (string hostNameOrAddress, int timeout, byte[] buffer, object userToken);
member this.SendAsync : string * int * byte[] * obj -> unit
Public Sub SendAsync (hostNameOrAddress As String, timeout As Integer, buffer As Byte(), userToken As Object)

Parameters

hostNameOrAddress
String

A String that identifies the computer that is the destination for the ICMP echo message. The value specified for this parameter can be a host name or a string representation of an IP address.

timeout
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
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.

userToken
Object

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

Exceptions

hostNameOrAddress is null or is an empty string ("").

-or-

buffer is null.

timeout is less than zero.

A call to SendAsync is in progress.

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

hostNameOrAddress could not be resolved to a valid IP address.

This object has been disposed.

The size of buffer exceeds 65500 bytes.

.NET 7 and later versions only on Linux: The process is non-privileged, and buffer is not empty.

Examples

The following code example demonstrates how to call a SendAsync overload, see the Ping class overview.

Remarks

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 should 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 containing 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 should block 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.

Note

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

This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if 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. To prevent fragmentation, use one of the SendAsync methods that takes an options parameter, and set the DontFragment property to true. When DontFragment 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. The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a SendAsync overload that takes an options parameter, and set the Ttl property to the desired value. 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.

Applies to

SendAsync(IPAddress, Int32, Byte[], 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.

public:
 void SendAsync(System::Net::IPAddress ^ address, int timeout, cli::array <System::Byte> ^ buffer, System::Object ^ userToken);
public void SendAsync (System.Net.IPAddress address, int timeout, byte[] buffer, object? userToken);
public void SendAsync (System.Net.IPAddress address, int timeout, byte[] buffer, object userToken);
member this.SendAsync : System.Net.IPAddress * int * byte[] * obj -> unit
Public Sub SendAsync (address As IPAddress, timeout As Integer, buffer As Byte(), userToken As Object)

Parameters

address
IPAddress

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

timeout
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
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.

userToken
Object

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

Exceptions

address or buffer is null.

timeout is less than zero.

A call to SendAsync is in progress.

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

address is not a valid IP address.

This object has been disposed.

The size of buffer exceeds 65500 bytes.

.NET 7 and later versions only on Linux: The process is non-privileged, and buffer is not empty.

Examples

For a code example that demonstrates calling a SendAsync overload, see the Ping class overview.

Remarks

This 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 should 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. 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.

Note

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.

Note

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

This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if 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. To prevent fragmentation, use one of the SendAsync methods that takes an options parameter, and set the DontFragment property to true. When DontFragment 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. The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a SendAsync overload that takes an options parameter, and set the Ttl property to the desired value. 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.

Applies to

SendAsync(IPAddress, Int32, Object)

Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message 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.

public:
 void SendAsync(System::Net::IPAddress ^ address, int timeout, System::Object ^ userToken);
public void SendAsync (System.Net.IPAddress address, int timeout, object? userToken);
public void SendAsync (System.Net.IPAddress address, int timeout, object userToken);
member this.SendAsync : System.Net.IPAddress * int * obj -> unit
Public Sub SendAsync (address As IPAddress, timeout As Integer, userToken As Object)

Parameters

address
IPAddress

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

timeout
Int32

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

userToken
Object

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

Exceptions

address is null.

timeout is less than zero.

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

address is not a valid IP address.

This object has been disposed.

Examples

For a code example that demonstrates calling a SendAsync overload, see the Ping class overview.

Remarks

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 should 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 should block 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.

Note

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

This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if 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. To prevent fragmentation, use one of the SendAsync methods that takes an options parameter, and set the DontFragment property to true. When DontFragment 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. The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a SendAsync overload that takes an options parameter, and set the Ttl property to the desired value. 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.

Applies to

SendAsync(String, Object)

Asynchronously 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.

public:
 void SendAsync(System::String ^ hostNameOrAddress, System::Object ^ userToken);
public void SendAsync (string hostNameOrAddress, object? userToken);
public void SendAsync (string hostNameOrAddress, object userToken);
member this.SendAsync : string * obj -> unit
Public Sub SendAsync (hostNameOrAddress As String, userToken As Object)

Parameters

hostNameOrAddress
String

A String that identifies the computer that is the destination for the ICMP echo message. The value specified for this parameter can be a host name or a string representation of an IP address.

userToken
Object

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

Exceptions

hostNameOrAddress is null or is an empty string ("").

A call to SendAsync(String, Object) method is in progress.

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

hostNameOrAddress could not be resolved to a valid IP address.

This object has been disposed.

Examples

For a code example that demonstrates calling the SendAsync method, see the Ping class overview.

Remarks

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 should not block. Each call to this method executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the PingCompleted event. 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.

Note

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

This method sends a 32 Byte data buffer with the ICMP echo message. The method waits five seconds for an ICMP echo reply message. If it does not receive a reply in that time the method returns and the Status property is set to TimedOut.

This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if 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. To prevent fragmentation, use one of the SendAsync methods that takes an options parameter, and set the DontFragment property to true. When DontFragment 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.

The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a SendAsync overload that takes an options parameter, and set the Ttl property to the desired value. 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.

Applies to

SendAsync(IPAddress, Object)

Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message to the computer that has the specified IPAddress, and receive a corresponding ICMP echo reply message from that computer.

public:
 void SendAsync(System::Net::IPAddress ^ address, System::Object ^ userToken);
public void SendAsync (System.Net.IPAddress address, object? userToken);
public void SendAsync (System.Net.IPAddress address, object userToken);
member this.SendAsync : System.Net.IPAddress * obj -> unit
Public Sub SendAsync (address As IPAddress, userToken As Object)

Parameters

address
IPAddress

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

userToken
Object

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

Exceptions

address is null.

A call to the SendAsync method is in progress.

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

address is not a valid IP address.

This object has been disposed.

Examples

For a code example that demonstrates calling a SendAsync method, see the Ping class overview.

Remarks

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 should not block. Each call to this method executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the PingCompleted event. 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.

Note

If your application should block while waiting for a reply, use one of the Send methods; these methods are synchronous.

This method sends a 32 Byte data buffer with the ICMP echo message. The method waits five seconds for an ICMP echo reply message. If it does not receive a reply in that time, the method returns and the Status property is set to TimedOut.

This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if 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. To prevent fragmentation, use one of the SendAsync methods that takes an options parameter, and set the DontFragment property to true. When DontFragment 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.

The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a SendAsync overload that takes an options parameter, and set the Ttl property to the desired value. 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.

Applies to

SendAsync(String, Int32, Object)

Asynchronously 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 overload allows you to specify a time-out value for the operation.

public:
 void SendAsync(System::String ^ hostNameOrAddress, int timeout, System::Object ^ userToken);
public void SendAsync (string hostNameOrAddress, int timeout, object? userToken);
public void SendAsync (string hostNameOrAddress, int timeout, object userToken);
member this.SendAsync : string * int * obj -> unit
Public Sub SendAsync (hostNameOrAddress As String, timeout As Integer, userToken As Object)

Parameters

hostNameOrAddress
String

A String that identifies the computer that is the destination for the ICMP echo message. The value specified for this parameter can be a host name or a string representation of an IP address.

timeout
Int32

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

userToken
Object

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

Exceptions

hostNameOrAddress is null or is an empty string ("").

timeout is less than zero.

A call to SendAsync is in progress.

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

hostNameOrAddress could not be resolved to a valid IP address.

This object has been disposed.

Examples

For a code example that demonstrates calling the SendAsync method, see the Ping class overview.

Remarks

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 should 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 should block 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.

Note

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

This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if 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. To prevent fragmentation, use one of the SendAsync methods that takes an options parameter, and set the DontFragment property to true. When DontFragment 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. The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a SendAsync overload that takes an options parameter, and set the Ttl property to the desired value. 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.

Applies to