Add JSON-RPC access to directories and server lists

riban-bw · ann0see · commit ec574574e45c · 2025-02-13T11:21:30.000+01:00
Squash from: #3249 rpc_notification jamulusclient/serverListReceived rpc_method jamulus/pollServerList Change JSON-RPC for server list. Use pollServerList instead of getServerList. (No result returned from the call.) Change "address" to "url" Adds documentation for new JSON-RPC methods Consistent use of countryId Fixes JSON-RPC docs JSON-RPC fixes for feedback to PR Changes method "jamulus/pollServerList" to "jamulusclient/pollServerList" (for consistency). Changes "url" to "address" in protocol and "server address" in docs. Fixes typo in countryId. JSON-RPC Enhancements Adds jamulusclient/connect method. Adds jamulusclient/disconnect method. Adds jamulusclient/serverInfoReceived notification. Return country string rather than (QT specific) country code. Request server info after server list received (to get each server's ping time and num clients). JSON-RPC enhancements Adds method jamulusclient/recorderState. Changes intrument code to instrument name (remote client may not have access to lookup table). Fixes errors in docs. Fixes coding style Update docs Fix coding style
diff --git a/docs/JSON-RPC.md b/docs/JSON-RPC.md
@@ -129,6 +129,57 @@ Results:
 | result.version | string | The Jamulus version. |
 
 
+### jamulus/pollServerList
+
+Request list of servers in a directory
+
+Parameters:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| params.directory | string | socket address of directory to query, e.g. anygenre1.jamulus.io:22124. |
+
+Results:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| result | string | "ok" or "error" if bad arguments. |
+
+
+### jamulusclient/connect
+
+Disconnect client from server
+
+Parameters:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| params.address | string | Server socket address (ip_addr:port). |
+
+Results:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| result | string | Always "ok". |
+
+
+### jamulusclient/disconnect
+
+Disconnect client from server
+
+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.
@@ -146,9 +197,9 @@ Results:
 | result.id | number | The channel ID. |
 | result.name | string | The musician’s name. |
 | result.skillLevel | string | The musician’s skill level (beginner, intermediate, expert, or null). |
-| result.countryId | number | The musician’s country ID (see QLocale::Country). |
+| result.country | string | The musician’s country. |
 | result.city | string | The musician’s city. |
-| result.instrumentId | number | The musician’s instrument ID (see CInstPictures::GetTable). |
+| result.instrument | number | The musician’s instrument. |
 | result.skillLevel | string | Your skill level (beginner, intermediate, expert, or null). |
 
 
@@ -444,9 +495,9 @@ Parameters:
 | params.clients[*].id | number | The channel ID. |
 | params.clients[*].name | string | The musician’s name. |
 | params.clients[*].skillLevel | string | The musician’s skill level (beginner, intermediate, expert, or null). |
-| params.clients[*].countryId | number | The musician’s country ID (see QLocale::Country). |
+| params.clients[*].country | string | The musician’s country. |
 | params.clients[*].city | string | The musician’s city. |
-| params.clients[*].instrumentId | number | The musician’s instrument ID (see CInstPictures::GetTable). |
+| params.clients[*].instrument | string | The musician’s instrument. |
 
 
 ### jamulusclient/connected
@@ -471,3 +522,42 @@ Parameters:
 | params | object | No parameters (empty object). |
 
 
+### jamulusclient/recorderState
+
+Emitted when the client is connected to a server who's recorder state changes.
+
+Parameters:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| params.state | number | The recorder state |
+
+
+### jamulusclient/serverInfoReceived
+
+Emitted when a server info is received.
+
+Parameters:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| params.address | string | The server socket address |
+| params.pingtime | number | The round-trip ping time in ms |
+| params.numClients | number | The quantity of clients connected to the server |
+
+
+### jamulusclient/serverListReceived
+
+Emitted when the server list is received.
+
+Parameters:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| params.servers | array | The server list. |
+| params.servers[*].address | string | Socket address (ip_address:port) |
+| params.servers[*].name | string | Server name |
+| params.servers[*].country | string | Server country |
+| params.servers[*].city | string | Server city |
+
+
diff --git a/src/client.h b/src/client.h
@@ -286,6 +286,8 @@ class CClient : public QObject
         Channel.GetBufErrorRates ( vecErrRates, dLimit, dMaxUpLimit );
     }
 
+    CProtocol* getConnLessProtocol() { return &ConnLessProtocol; }
+
     // settings
     CChannelCoreInfo ChannelInfo;
     QString          strClientName;
