added a new README and fix the comments

Author: xianshijing-lk

README.md

@@ -71,7 +71,7 @@ The SimpleRpc example demonstrates how to:
 - Observe round-trip times (RTT) for each RPC call
 
 #### 🔑 Generate Tokens
-Before running any participant, create JWT tokens with "caller", "greeter" and "math-genius" identities and room name.
+Before running any participant, create JWT tokens with **caller**, **greeter** and **math-genius** identities and room name.
 ```bash
 lk token create -r test -i caller --join --valid-for 99999h --dev --room=your_own_room
 lk token create -r test -i greeter --join --valid-for 99999h --dev --room=your_own_room

examples/simple_rpc/README

@@ -0,0 +1,157 @@
+# 📘 SimpleRpc Example — Technical Overview
+
+This README provides deeper technical details about the RPC (Remote Procedure Call) support demonstrated in the SimpleRpc example.
+It complements the example instructions found in the root README.md.
+
+If you're looking for how to run the example, see the root [README](https://github.com/livekit/client-sdk-cpp).
+
+This document explains:
+- How LiveKit RPC works in the C++ SDK
+- Where the APIs are defined
+- How senders call RPC methods
+- How receivers register handlers
+- What happens if the receiver is absent
+- How long-running operations behave
+- Timeouts, disconnects, and unsupported methods
+- RPC lifecycle events and error propagation
+
+## 🔧 Overview: How RPC Works
+LiveKit RPC allows one participant (the caller) to invoke a method on another participant (the receiver) using the data channel transport.
+It is:
+- Peer-to-peer within the room (not server-executed RPC)
+- Request/response (caller waits for a reply or an error)
+- Asynchronous under the hood, synchronous or blocking from the caller’s perspective
+- Delivery-guaranteed when using the reliable data channel
+
+Each RPC call includes:
+| Field                    | Meaning                                             |
+|--------------------------|-----------------------------------------------------|
+| **destination_identity** | Identity of the target participant                  |
+| **method**               | Method name string (e.g., "square-root")            |
+| **payload**              | Arbitrary UTF-8 text                                |
+| **response_timeout**     | Optional timeout (seconds)                          |
+| **invocation_id**        | Server-generated ID used internally for correlation |
+
+##  📍 Location of APIs in C++
+All public-facing RPC APIs live in:
+[include/livekit/local_participant.h](https://github.com/livekit/client-sdk-cpp/blob/main/include/livekit/local_participant.h#L124)
+
+### Key methods:
+
+#### Sender-side APIs
+```bash
+std::string performRpc(
+    const std::string& destination_identity,
+    const std::string& method,
+    const std::string& payload,
+    std::optional<double> response_timeout_sec = std::nullopt
+);
+
+Receiver-side APIs
+void registerRpcMethod(
+    const std::string& method_name,
+    RpcHandler handler
+);
+
+void unregisterRpcMethod(const std::string& method_name);
+
+Handler signature
+using RpcHandler =
+  std::function<std::optional<std::string>(const RpcInvocationData&)>;
+```
+
+Handlers can:
+- Return a string (the RPC response payload)
+- Return std::nullopt (meaning “no return payload”)
+- Throw exceptions (mapped to APPLICATION_ERROR)
+- Throw a RpcError (mapped to specific error codes)
+
+#### 🛰 Sender Behavior (performRpc)
+
+When the caller invokes:
+```bash
+auto reply = lp->performRpc("math-genius", "square-root", "{\"number\":16}");
+```
+
+The following occurs:
+
+A PerformRpcRequest is sent through FFI to the SDK core.
+
+The SDK transmits the invocation to the target participant (if present).
+
+The caller begins waiting for a matching RpcMethodInvocationResponse.
+
+One of the following happens:
+| Outcome                  | Meaning                                  |
+|--------------------------|------------------------------------------|
+| **Success**              | Receiver returned a payload              |
+| **UNSUPPORTED_METHOD**   | Receiver did not register the method     |
+| **RECIPIENT_NOT_FOUND**  | Target identity not present in room      |
+| **RECIPIENT_DISCONNECTED** | Target left before replying            |
+| **RESPONSE_TIMEOUT**     | Receiver took too long                   |
+| **APPLICATION_ERROR**    | Handler threw an exception               |
+
+#### 🔄 Round-trip time (RTT)
+
+The caller can measure RTT externally (as SimpleRpc does), but the SDK does not measure RTT internally.
+
+#### 📡 Receiver Behavior (registerRpcMethod)
+
+A receiver must explicitly register handlers:
+```bash
+local_participant->registerRpcMethod("square-root",
+  [](const RpcInvocationData& data) {
+      double number = parse(data.payload);
+      return make_json("result", std::sqrt(number));
+  });
+```
+
+When an invocation arrives:
+- Room receives a RpcMethodInvocationEvent
+- Room forwards it to the corresponding LocalParticipant
+- LocalParticipant::handleRpcMethodInvocation():
+- Calls the handler
+- Converts any exceptions into RpcError
+- Sends back RpcMethodInvocationResponse
+
+⚠ If no handler exists:
+
+Receiver returns: UNSUPPORTED_METHOD
+
+
+#### 🚨 What Happens if Receiver Is Absent?
+| Case                                                | Behavior                                          |
+|-----------------------------------------------------|---------------------------------------------------|
+| Receiver identity is not in the room                | Caller immediately receives `RECIPIENT_NOT_FOUND` |
+| Receiver is present but disconnects before replying | Caller receives `RECIPIENT_DISCONNECTED`          |
+| Receiver joins later                                | Caller must retry manually (no automatic waiting) |
+
+**Important**:
+LiveKit does not queue RPC calls for offline participants.
+
+#### ⏳ Timeout Behavior
+
+If the caller specifies:
+
+performRpc(..., /*response_timeout=*/10.0); 
+
+Then:
+- Receiver is given 10 seconds to respond.
+- If the receiver handler takes longer (e.g., sleep 30s), caller receives:
+RESPONSE_TIMEOUT
+
+**If no response_timeout is provided explicitly, the default timeout is 15 seconds.**
+
+
+This is by design and demonstrated in the example.
+
+####  🧨 Errors & Failure Modes
+| Error Code             | Cause                                      |
+|------------------------|---------------------------------------------|
+| **APPLICATION_ERROR**  | Handler threw a C++ exception               |
+| **UNSUPPORTED_METHOD** | No handler registered for the method        |
+| **RECIPIENT_NOT_FOUND** | Destination identity not in room          |
+| **RECIPIENT_DISCONNECTED** | Participant left mid-flight            |
+| **RESPONSE_TIMEOUT**   | Handler exceeded allowed response time      |
+| **CONNECTION_TIMEOUT** | Transport-level issue                       |
+| **SEND_FAILED**        | SDK failed to send invocation               |

examples/simple_rpc/main.cpp

@@ -32,17 +32,13 @@
 #include <vector>
 
 #include "livekit/livekit.h"
-#include "livekit_ffi.h" // same as simple_room; internal but used here
+#include "livekit_ffi.h"
 
 using namespace livekit;
 using namespace std::chrono_literals;
 
 namespace {
 
-// ------------------------------------------------------------
-// Global control (same pattern as simple_room)
-// ------------------------------------------------------------
-
 std::atomic<bool> g_running{true};
 
 void handleSignal(int) { g_running.store(false); }
@@ -91,38 +87,31 @@ bool ensurePeerPresent(Room &room, const std::string &identity,
   std::cout << "[Caller] Waiting up to " << timeout.count() << "s for "
             << friendly_role << " (identity=\"" << identity
             << "\") to join...\n";
-
   bool present = waitForParticipant(
       room, identity,
       std::chrono::duration_cast<std::chrono::milliseconds>(timeout));
-
   if (present) {
     std::cout << "[Caller] " << friendly_role << " is present.\n";
     return true;
   }
-
   // Timed out
   auto info = room.room_info();
   const std::string room_name = info.name;
-
   std::cout << "[Caller] Timed out after " << timeout.count()
             << "s waiting for " << friendly_role << " (identity=\"" << identity
             << "\").\n";
   std::cout << "[Caller] No participant with identity \"" << identity
             << "\" appears to be connected to room \"" << room_name
             << "\".\n\n";
-
   std::cout << "To start a " << friendly_role
             << " in another terminal, run:\n\n"
             << "  lk token create -r test -i " << identity
             << " --join --valid-for 99999h --dev --room=" << room_name << "\n"
             << "  ./build/examples/SimpleRpc " << url
             << " $token --role=" << friendly_role << "\n\n";
-
   return false;
 }
 
-// Parse args similar to simple_room, plus optional --role / role positional
 bool parseArgs(int argc, char *argv[], std::string &url, std::string &token,
                std::string &role) {
   // --help
@@ -206,26 +195,18 @@ bool parseArgs(int argc, char *argv[], std::string &url, std::string &token,
   return !(url.empty() || token.empty());
 }
 
-// ------------------------------------------------------------
-// Tiny helpers for the simple JSON used in the sample
-// (to avoid bringing in a json library)
-// ------------------------------------------------------------
-
-// create {"key":number}
 std::string makeNumberJson(const std::string &key, double value) {
   std::ostringstream oss;
   oss << "{\"" << key << "\":" << value << "}";
   return oss.str();
 }
 
-// create {"key":"value"}
 std::string makeStringJson(const std::string &key, const std::string &value) {
   std::ostringstream oss;
   oss << "{\"" << key << "\":\"" << value << "\"}";
   return oss.str();
 }
 
-// very naive parse of {"key":number}
 double parseNumberFromJson(const std::string &json) {
   auto colon = json.find(':');
   if (colon == std::string::npos)
@@ -236,7 +217,6 @@ double parseNumberFromJson(const std::string &json) {
   return std::stod(num_str);
 }
 
-// very naive parse of {"key":"value"}
 std::string parseStringFromJson(const std::string &json) {
   auto colon = json.find(':');
   if (colon == std::string::npos)
@@ -250,10 +230,7 @@ std::string parseStringFromJson(const std::string &json) {
   return json.substr(first_quote + 1, second_quote - first_quote - 1);
 }
 
-// ------------------------------------------------------------
-// RPC handler registration (for greeter & math-genius)
-// ------------------------------------------------------------
-
+// RPC handler registration
 void registerReceiverMethods(Room &greeters_room, Room &math_genius_room) {
   LocalParticipant *greeter_lp = greeters_room.local_participant();
   LocalParticipant *math_genius_lp = math_genius_room.local_participant();
@@ -321,19 +298,15 @@ void registerReceiverMethods(Room &greeters_room, Room &math_genius_room) {
         std::cout << "[Math Genius] This will take 30 seconds even though "
                      "you're only giving me "
                   << data.response_timeout_sec << " seconds\n";
-
+        // Sleep for 30 seconds to mimic a long running task.
         std::this_thread::sleep_for(30s);
         return makeStringJson("result", "Calculation complete!");
       });
 
   // Note: we do NOT register "quantum-hypergeometric-series" here,
-  // so the caller sees UNSUPPORTED_METHOD, just like in Python.
+  // so the caller sees UNSUPPORTED_METHOD
 }
 
-// ------------------------------------------------------------
-// Caller-side helpers (like perform_* in rpc.py)
-// ------------------------------------------------------------
-
 void performGreeting(Room &room) {
   std::cout << "[Caller] Letting the greeter know that I've arrived\n";
   double t0 = nowMs();
@@ -460,10 +433,6 @@ void performLongCalculation(Room &room) {
 
 } // namespace
 
-// ------------------------------------------------------------
-// main – similar style to simple_room/main.cpp
-// ------------------------------------------------------------
-
 int main(int argc, char *argv[]) {
   std::string url, token, role;
   if (!parseArgs(argc, argv, url, token, role)) {
@@ -479,7 +448,7 @@ int main(int argc, char *argv[]) {
   std::cout << "Connecting to: " << url << "\n";
   std::cout << "Role: " << role << "\n";
 
-  // Ctrl-C
+  // Ctrl-C to quit the program
   std::signal(SIGINT, handleSignal);
 
   Room room{};