libvncclient: rework utf-8 clipboard API to resemble libvncserver one

Public LibVNCServer API has

* `rfbSendServerCutTextUTF8(rfbScreenInfoPtr rfbScreen,char *str, int len, char *fallbackLatin1Str, int latin1Len);`
* and `typedef void (*rfbSetXCutTextUTF8ProcPtr) (char* str,int len, struct _rfbClientRec* cl);` which is wired up
  as `setXCutTextUTF8`,

i.e. it's got a unicode sender w/ Latin1 fallback and a dedicated
unicode receiver.

This commit reworks the libvncclient API to have a dedicated UTF8
clipboard sending function and a dedicated on-receive callback.

Applications can use those functions instead of changing state with
some rfbClient member.

Author: bk138

libvncclient/rfbproto.c

@@ -1448,9 +1448,8 @@ SetFormatAndEncodings(rfbClient* client)
 
 #ifdef LIBVNCSERVER_HAVE_LIBZ
   /* extendedclipboard */
-  if (client->clipboardCap)
-    if (se->nEncodings < MAX_ENCODINGS)
-      encs[se->nEncodings++] = rfbClientSwap32IfLE(rfbEncodingExtendedClipboard);
+  if (se->nEncodings < MAX_ENCODINGS)
+    encs[se->nEncodings++] = rfbClientSwap32IfLE(rfbEncodingExtendedClipboard);
 #endif
 
   /* client extensions */
@@ -1778,7 +1777,7 @@ SendExtendedKeyEvent(rfbClient* client, uint32_t keysym, uint32_t keycode, rfbBo
 
 #ifdef LIBVNCSERVER_HAVE_LIBZ
 /*
- * sendClientCutTextNotify
+ * sendExtClientCutTextNotify
  * it is needed when client send utf8 clipboard data
  * please refer to
  * https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#extended-clipboard-pseudo-encoding
@@ -1800,7 +1799,7 @@ sendExtClientCutTextNotify(rfbClient *client)
 
 
 /*
- * sendClientCutTextProvide
+ * sendExtClientCutTextProvide
  * it need send notify first to grab clipboard (server will check that)
  */
 
@@ -1859,19 +1858,23 @@ SendClientCutText(rfbClient* client, char *str, int len)
 
   if (!SupportsClient2Server(client, rfbClientCutText)) return TRUE;
 
-#ifdef LIBVNCSERVER_HAVE_LIBZ
-  if (client->clipboardEnabledCap) { /* if enabled extended clipboard, use it */
-    return sendExtClientCutTextProvide(client, str, len);
-  }
-#endif
-
   memset(&cct, 0, sizeof(cct));
   cct.type = rfbClientCutText;
   cct.length = rfbClientSwap32IfLE(len);
   return  (WriteToRFBServer(client, (char *)&cct, sz_rfbClientCutTextMsg) &&
 	   WriteToRFBServer(client, str, len));
 }
 
+rfbBool
+SendClientCutTextUTF8(rfbClient* client, char *str, int len)
+{
+#ifdef LIBVNCSERVER_HAVE_LIBZ
+    return client->extendedClipboardServerCapabilities && sendExtClientCutTextProvide(client, str, len);
+#else
+    return FALSE;
+#endif
+}
+
 
 #ifdef LIBVNCSERVER_HAVE_LIBZ
 /*
@@ -1905,7 +1908,7 @@ rfbClientProcessExtServerCutText(rfbClient* client, char *data, int len)
   }
   if (flags & rfbExtendedClipboard_Caps) {
     rfbClientLog("rfbClientProcessExtServerCutText. default cap.\n");
-    client->clipboardEnabledCap |= rfbExtendedClipboard_Text; /* for now, only text */
+    client->extendedClipboardServerCapabilities |= rfbExtendedClipboard_Text; /* for now, only text */
     return TRUE;
   }
 
@@ -1959,8 +1962,8 @@ rfbClientProcessExtServerCutText(rfbClient* client, char *data, int len)
     inflateEnd(&stream);
     return FALSE;
   }
-  if (client->GotXCutText)
-    client->GotXCutText(client, (char *)buf, size);
+  if (client->GotXCutTextUTF8)
+    client->GotXCutTextUTF8(client, buf, size);
   free(buf);
 
   inflateEnd(&stream);
@@ -2514,7 +2517,6 @@ HandleRFBServerMessage(rfbClient* client)
     char *buffer;
 #ifdef LIBVNCSERVER_HAVE_LIBZ
     int32_t ilen; /* also as a flag, if ilen < 0, it is ext clipboard text */