diff --git a/src/clientrpc.cpp b/src/clientrpc.cpp
@@ -53,9 +53,9 @@ CClientRpc::CClientRpc ( CClient* pClient, CRpcServer* pRpcServer, QObject* pare
     /// @param {number} params.clients[*].id - The channel ID.
     /// @param {string} params.clients[*].name - The musician’s name.
     /// @param {string} params.clients[*].skillLevel - The musician’s skill level (beginner, intermediate, expert, or null).
-    /// @param {number} params.clients[*].countryId - The musician’s country ID (see QLocale::Country).
+    /// @param {string} params.clients[*].country - The musician’s country.
     /// @param {string} params.clients[*].city - The musician’s city.
-    /// @param {number} params.clients[*].instrumentId - The musician’s instrument ID (see CInstPictures::GetTable).
+    /// @param {string} params.clients[*].instrument - The musician’s instrument.
     connect ( pClient, &CClient::ConClientListMesReceived, [=] ( CVector<CChannelInfo> vecChanInfo ) {
         QJsonArray arrChanInfo;
         for ( const auto& chanInfo : vecChanInfo )
@@ -64,9 +64,9 @@ CClientRpc::CClientRpc ( CClient* pClient, CRpcServer* pRpcServer, QObject* pare
                 { "id", chanInfo.iChanID },
                 { "name", chanInfo.strName },
                 { "skillLevel", SerializeSkillLevel ( chanInfo.eSkillLevel ) },
-                { "countryId", chanInfo.eCountry },
+                { "country", QLocale::countryToString ( chanInfo.eCountry ) },
                 { "city", chanInfo.strCity },
-                { "instrumentId", chanInfo.iInstrument },
+                { "instrument", CInstPictures::GetName ( chanInfo.iInstrument ) },
             };
             arrChanInfo.append ( objChanInfo );
         }
@@ -94,11 +94,125 @@ CClientRpc::CClientRpc ( CClient* pClient, CRpcServer* pRpcServer, QObject* pare
                                             } );
     } );
 
+    /// @rpc_notification jamulusclient/serverListReceived
+    /// @brief Emitted when the server list is received.
+    /// @param {array} params.servers - The server list.
+    /// @param {string} params.servers[*].address - Socket address (ip_address:port)
+    /// @param {string} params.servers[*].name - Server name
+    /// @param {string} params.servers[*].country - Server country
+    /// @param {string} params.servers[*].city - Server city
+    connect ( pClient->getConnLessProtocol(),
+              &CProtocol::CLServerListReceived,
+              [=] ( CHostAddress /* unused */, CVector<CServerInfo> vecServerInfo ) {
+                  QJsonArray arrServerInfo;
+                  for ( const auto& serverInfo : vecServerInfo )
+                  {
+                      QJsonObject objServerInfo{
+                          { "address", serverInfo.HostAddr.toString() },
+                          { "name", serverInfo.strName },
+                          { "country", QLocale::countryToString ( serverInfo.eCountry ) },
+                          { "city", serverInfo.strCity },
+                      };
+                      arrServerInfo.append ( objServerInfo );
+                      pClient->CreateCLServerListPingMes ( serverInfo.HostAddr );
+                  }
+                  pRpcServer->BroadcastNotification ( "jamulusclient/serverListReceived",
+                                                      QJsonObject{
+                                                          { "servers", arrServerInfo },
+                                                      } );
+              } );
+
+    /// @rpc_notification jamulusclient/serverInfoReceived
+    /// @brief Emitted when a server info is received.
+    /// @param {string} params.address - The server socket address
+    /// @param {number} params.pingtime - The round-trip ping time in ms
+    /// @param {number} params.numClients - The quantity of clients connected to the server
+    connect ( pClient, &CClient::CLPingTimeWithNumClientsReceived, [=] ( CHostAddress InetAddr, int iPingTime, int iNumClients ) {
+        pRpcServer->BroadcastNotification (
+            "jamulusclient/serverInfoReceived",
+            QJsonObject{ { "address", InetAddr.toString() }, { "pingTime", iPingTime }, { "numClients", iNumClients } } );
+    } );
+
     /// @rpc_notification jamulusclient/disconnected
     /// @brief Emitted when the client is disconnected from the server.
     /// @param {object} params - No parameters (empty object).
     connect ( pClient, &CClient::Disconnected, [=]() { pRpcServer->BroadcastNotification ( "jamulusclient/disconnected", QJsonObject{} ); } );
 
