Add JSON-RPC client connection control

New methods: jamulusclient/connect, jamulusclient/disconnect and
jamulusclient/getConnectionState. New notifications:
jamulusclient/connecting, jamulusclient/connectingFailed and
jamulusclient/connectionStateChanged. Together with the existing
connected/disconnected notifications this gives JSON-RPC full parity
with the UI for joining and leaving servers (#3801) and makes a
--nogui client fully scriptable.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: jrd

docs/JSON-RPC.md

@@ -129,6 +129,41 @@ Results:
 | result.version | string | The Jamulus version. |
 
 
+### jamulusclient/connect
+
+Connects the client to a server. Any current connection is terminated first. The connection is established asynchronously: subscribe to the jamulusclient/connecting, jamulusclient/connected, jamulusclient/connectingFailed and jamulusclient/connectionStateChanged notifications to follow its progress.
+
+Parameters:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| params.address | string | Socket address of the server (host:port). |
+| params.serverName | string | Optional human readable server name used for display purposes. Defaults to the address. |
+
+Results:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| result | string | "ok" once the connection attempt has been initiated. |
+
+
+### jamulusclient/disconnect
+
+Disconnects the client from the current server. Does nothing if the client is not connected.
+
+Parameters:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| params | object | No parameters (empty object). |
+
+Results:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| result | string | Always "ok". |
+
+
 ### jamulusclient/getChannelInfo
 
 Returns the client's profile information.
@@ -188,6 +223,24 @@ Results:
 | result.clients | array | The client list. See jamulusclient/clientListReceived for the format. |
 
 
+### jamulusclient/getConnectionState
+
+Returns the current connection state.
+
+Parameters:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| params | object | No parameters (empty object). |
+
+Results:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| result.state | string | The connection state (disconnected, connecting, or connected). |
+| result.serverName | string | The human readable name of the current server (empty if disconnected). |
+
+
 ### jamulusclient/getCurrentDirectory
 
 Returns the currently selected directory socket address.
@@ -656,6 +709,39 @@ Parameters:
 | params.id | number | The channel ID assigned to the client. |
 
 
+### jamulusclient/connecting
+
+Emitted when a connection to a server has been requested but is not yet established.
+
+Parameters:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| params.serverName | string | The human readable server name (or the address if no name is known). |
+
+
+### jamulusclient/connectingFailed
+
+Emitted when a connection attempt failed before it could be requested from the server.
+
+Parameters:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| params.error | string | The error message. |
+
+
+### jamulusclient/connectionStateChanged
+
+Emitted whenever the connection state changes.
+
+Parameters:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| params.state | string | The new connection state (disconnected, connecting, or connected). |
+
+
 ### jamulusclient/disconnected
 
 Emitted when the client is disconnected from the server.

src/clientrpc.cpp

@@ -47,6 +47,21 @@
 
 #include "clientrpc.h"
 
+static QString ConnectionStateToString ( const EConnectionState eState )
+{
+    switch ( eState )
+    {
+    case CS_CONNECTING:
+        return "connecting";
+
+    case CS_CONNECTED:
+        return "connected";
+
+    default:
+        return "disconnected";
+    }
+}
+
 CClientRpc::CClientRpc ( CClient* pClient, CClientSettings* pSettings, CRpcServer* pRpcServer, QObject* parent ) :
     QObject ( parent ),
     m_pSettings ( pSettings )
@@ -168,6 +183,36 @@ CClientRpc::CClientRpc ( CClient* pClient, CClientSettings* pSettings, CRpcServe
     /// @param {object} params - No parameters (empty object).
     connect ( pClient, &CClient::Disconnected, [=]() { pRpcServer->BroadcastNotification ( "jamulusclient/disconnected", QJsonObject{} ); } );
 
+    /// @rpc_notification jamulusclient/connecting
+    /// @brief Emitted when a connection to a server has been requested but is not yet established.
+    /// @param {string} params.serverName - The human readable server name (or the address if no name is known).
+    connect ( pClient, &CClient::Connecting, [=] ( QString strServerName ) {
+        pRpcServer->BroadcastNotification ( "jamulusclient/connecting",
+                                            QJsonObject{
+                                                { "serverName", strServerName },
+                                            } );
+    } );
+
+    /// @rpc_notification jamulusclient/connectingFailed
+    /// @brief Emitted when a connection attempt failed before it could be requested from the server.
+    /// @param {string} params.error - The error message.
+    connect ( pClient, &CClient::ConnectingFailed, [=] ( QString strError ) {
+        pRpcServer->BroadcastNotification ( "jamulusclient/connectingFailed",
+                                            QJsonObject{
+                                                { "error", strError },
+                                            } );
+    } );
+
+    /// @rpc_notification jamulusclient/connectionStateChanged
+    /// @brief Emitted whenever the connection state changes.
+    /// @param {string} params.state - The new connection state (disconnected, connecting, or connected).
+    connect ( pClient, &CClient::ConnectionStateChanged, [=] ( EConnectionState eState ) {
+        pRpcServer->BroadcastNotification ( "jamulusclient/connectionStateChanged",
+                                            QJsonObject{
+                                                { "state", ConnectionStateToString ( eState ) },
+                                            } );
+    } );
+
     /// @rpc_notification jamulusclient/recorderState
     /// @brief Emitted when the client is connected to a server whose recorder state changes.
     /// @param {number} params.state - The recorder state.
@@ -212,6 +257,58 @@ CClientRpc::CClientRpc ( CClient* pClient, CClientSettings* pSettings, CRpcServe
         Q_UNUSED ( params );
     } );
 
+    /// @rpc_method jamulusclient/connect
+    /// @brief Connects the client to a server. Any current connection is terminated first.
+    ///        The connection is established asynchronously: subscribe to the jamulusclient/connecting,
+    ///        jamulusclient/connected, jamulusclient/connectingFailed and jamulusclient/connectionStateChanged
+    ///        notifications to follow its progress.
+    /// @param {string} params.address - Socket address of the server (host:port).
+    /// @param {string} params.serverName - Optional human readable server name used for display purposes. Defaults to the address.
+    /// @result {string} result - "ok" once the connection attempt has been initiated.
+    pRpcServer->HandleMethod ( "jamulusclient/connect", [=] ( const QJsonObject& params, QJsonObject& response ) {
+        auto jsonAddress = params["address"];
+        if ( !jsonAddress.isString() )
+        {
+            response["error"] = CRpcServer::CreateJsonRpcError ( CRpcServer::iErrInvalidParams, "Invalid params: address is not a string" );
+            return;
+        }
+
+        auto          jsonServerName = params["serverName"];
+        const QString strAddress     = NetworkUtil::FixAddress ( jsonAddress.toString() );
+        const QString strServerName  = jsonServerName.isString() ? jsonServerName.toString() : strAddress;
+
+        pClient->Connect ( strAddress, strServerName );
+
+        response["result"] = "ok";
+    } );
+
+    /// @rpc_method jamulusclient/disconnect
+    /// @brief Disconnects the client from the current server. Does nothing if the client is not connected.
+    /// @param {object} params - No parameters (empty object).
+    /// @result {string} result - Always "ok".
+    pRpcServer->HandleMethod ( "jamulusclient/disconnect", [=] ( const QJsonObject& params, QJsonObject& response ) {
+        pClient->Disconnect();
+
+        response["result"] = "ok";
+        Q_UNUSED ( params );
+    } );
+
+    /// @rpc_method jamulusclient/getConnectionState
+    /// @brief Returns the current connection state.
+    /// @param {object} params - No parameters (empty object).
+    /// @result {string} result.state - The connection state (disconnected, connecting, or connected).
+    /// @result {string} result.serverName - The human readable name of the current server (empty if disconnected).
+    pRpcServer->HandleMethod ( "jamulusclient/getConnectionState", [=] ( const QJsonObject& params, QJsonObject& response ) {
+        const EConnectionState eState = pClient->GetConnectionState();
+
+        QJsonObject result{
+            { "state", ConnectionStateToString ( eState ) },
+            { "serverName", eState == CS_DISCONNECTED ? QString() : pClient->GetConnectedServerName() },
+        };
+        response["result"] = result;
+        Q_UNUSED ( params );
+    } );
+
     /// @rpc_method jamulus/getMode
     /// @brief Returns the current mode, i.e. whether Jamulus is running as a server or client.
     /// @param {object} params - No parameters (empty object).