Interface IPings

This feature provides a client session with the ability to test its connection to the server.

Inherited Members
Namespace: PushTechnology.ClientInterface.Client.Features
Assembly: Diffusion.Client.dll
Syntax
public interface IPings : IFeature
Remarks

The main purpose of a ping is to test, at a very basic level, the current network conditions that exist between the client session and the server it is connected to. The ping response includes the time taken to make a round-trip call to the server.

Access control

There are no permissions requirements associated with this feature.

Accessing the feature

This feature may be obtained from an ISession as follows: 

var ping = session.Ping;

// Pinging the server and waiting for the result.
// This operation will block until the ping details have
// been received.
var details = pings.PingServerAsync().Result;


// Any exceptions thrown within the PingServerAsync()
// method will be packed into an AggregateException.
try {
var details = pings.PingServerAsync().Result;
} catch ( AggregateException ae ) {
ae.Handle( ex => {
// Handle specific exception in here.
return true; // Exception is handled.
} );
}


// Pinging the server in an async/await scenario.
var details = await pings.PingServerAsync();


// Exceptions in an async/await scenario will not
// be bundled into an AggregateException so they
// have to be handled in the usual way.
try {
var details = await pings.PingServerAsync();
} catch ( SessionClosedException ex ) {
// Handle session closed exception.
}


// The await/async pattern is the preferred way to
// use the IPings feature. For more information visit:
// https://msdn.microsoft.com/en-gb/library/mt674882.aspx

Added in version 5.0.

Methods

PingServer(IPingCallback)

Sends a ping request to the server.

Declaration
void PingServer(IPingCallback callback)
Parameters
Type Name Description
IPingCallback callback

The callback for the response to this ping operation.
Remarks

Caution

Deprecated since 6.7. Methods that use callbacks are deprecated and will be removed in a future release. Use a Task instead.

PingServer<TContext>(TContext, IPingContextCallback<TContext>)

Sends a ping request to the server.

Declaration
void PingServer<TContext>(TContext context, IPingContextCallback<TContext> callback)
Parameters
Type Name Description
TContext context

The context object that will be passed to the callback.
IPingContextCallback<TContext> callback

The callback for the response to this ping operation.
Type Parameters
Name Description
TContext

The context type.
Remarks

Caution

Deprecated since 6.7. Methods that use contextual callbacks are deprecated and will be removed in a future release. Use a Task instead.

PingServerAsync()

Sends a ping request to the server.

Declaration
Task<IPingDetails> PingServerAsync()
Returns
Type Description
Task<IPingDetails>

The task representing the current operation.
Remarks

Since 6.0

Exceptions
Type Condition
SessionClosedException

The session is closed. Thrown by the returned task.
See Also

PingServerAsync(CancellationToken)

Sends a ping request to the server.

Declaration
Task<IPingDetails> PingServerAsync(CancellationToken cancellationToken)
Parameters
Type Name Description
CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
Task<IPingDetails>

The task representing the current operation.
Remarks

Since 6.0

Examples

Pinging the server with a cancellation token

try {
    var src = new CancellationTokenSource();
    var details = await session.Ping.PingServerAsync( src.Token );
} catch ( SessionClosedException ex ) {
    Console.WriteLine( $"Ping failed. Reason: {ex}." );
}
Exceptions
Type Condition
SessionClosedException

The session is closed. Thrown by the returned task.