romenskiy2012/curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-07-10 05:37:15 +03:00
Code Issues Projects Releases Packages Wiki Activity

curl_ws_meta.md: polish and better vocabulary

Browse source 
Assisted-by: Hendrik Hübner
Closes #22233
This commit is contained in:
Daniel Stenberg 2026-07-01 09:50:34 +02:00
parent adf843fbbd
commit 5bf1ce64f5
No known key found for this signature in database
GPG key ID: 5CC908FDB71E12C2
1 changed files with 22 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

34
docs/libcurl/curl_ws_meta.md
View file

@ -29,9 +29,9 @@ const struct curl_ws_frame *curl_ws_meta(CURL *curl);
# DESCRIPTION
When the write callback (CURLOPT_WRITEFUNCTION(3)) is invoked on
received WebSocket traffic, curl_ws_meta(3) can be called from within
the callback to provide additional information about the current frame.
When the write callback (CURLOPT_WRITEFUNCTION(3)) is invoked on received
WebSocket traffic, curl_ws_meta(3) can be called from within the callback to
provide additional information about the current frame.
This function only works from within the callback, and only when receiving
WebSocket data.
@ -41,6 +41,14 @@ what transfer the question is about, but as there is no such pointer provided
to the callback by libcurl itself, applications that want to use
curl_ws_meta(3) need to pass it on to the callback on its own.
WebSocket messages are split into *frames*. A WebSocket message can be made up
of an arbitrary number of frames. Each WebSocket frame payload can be up to
2^63-1 bytes. When libcurl delivers WebSocket data, it splits each frame into
*chunks*; each chunk is therefore part of a frame, or at most a full frame.
Each callback delivers data for a single chunk that is then part of a single
frame.
# struct curl_ws_frame
~~~c
@ -64,13 +72,15 @@ See the list below.
## `offset`
When this chunk is a continuation of frame data already delivered, this is
the offset into the final frame data where this piece belongs to.
When this chunk is a continuation of frame data already delivered in a
previous callback, this is the offset into the complete frame payload where
this chunk's data belongs.
## `bytesleft`
If this is not a complete fragment, the *bytesleft* field informs about how
many additional bytes are expected to arrive before this fragment is complete.
When this is not a complete frame nor the last chunk for a frame, the
*bytesleft* field informs about how many additional bytes are expected to
arrive before this frame is complete.
## `len`
@ -118,12 +128,12 @@ libcurl does not verify that the payload is valid UTF-8.
Can only occur in conjunction with CURLWS_TEXT or CURLWS_BINARY.
This is not the final fragment of the message, it implies that there is
another fragment coming as part of the same message. The application must
reassemble the fragments to receive the complete message.
This is not the final *frame* of the message, it implies that there is another
*frame* coming as part of the same message. The application must reassemble
the frames to receive the complete message.
Only a single fragmented message can be transmitted at a time, but it may
be interrupted by CURLWS_CLOSE, CURLWS_PING or CURLWS_PONG frames.
Only a single multi-frame message can be transmitted at a time, but it may be
interrupted by CURLWS_CLOSE, CURLWS_PING or CURLWS_PONG frames.
# %PROTOCOLS%