-    rfbBool fallback = FALSE;
 #endif
 
     if (!ReadFromRFBServer(client, ((char *)&msg) + 1,
@@ -2523,16 +2525,6 @@ HandleRFBServerMessage(rfbClient* client)
 
 #ifdef LIBVNCSERVER_HAVE_LIBZ
     ilen = rfbClientSwap32IfLE(msg.sct.length);
-    if (client->clipboardEnabledCap && ilen >= 0) {
-      if (!client->GotXCutTextFallback) {
-        rfbClientLog("extend clipboardCap enabled but msg len:%d >= 0. no fallback callback. ignore\n", ilen);
-        return FALSE;
-      } else {
-        rfbClientLog("extend clipboardCap enabled but msg len:%d >= 0. fallback\n", ilen);
-        fallback = TRUE;
-      }
-    }
-
     msg.sct.length = ilen < 0 ? -ilen : ilen;
 #else
     msg.sct.length = rfbClientSwap32IfLE(msg.sct.length);
@@ -2553,9 +2545,7 @@ HandleRFBServerMessage(rfbClient* client)
     buffer[msg.sct.length] = 0;
 
 #ifdef LIBVNCSERVER_HAVE_LIBZ
-    if (fallback) {
-      client->GotXCutTextFallback(client, buffer, msg.sct.length);
-    } else if (ilen < 0) {
+    if (ilen < 0 && client->GotXCutTextUTF8) {
       if (!rfbClientProcessExtServerCutText(client, buffer, -ilen)) {
         free(buffer);
         return FALSE;

rfb/rfbclient.h

@@ -217,6 +217,7 @@ typedef char* (*GetPasswordProc)(struct _rfbClient* client);
 typedef rfbCredential* (*GetCredentialProc)(struct _rfbClient* client, int credentialType);
 typedef rfbBool (*MallocFrameBufferProc)(struct _rfbClient* client);
 typedef void (*GotXCutTextProc)(struct _rfbClient* client, const char *text, int textlen);
+typedef void (*GotXCutTextUTF8Proc)(struct _rfbClient* client, const char* buffer, int buffer_len);
 typedef void (*BellProc)(struct _rfbClient* client);
 /**
     Called when a cursor shape update was received from the server. The decoded cursor shape
@@ -479,17 +480,12 @@ typedef struct _rfbClient {
 	rfbExtDesktopScreen screen;
 
 #ifdef LIBVNCSERVER_HAVE_LIBZ
-	uint32_t clipboardCap; /**extended clipboard pseudo-encoding cap */
-	                       /**it is bitset as rfb3.8, current only support text */
-	                       /**client set it to rfbExtendedClipboard_Text for now */
-	uint32_t clipboardEnabledCap; /**enabled cap which confirmed by server */
-	                              /**client can use it as a check for server cap */
-	/**
-	 * Used for extended clipboard text fallback
-	 * When server announce cap of utf8, but still send latin-1
-	 */
-	GotXCutTextProc GotXCutTextFallback;
+        uint32_t extendedClipboardServerCapabilities;
 #endif
+        /**
+	 * Callback fired when "Extended Clipboard" UTF-8 text data is received.
+	 */
+        GotXCutTextUTF8Proc GotXCutTextUTF8;
 } rfbClient;
 
 /* cursor.c */
@@ -609,18 +605,33 @@ extern rfbBool SendKeyEvent(rfbClient* client,uint32_t key, rfbBool down);
  */
 extern rfbBool SendExtendedKeyEvent(rfbClient* client, uint32_t keysym, uint32_t keycode, rfbBool down);
 /**
- * Places a string on the server's clipboard. Use this function if you want to
+ * Places a Latin-1-encoded string on the server's clipboard. Use this function if you want to
  * be able to copy and paste between the server and your application. For
  * instance, when your application is notified that the user copied some text
  * onto the clipboard, you would call this function to synchronize the server's
  * clipboard with your local clipboard.
  * @param client The client structure through which to send the client cut text
  * message
- * @param str The string to send (doesn't need to be NULL terminated)
+ * @param str The string to send (needs to be Latin-1-encoded, doesn't need to be NULL terminated)
  * @param len The length of the string
  * @return true if the client cut message was sent successfully, false otherwise
  */
 extern rfbBool SendClientCutText(rfbClient* client,char *str, int len);
+/**
+ * Places a UTF-8-encoded string on the server's clipboard if the server supports it.
+ * Use this function if you want to be able to copy and paste between the server and your application. For
+ * instance, when your application is notified that the user copied some text
+ * onto the clipboard, you would call this function to synchronize the server's
+ * clipboard with your local clipboard. This is the more modern equivalent of
+ * SendClientCutText().
+ * @param client The client structure through which to send the client cut text
+ * message
+ * @param str The string to send (needs to be UTF-8-encoded, doesn't need to be NULL terminated)
+ * @param len The length of the string in bytes
+ * @return true if the message was sent successfully, false otherwise - you might want to
+ * fall back to SendClientCutText() in this case.
+ */
+extern rfbBool SendClientCutTextUTF8(rfbClient* client, char *str, int len);
 /**
  * Handles messages from the RFB server. You must call this function
  * intermittently so LibVNCClient can parse messages from the server. For