Hand pairing text, tokens and server information to consumers without copies

docs/conventions.md

@@ -185,9 +185,10 @@ checklists in `.claude/skills/` apply these standards to a diff.
   is bounded where it is parsed: read in place, refused past its cap, or cut to
   its field's size. Peer text a log line prints that no field bounds (a type, a
   reason, an unrecognized value) is cut to `PEER_TEXT_LOG_BYTES`
-  (`peer_text_for_log()`). Bounded text in a public type built for views
-  (`TrackMetadata`, `GroupState`) is a `std::string_view` into storage the
-  library keeps, valid for as long as its declaration says; a public type
+  (`peer_text_for_log()`). Bounded text in a public type or callback built
+  for views (`TrackMetadata`, `GroupState`, `ServerInformation`, the pairing
+  callbacks) is a `std::string_view` into storage the library keeps, valid
+  for as long as its declaration says; a public type
   still holding `std::string` or `std::vector` is built from the inline value
   on the thread that hands it to the consumer. `docs/internals.md` "Memory"
   lists the `operator new` allocations that remain after `start()`, and

examples/basic_client/main.cpp

@@ -436,35 +436,39 @@ int main(int argc, char* argv[]) {
             }
         }
 
-        void on_pairing_started(const std::string& server_id) override {
-            fprintf(stderr, ">>> Pairing started with server: %s\n", server_id.c_str());
+        void on_pairing_attempt(std::string_view server_id) override {
+            fprintf(stderr, ">>> Pairing started with server: %.*s\n",
+                    static_cast<int>(server_id.size()), server_id.data());
         }
 
-        void on_pairing_succeeded(const std::string& server_id) override {
-            fprintf(stderr, ">>> Pairing succeeded with server: %s\n", server_id.c_str());
+        void on_paired(std::string_view server_id) override {
+            fprintf(stderr, ">>> Pairing succeeded with server: %.*s\n",
+                    static_cast<int>(server_id.size()), server_id.data());
             fprintf(stderr, "    Long-term record stored. Future connections from this server\n");
             fprintf(stderr, "    will be paired sessions.\n");
         }
 
-        void on_pairing_failed(const std::string& server_id,
-                               SendspinPairAbortReason reason) override {
-            fprintf(stderr, ">>> Pairing failed with server: %s (reason %d)\n", server_id.c_str(),
-                    static_cast<int>(reason));
+        void on_pairing_aborted(std::string_view server_id,
+                                SendspinPairAbortReason reason) override {
+            fprintf(stderr, ">>> Pairing failed with server: %.*s (reason %d)\n",
+                    static_cast<int>(server_id.size()), server_id.data(), static_cast<int>(reason));
         }
 
-        void on_display_pairing_code(const std::string& code,
-                                     SendspinPairingCodeFormat format) override {
+        void on_pairing_code(std::string_view code, SendspinPairingCodeFormat format) override {
             if (format == SendspinPairingCodeFormat::QR_CODE) {
                 // This example never offers qr_code (a terminal cannot render one), so a server
                 // can only select digits.
-                fprintf(stderr, "\n>>> Pairing token: %s\n", code.c_str());
+                fprintf(stderr, "\n>>> Pairing token: %.*s\n", static_cast<int>(code.size()),
+                        code.data());
                 fprintf(stderr, "    Scan or paste this into the server to finish pairing.\n\n");
                 return;
             }
             // pairing.md "Pairing Code Presentation" asks for a 3-3 grouping; the separator is
             // presentation only and never part of the code the operator types.
-            fprintf(stderr, "\n>>> Pairing code: %s-%s\n", code.substr(0, 3).c_str(),
-                    code.substr(3).c_str());
+            const std::string_view first = code.substr(0, 3);
+            const std::string_view second = code.substr(3);
+            fprintf(stderr, "\n>>> Pairing code: %.*s-%.*s\n", static_cast<int>(first.size()),
+                    first.data(), static_cast<int>(second.size()), second.data());
             fprintf(stderr, "    Enter this code on the server to finish pairing.\n\n");
         }
 
@@ -528,9 +532,9 @@ int main(int argc, char* argv[]) {
     // The pairing token carries the client_id and the Pairing PSK together. Paste it into a
     // server that asks for one to pair via the pairing_psk method; pairing with a code instead
     // needs nothing from here (the code is printed when the server starts that flow).
-    auto token = client.pairing_token();
+    const auto token = client.client_pairing_token();
     if (token.has_value()) {
-        fprintf(stderr, "Pairing token: %s\n", token->c_str());
+        fprintf(stderr, "Pairing token: %.*s\n", static_cast<int>(token->size()), token->data());
     }
 
 #ifdef SENDSPIN_HAS_MDNS

examples/source_client/main.cpp

@@ -65,6 +65,7 @@
 #include <cstring>
 #include <optional>
 #include <string>
+#include <string_view>
 #include <thread>
 #include <utility>
 
@@ -545,26 +546,29 @@ int main(int argc, char* argv[]) {
             fprintf(stderr, ">>> High-performance networking released\n");
         }
 
-        void on_pairing_started(const std::string& server_id) override {
-            fprintf(stderr, ">>> Pairing started with server: %s\n", server_id.c_str());
+        void on_pairing_attempt(std::string_view server_id) override {
+            fprintf(stderr, ">>> Pairing started with server: %.*s\n",
+                    static_cast<int>(server_id.size()), server_id.data());
         }
 
-        void on_pairing_succeeded(const std::string& server_id) override {
-            fprintf(stderr, ">>> Pairing succeeded with server: %s\n", server_id.c_str());
+        void on_paired(std::string_view server_id) override {
+            fprintf(stderr, ">>> Pairing succeeded with server: %.*s\n",
+                    static_cast<int>(server_id.size()), server_id.data());
         }
 
-        void on_pairing_failed(const std::string& server_id,
-                               SendspinPairAbortReason reason) override {
-            fprintf(stderr, ">>> Pairing failed with server: %s (reason %d)\n", server_id.c_str(),
-                    static_cast<int>(reason));
+        void on_pairing_aborted(std::string_view server_id,
+                                SendspinPairAbortReason reason) override {
+            fprintf(stderr, ">>> Pairing failed with server: %.*s (reason %d)\n",
+                    static_cast<int>(server_id.size()), server_id.data(), static_cast<int>(reason));
         }
 
-        void on_display_pairing_code(const std::string& code,
-                                     SendspinPairingCodeFormat /*format*/) override {
+        void on_pairing_code(std::string_view code, SendspinPairingCodeFormat /*format*/) override {
             // Only digits are offered. pairing.md "Pairing Code Presentation" asks for a 3-3
             // grouping; the separator is presentation only and never part of the code.
-            fprintf(stderr, "\n>>> Pairing code: %s-%s\n", code.substr(0, 3).c_str(),
-                    code.substr(3).c_str());
+            const std::string_view first = code.substr(0, 3);
+            const std::string_view second = code.substr(3);
+            fprintf(stderr, "\n>>> Pairing code: %.*s-%.*s\n", static_cast<int>(first.size()),
+                    first.data(), static_cast<int>(second.size()), second.data());
             fprintf(stderr, "    Enter this code on the server to finish pairing.\n\n");
         }
 
@@ -602,9 +606,9 @@ int main(int argc, char* argv[]) {
     // The pairing token carries the client_id and the Pairing PSK together. Paste it into a
     // server that asks for one to pair via the pairing_psk method; pairing with a code instead
     // needs nothing from here (the code is printed when the server starts that flow).
-    auto token = client.pairing_token();
+    const auto token = client.client_pairing_token();
     if (token.has_value()) {
-        fprintf(stderr, "Pairing token: %s\n", token->c_str());
+        fprintf(stderr, "Pairing token: %.*s\n", static_cast<int>(token->size()), token->data());
     }
 
 #ifdef SENDSPIN_HAS_MDNS

examples/tui_client/main.cpp

@@ -81,6 +81,7 @@
 #include <optional>
 #include <sstream>
 #include <string>
+#include <string_view>
 #include <thread>
 #include <utility>
 #include <vector>
@@ -768,31 +769,31 @@ int main(int argc, char* argv[]) {
             }
         }
 
-        void on_pairing_started(const std::string& /*server_id*/) override {
+        void on_pairing_attempt(std::string_view /*server_id*/) override {
             std::lock_guard<std::mutex> lock(state.mutex);
             state.pairing_status = "Pairing...";
         }
 
-        void on_pairing_succeeded(const std::string& /*server_id*/) override {
+        void on_paired(std::string_view /*server_id*/) override {
             std::lock_guard<std::mutex> lock(state.mutex);
             state.pairing_status = "Paired";
         }
 
-        void on_pairing_failed(const std::string& /*server_id*/,
-                               SendspinPairAbortReason /*reason*/) override {
+        void on_pairing_aborted(std::string_view /*server_id*/,
+                                SendspinPairAbortReason /*reason*/) override {
             std::lock_guard<std::mutex> lock(state.mutex);
             state.pairing_status = "Pairing failed";
         }
 
-        void on_display_pairing_code(const std::string& code,
-                                     SendspinPairingCodeFormat format) override {
+        void on_pairing_code(std::string_view code, SendspinPairingCodeFormat format) override {
             std::lock_guard<std::mutex> lock(state.mutex);
             // Only digits are offered above, so a code that arrives is six digits; pairing.md
             // "Pairing Code Presentation" asks for the 3-3 grouping shown here, which is
             // presentation only and never part of what the operator types.
-            state.pairing_status = format == SendspinPairingCodeFormat::DIGITS
-                                       ? "Code " + code.substr(0, 3) + "-" + code.substr(3)
-                                       : "Token " + code;
+            state.pairing_status =
+                format == SendspinPairingCodeFormat::DIGITS
+                    ? "Code " + std::string(code.substr(0, 3)) + "-" + std::string(code.substr(3))
+                    : "Token " + std::string(code);
         }
 
         void on_clear_pairing_code() override {
@@ -1004,9 +1005,9 @@ int main(int argc, char* argv[]) {
     {
         std::lock_guard<std::mutex> lock(state.mutex);
         state.client_id = client.client_id();
-        auto token = client.pairing_token();
+        const auto token = client.client_pairing_token();
         if (token.has_value()) {
-            state.pairing_token = std::move(*token);
+            state.pairing_token.assign(token->data(), token->size());
         }
     }