websockets: remodeled API to support 63 bit frame sizes

curl_ws_recv() now receives data to fill up the provided buffer, but can
return a partial fragment. The function now also get a pointer to a
curl_ws_frame struct with metadata that also mentions the offset and
total size of the fragment (of which you might be receiving a smaller
piece). This way, large incoming fragments will be "streamed" to the
application. When the curl_ws_frame struct field 'bytesleft' is 0, the
final fragment piece has been delivered.

curl_ws_recv() was also adjusted to work with a buffer size smaller than
the fragment size. (Possibly needless to say as the fragment size can
now be 63 bit large).

curl_ws_send() now supports sending a piece of a fragment, in a
streaming manner, in addition to sending the entire fragment in a single
call if it is small enough. To send a huge fragment, curl_ws_send() can
be used to send it in many small calls by first telling libcurl about
the total expected fragment size, and then send the payload in N number
of separate invokes and libcurl will stream those over the wire.

The struct curl_ws_meta() returns is now called 'curl_ws_frame' and it
has been extended with two new fields: *offset* and *bytesleft*. To help
describe the passed on data chunk when a fragment is delivered in many
smaller pieces.

The documentation has been updated accordingly.

Closes #9636

1 files changed, 13 insertions, 9 deletions

diff --git a/include/curl/websockets.h b/include/curl/websockets.h
index e128526f4..4d57f91e5 100644
--- a/include/curl/websockets.h
+++ b/include/curl/websockets.h
@@ -28,12 +28,20 @@
 extern "C" {
 #endif
 
-/* generic in/out flag bits */
+struct curl_ws_frame {
+  int age;              /* zero */
+  int flags;            /* See the CURLWS_* defines */
+  curl_off_t offset;    /* the offset of this data into the frame */
+  curl_off_t bytesleft; /* number of pending bytes left of the payload */
+};
+
+/* flag bits */
 #define CURLWS_TEXT       (1<<0)
 #define CURLWS_BINARY     (1<<1)
 #define CURLWS_CONT       (1<<2)
 #define CURLWS_CLOSE      (1<<3)
 #define CURLWS_PING       (1<<4)
+#define CURLWS_OFFSET     (1<<5)
 
 /*
  * NAME curl_ws_recv()
@@ -44,10 +52,10 @@ extern "C" {
  * curl_easy_perform() with CURLOPT_CONNECT_ONLY option.
  */
 CURL_EXTERN CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen,
-                                  size_t *recv, unsigned int *recvflags);
+                                  size_t *recv,
+                                  struct curl_ws_frame **metap);
 
 /* sendflags for curl_ws_send() */
-#define CURLWS_NOCOMPRESS (1<<5)
 #define CURLWS_PONG       (1<<6)
 
 /*
@@ -60,17 +68,13 @@ CURL_EXTERN CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen,
  */
 CURL_EXTERN CURLcode curl_ws_send(CURL *curl, const void *buffer,
                                   size_t buflen, size_t *sent,
+                                  curl_off_t framesize,
                                   unsigned int sendflags);
 
 /* bits for the CURLOPT_WS_OPTIONS bitmask: */
 #define CURLWS_RAW_MODE (1<<0)
 
-struct curl_ws_metadata {
-  int age;       /* zero */
-  int recvflags; /* See the CURLWS_* defines */
-};
-
-CURL_EXTERN struct curl_ws_metadata *curl_ws_meta(CURL *curl);
+CURL_EXTERN struct curl_ws_frame *curl_ws_meta(CURL *curl);
 
 #ifdef  __cplusplus
 }