diff --git a/docs/JSON-RPC.md b/docs/JSON-RPC.md index 3501fbdc9d..620d2bf78d 100644 --- a/docs/JSON-RPC.md +++ b/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. diff --git a/src/clientrpc.cpp b/src/clientrpc.cpp index 0f376d10b4..bbadd0fb61 100644 --- a/src/clientrpc.cpp +++ b/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).