From 179c0258f5da767ec24675606986a6c699d92c42 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 14 Mar 2025 11:52:05 +0100 Subject: [PATCH] curl_ws_recv.md: expand a little on the fragments the API delivers Closes #16720 --- docs/libcurl/curl_ws_recv.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/libcurl/curl_ws_recv.md b/docs/libcurl/curl_ws_recv.md index 2409335f0d..8c5cd55a4c 100644 --- a/docs/libcurl/curl_ws_recv.md +++ b/docs/libcurl/curl_ws_recv.md @@ -30,26 +30,26 @@ CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen, # DESCRIPTION -Retrieves as much as possible of a received WebSocket frame into the -*buffer*, but not more than *buflen* bytes. *recv* is set to the -number of bytes actually stored. +Retrieves as much as possible of a received WebSocket frame into the *buffer*, +but not more than *buflen* bytes. *recv* is set to the number of bytes +actually stored. If the function call is successful, the *meta* pointer gets set to point to a *const struct curl_ws_frame* that contains information about the received data. That struct must not be freed and its contents must not be relied upon -anymore once another WebSocket function is called. See curl_ws_meta(3) for more -details on that struct. +anymore once another WebSocket function is called. See curl_ws_meta(3) for +more details on that struct. The application must check `meta->bytesleft` to determine whether the complete frame has been received. If more payload is pending, the application must call this function again with an updated *buffer* and *buflen* to resume receiving. -This may for example happen when the data does not fit into the provided buffer -or when not all frame data has been delivered over the network yet. +This may for example happen when the data does not fit into the provided +buffer or when not all frame data has been delivered over the network yet. If the application wants to read the metadata without consuming any payload, it may call this function with a *buflen* of zero. Setting *buffer* to a NULL -pointer is permitted in this case. Note that frames without payload are consumed -by this action. +pointer is permitted in this case. Note that frames without payload are +consumed by this action. If the received message consists of multiple fragments, the *CURLWS_CONT* bit is set in all frames except the final one. The appropriate *CURLWS_TEXT* or @@ -60,6 +60,11 @@ to correctly handle control frames (i.e. CLOSE, PING and PONG) arriving in between consecutive fragments of a fragmented TEXT or BINARY message. See curl_ws_meta(3) for more details on *CURLWS_CONT*. +The WebSocket protocol consists of *messages* that can be delivered over the +wire as one or more *frames* - but since a frame can be too large to buffer in +memory, libcurl may need to deliver partial frames to the application. +Fragments, or chunks, of frames. + # %PROTOCOLS% # EXAMPLE