115 lines
4.4 KiB
Groff
115 lines
4.4 KiB
Groff
.\" generated by cd2nroff 0.1 from curl_ws_recv.md
|
|
.TH curl_ws_recv 3 "2025-07-07" libcurl
|
|
.SH NAME
|
|
curl_ws_recv \- receive WebSocket data
|
|
.SH SYNOPSIS
|
|
.nf
|
|
#include <curl/curl.h>
|
|
|
|
CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen,
|
|
size_t *recv, const struct curl_ws_frame **meta);
|
|
.fi
|
|
.SH DESCRIPTION
|
|
Retrieves as much as possible of a received WebSocket frame into the \fIbuffer\fP,
|
|
but not more than \fIbuflen\fP bytes. \fIrecv\fP is set to the number of bytes
|
|
actually stored.
|
|
|
|
If the function call is successful, the \fImeta\fP pointer gets set to point to a
|
|
\fIconst struct curl_ws_frame\fP 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 \fIcurl_ws_meta(3)\fP for
|
|
more details on that struct.
|
|
|
|
The application must check \fImeta\->bytesleft\fP to determine whether the complete
|
|
frame has been received. If more payload is pending, the application must call
|
|
this function again with an updated \fIbuffer\fP and \fIbuflen\fP 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.
|
|
|
|
If the application wants to read the metadata without consuming any payload,
|
|
it may call this function with a \fIbuflen\fP of zero. Setting \fIbuffer\fP to a NULL
|
|
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 \fICURLWS_CONT\fP bit
|
|
is set in all frames except the final one. The appropriate \fICURLWS_TEXT\fP or
|
|
\fICURLWS_BINARY\fP flag is set in every frame, regardless whether it is the first
|
|
fragment, an intermediate fragment or the final fragment. The application is
|
|
responsible for reassembling fragmented messages. Special care must be taken
|
|
to correctly handle control frames (i.e. CLOSE, PING and PONG) arriving in
|
|
between consecutive fragments of a fragmented TEXT or BINARY message. See
|
|
\fIcurl_ws_meta(3)\fP for more details on \fICURLWS_CONT\fP.
|
|
|
|
The WebSocket protocol consists of \fImessages\fP that can be delivered over the
|
|
wire as one or more \fIframes\fP \- 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.
|
|
.SH PROTOCOLS
|
|
This functionality affects ws only
|
|
.SH EXAMPLE
|
|
.nf
|
|
int main(void)
|
|
{
|
|
char buffer[256];
|
|
size_t offset = 0;
|
|
CURLcode res = CURLE_OK;
|
|
CURL *curl = curl_easy_init();
|
|
|
|
curl_easy_setopt(curl, CURLOPT_URL, "wss://example.com/");
|
|
curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L);
|
|
/* start HTTPS connection and upgrade to WSS, then return control */
|
|
curl_easy_perform(curl);
|
|
|
|
/* Note: This example neglects fragmented messages. (CURLWS_CONT bit)
|
|
A real application must handle them appropriately. */
|
|
|
|
while(!res) {
|
|
size_t recv;
|
|
const struct curl_ws_frame *meta;
|
|
res = curl_ws_recv(curl, buffer + offset, sizeof(buffer) - offset, &recv,
|
|
&meta);
|
|
offset += recv;
|
|
|
|
if(res == CURLE_OK) {
|
|
if(meta->bytesleft == 0)
|
|
break; /* finished receiving */
|
|
if(meta->bytesleft > sizeof(buffer) - offset)
|
|
res = CURLE_TOO_LARGE;
|
|
}
|
|
|
|
if(res == CURLE_AGAIN)
|
|
/* in real application: wait for socket here, e.g. using select() */
|
|
res = CURLE_OK;
|
|
}
|
|
|
|
curl_easy_cleanup(curl);
|
|
return (int)res;
|
|
}
|
|
.fi
|
|
.SH AVAILABILITY
|
|
Added in curl 7.86.0
|
|
.SH RETURN VALUE
|
|
This function returns a CURLcode indicating success or error.
|
|
|
|
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
|
|
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
|
|
there can be an error message stored in the error buffer when non\-zero is
|
|
returned.
|
|
|
|
Returns \fBCURLE_GOT_NOTHING\fP if the associated connection is closed.
|
|
|
|
Instead of blocking, the function returns \fBCURLE_AGAIN\fP. The correct
|
|
behavior is then to wait for the socket to signal readability before calling
|
|
this function again.
|
|
|
|
Any other non\-zero return value indicates an error. See the \fIlibcurl\-errors(3)\fP
|
|
man page for the full list with descriptions.
|
|
|
|
Returns \fBCURLE_GOT_NOTHING\fP if the associated connection is closed.
|
|
.SH SEE ALSO
|
|
.BR curl_easy_getinfo (3),
|
|
.BR curl_easy_perform (3),
|
|
.BR curl_easy_setopt (3),
|
|
.BR curl_ws_send (3),
|
|
.BR libcurl-ws (3)
|