+    /// @rpc_notification jamulusclient/recorderState
+    /// @brief Emitted when the client is connected to a server who's recorder state changes.
+    /// @param {number} params.state - The recorder state
+    connect ( pClient, &CClient::RecorderStateReceived, [=] ( const ERecorderState newRecorderState ) {
+        pRpcServer->BroadcastNotification ( "jamulusclient/recorderState", QJsonObject{ { "state", newRecorderState } } );
+    } );
+
+    /// @rpc_method jamulus/pollServerList
+    /// @brief Request list of servers in a directory
+    /// @param {string} params.directory - socket address of directory to query, e.g. anygenre1.jamulus.io:22124.
+    /// @result {string} result - "ok" or "error" if bad arguments.
+    pRpcServer->HandleMethod ( "jamulusclient/pollServerList", [=] ( const QJsonObject& params, QJsonObject& response ) {
+        auto jsonDirectoryIp = params["directory"];
+        if ( !jsonDirectoryIp.isString() )
+        {
+            response["error"] = CRpcServer::CreateJsonRpcError ( CRpcServer::iErrInvalidParams, "Invalid params: directory is not a string" );
+            return;
+        }
+
+        CHostAddress haDirectoryAddress;
+        if ( NetworkUtil().ParseNetworkAddress ( jsonDirectoryIp.toString(), haDirectoryAddress, false ) )
+        {
+            // send the request for the server list
+            pClient->CreateCLReqServerListMes ( haDirectoryAddress );
+            response["result"] = "ok";
+        }
+        else
+        {
+            response["error"] =
+                CRpcServer::CreateJsonRpcError ( CRpcServer::iErrInvalidParams, "Invalid params: directory is not a valid socket address" );
+        }
+
+        response["result"] = "ok";
+    } );
+
+    /// @rpc_method jamulusclient/connect
+    /// @brief Disconnect client from server
+    /// @param {string} params.address - Server socket address (ip_addr:port).
+    /// @result {string} result - Always "ok".
+    pRpcServer->HandleMethod ( "jamulusclient/connect", [=] ( const QJsonObject& params, QJsonObject& response ) {
+        auto jsonAddr = params["address"];
+        if ( !jsonAddr.isString() )
+        {
+            response["error"] = CRpcServer::CreateJsonRpcError ( CRpcServer::iErrInvalidParams, "Invalid params: address is not a string" );
+            return;
+        }
+
+        if ( pClient->SetServerAddr ( jsonAddr.toString() ) )
+        {
+            if ( !pClient->IsRunning() )
+            {
+                pClient->Start();
+            }
+            response["result"] = "ok";
+        }
+        else
+        {
+            response["error"] = CRpcServer::CreateJsonRpcError ( 1, "Bad server address" );
+        }
+    } );
+
+    /// @rpc_method jamulusclient/disconnect
+    /// @brief Disconnect client from server
+    /// @param {object} params - No parameters (empty object).
+    /// @result {string} result - Always "ok".
+    pRpcServer->HandleMethod ( "jamulusclient/disconnect", [=] ( const QJsonObject& params, QJsonObject& response ) {
+        if ( pClient->IsRunning() )
+        {
+            pClient->Stop();
+        }
+
+        response["result"] = "ok";
+        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).
@@ -125,17 +239,17 @@ CClientRpc::CClientRpc ( CClient* pClient, CRpcServer* pRpcServer, QObject* pare
     /// @result {number} result.id - The channel ID.
     /// @result {string} result.name - The musician’s name.
     /// @result {string} result.skillLevel - The musician’s skill level (beginner, intermediate, expert, or null).
-    /// @result {number} result.countryId - The musician’s country ID (see QLocale::Country).
+    /// @result {string} result.country - The musician’s country.
     /// @result {string} result.city - The musician’s city.
-    /// @result {number} result.instrumentId - The musician’s instrument ID (see CInstPictures::GetTable).
+    /// @result {number} result.instrument - The musician’s instrument.
     /// @result {string} result.skillLevel - Your skill level (beginner, intermediate, expert, or null).
     pRpcServer->HandleMethod ( "jamulusclient/getChannelInfo", [=] ( const QJsonObject& params, QJsonObject& response ) {
         QJsonObject result{
             // TODO: We cannot include "id" here is pClient->ChannelInfo is a CChannelCoreInfo which lacks that field.
             { "name", pClient->ChannelInfo.strName },
-            { "countryId", pClient->ChannelInfo.eCountry },
+            { "country", QLocale::countryToString ( pClient->ChannelInfo.eCountry ) },
             { "city", pClient->ChannelInfo.strCity },
-            { "instrumentId", pClient->ChannelInfo.iInstrument },
+            { "instrument", CInstPictures::GetName ( pClient->ChannelInfo.iInstrument ) },
             { "skillLevel", SerializeSkillLevel ( pClient->ChannelInfo.eSkillLevel ) },
         };
         response["result"] = result;

Original file line number	Diff line number	Diff line change
`@@ -286,6 +286,8 @@ class CClient : public QObject`
`286`	`286`	`Channel.GetBufErrorRates ( vecErrRates, dLimit, dMaxUpLimit );`
`287`	`287`	`}`
`288`	`288`
	`289`	`+ CProtocol* getConnLessProtocol() { return &ConnLessProtocol; }`
	`290`	`+`
`289`	`291`	`// settings`
`290`	`292`	`CChannelCoreInfo ChannelInfo;`
`291`	`293`	`QString strClientName;`