114 lines
4.2 KiB
Groff
114 lines
4.2 KiB
Groff
|
.\" generated by cd2nroff 0.1 from curl_ws_send.md
|
||
|
|
.TH curl_ws_send 3 "2025-07-07" libcurl
|
||
|
|
.SH NAME
|
||
|
|
curl_ws_send \- send WebSocket data
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.nf
|
||
|
|
#include <curl/curl.h>
|
||
|
|
|
||
|
|
CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen,
|
||
|
|
size_t *sent, curl_off_t fragsize,
|
||
|
|
unsigned int flags);
|
||
|
|
.fi
|
||
|
|
.SH DESCRIPTION
|
||
|
|
Send the specific message chunk over an established WebSocket
|
||
|
|
connection. \fIbuffer\fP must point to a valid memory location containing
|
||
|
|
(at least) \fIbuflen\fP bytes of payload memory.
|
||
|
|
|
||
|
|
\fIsent\fP is set to the number of payload bytes actually sent. If the return value
|
||
|
|
is \fBCURLE_OK\fP but \fIsent\fP is less than the given \fIbuflen\fP, libcurl was unable
|
||
|
|
to consume the complete payload in a single call. In this case the application
|
||
|
|
must call this function again until all payload is processed. \fIbuffer\fP and
|
||
|
|
\fIbuflen\fP must be updated on every following invocation to only point to the
|
||
|
|
remaining piece of the payload.
|
||
|
|
|
||
|
|
\fIfragsize\fP should always be set to zero unless a (huge) frame shall be sent
|
||
|
|
using multiple calls with partial content per call explicitly. In that
|
||
|
|
case you must set the \fICURLWS_OFFSET\fP bit and set the \fIfragsize\fP as documented
|
||
|
|
in the section on \fICURLWS_OFFSET\fP below.
|
||
|
|
|
||
|
|
\fIflags\fP must contain at least one flag indicating the type of the message.
|
||
|
|
To send a fragmented message consisting of multiple frames, additionally set
|
||
|
|
the \fICURLWS_CONT\fP bit in all frames except the final one. The appropriate
|
||
|
|
message type bit should be set in every frame of a fragmented message without
|
||
|
|
exemption. Omitting the message type for continuation frames of a fragmented
|
||
|
|
message is only supported for backwards compatibility and highly discouraged.
|
||
|
|
|
||
|
|
For more details on the supported flags see below and in \fIcurl_ws_meta(3)\fP.
|
||
|
|
|
||
|
|
If \fICURLWS_RAW_MODE\fP is enabled in \fICURLOPT_WS_OPTIONS(3)\fP, the
|
||
|
|
\fIflags\fP argument should be set to 0.
|
||
|
|
|
||
|
|
Warning: while it is possible to invoke this function from a callback,
|
||
|
|
such a call is blocking in this situation, e.g. only returns after all data
|
||
|
|
has been sent or an error is encountered.
|
||
|
|
.SH FLAGS
|
||
|
|
Supports all flags documented in \fIcurl_ws_meta(3)\fP and additionally the following
|
||
|
|
flags.
|
||
|
|
.IP CURLWS_OFFSET
|
||
|
|
The provided data is only a partial frame and there is more coming in a
|
||
|
|
following call to \fIcurl_ws_send()\fP. When sending only a piece of the
|
||
|
|
frame like this, the \fIfragsize\fP must be provided with the total
|
||
|
|
expected frame size in the first call and must be zero in all subsequent
|
||
|
|
calls.
|
||
|
|
.SH PROTOCOLS
|
||
|
|
This functionality affects ws only
|
||
|
|
.SH EXAMPLE
|
||
|
|
.nf
|
||
|
|
#include <string.h> /* for strlen */
|
||
|
|
|
||
|
|
int main(void)
|
||
|
|
{
|
||
|
|
const char *buffer = "PAYLOAD";
|
||
|
|
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);
|
||
|
|
|
||
|
|
while(!res) {
|
||
|
|
size_t sent;
|
||
|
|
res = curl_ws_send(curl, buffer + offset, strlen(buffer) - offset, &sent,
|
||
|
|
0, CURLWS_TEXT);
|
||
|
|
offset += sent;
|
||
|
|
|
||
|
|
if(res == CURLE_OK) {
|
||
|
|
if(offset == strlen(buffer))
|
||
|
|
break; /* finished sending */
|
||
|
|
}
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
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.
|
||
|
|
.SH SEE ALSO
|
||
|
|
.BR curl_easy_getinfo (3),
|
||
|
|
.BR curl_easy_perform (3),
|
||
|
|
.BR curl_easy_setopt (3),
|
||
|
|
.BR curl_ws_recv (3),
|
||
|
|
.BR libcurl-ws (3)
|