Buttplug Client/Server Ping

Ping timing is a property of a Buttplug session negotiated when a client connects to a server. Ping is a Buttplug protocol specific negotiated keep-alive, with the server dictating the expected ping time to the client. A ping time of 0 denotes "no ping expected", while any number above that is the expected maximum amount of time in milliseconds between pings.

Ping exists to try ensuring some basic level of safety for usage if a client application locks up, remote connection is interrupted, or other horrible scenarios occur that stop ping messages from being transmitted. If a client does not send a ping message within the alloted time, the server is expected to disconnect and stop all devices that are currently active.

Keeping in line with the knowledge that reference, and most likely, all implementations of Buttplug are neither real-time constrained nor safety-guaranteed, the Ping system is more of a vaguely hopeful mitigation than a secure requirement. Your milage may vary. Don't die.

For some connectors, like the Websocket connector, there may already be ping built into that protocol, at which point Buttplug Server Ping may be redundant.

In reference library implementations of the Client, ping negotiation is handled opaquely by the client API. It is assumed that if the client's event loop fails to send a ping, the program has most likely locked up or crashed, and therefore everything should be shut down. Therefore, no code samples are provided for this. It should just work.

On ping failure in the client APIs, you should either receive some sort of event or callback denoting the error. The event or callback arguments will contain an error with an error class type of ERROR_PING. Any subsequent calls to server commands (device search/commands, etc) will fail from this point on.

C#

// Buttplug C# - Ping Timeout Example
//
// This example shows how to handle the PingTimeout event.
// Note: Ping handling is automatic in the C# client. The PingTimeout
// event fires when the server fails to respond, indicating the connection
// should be considered dead.

using Buttplug.Client;

var client = new ButtplugClient("Ping Example");

// The PingTimeout event fires when the server doesn't respond to keep-alive pings.
// This usually means the connection has been lost.
client.PingTimeout += (sender, args) =>
{
    Console.WriteLine("Ping timeout! Server connection lost.");
    Console.WriteLine("All devices should be stopped by the server.");
    // In a real application, you would:
    // - Update UI to show disconnected state
    // - Attempt to reconnect if appropriate
    // - Clean up any resources
};

// Connect normally - ping handling is automatic
await client.ConnectAsync("ws://127.0.0.1:12345");
Console.WriteLine("Connected. Ping keep-alive is handled automatically.");

Console.WriteLine("Press Enter to disconnect...");
Console.ReadLine();

await client.DisconnectAsync();