mirror/curl
2
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2024-12-15 06:40:09 +08:00
Code Issues Packages Projects Releases Wiki Activity
00452e6aaf
curl/docs/libcurl/curl_ws_send.3

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

91 lines
3.2 KiB
Groff
Raw Normal View History

ws: initial websockets support Closes #8995
2022-09-09 21:11:14 +08:00
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_ws_send 3 "12 Jun 2022" "libcurl 7.85.0" "libcurl Manual"
.SH NAME
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
2022-10-03 23:40:02 +08:00
curl_ws_send - send WebSocket data
ws: initial websockets support Closes #8995
2022-09-09 21:11:14 +08:00
.SH SYNOPSIS
.nf
#include <curl/easy.h>
websockets: sync prototypes in docs with implementation [ci skip] Docs for the new send/recv functions synced with the committed versions of these. Closes #9470
2022-09-11 05:36:49 +08:00
CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen,
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
2022-10-03 23:40:02 +08:00
size_t *sent, curl_off_t framesize,
unsigned int flags);
ws: initial websockets support Closes #8995
2022-09-09 21:11:14 +08:00
.fi
.SH DESCRIPTION
This function call is EXPERIMENTAL.
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
2022-10-03 23:40:02 +08:00
Send the specific message fragment over an established WebSocket
connection. The \fIbuffer\fP holds the data to send and it is \fIbuflen\fP
number of payload bytes in that memory area.
\fIsent\fP is returned as the number of payload bytes actually sent.
To send a (huge) fragment using multiple calls with partial content per
invoke, set the \fICURLWS_OFFSET\fP bit and the \fIframesize\fP argument as
the total expected size for the first part, then set the \fICURLWS_OFFSET\fP
with a zero \fItotalsize\fP for the following parts.
If not sending a partial fragment or if this is raw mode, \fIframsize\fP
should be set to zero.
ws: initial websockets support Closes #8995
2022-09-09 21:11:14 +08:00
If \fBCURLWS_RAW_MODE\fP is enabled in \fICURLOPT_WS_OPTIONS(3)\fP, the
docs: spellfixes Pointed by the new CI job
2022-09-21 05:30:19 +08:00
\fBflags\fP argument should be set to 0.
ws: initial websockets support Closes #8995
2022-09-09 21:11:14 +08:00
docs: spellfixes Pointed by the new CI job
2022-09-21 05:30:19 +08:00
.SH FLAGS
ws: initial websockets support Closes #8995
2022-09-09 21:11:14 +08:00
.IP CURLWS_TEXT
docs: use "WebSocket" in singular This is how the RFC calls the protocol. Also rename the file in docs/ to WEBSOCKET.md in uppercase to match how we have done it for many other protocol docs in similar fashion. Add the WebSocket docs to the tarball. Closes #9496
2022-09-13 15:17:53 +08:00
The buffer contains text data. Note that this makes a difference to WebSocket
ws: initial websockets support Closes #8995
2022-09-09 21:11:14 +08:00
but libcurl itself will not make any verification of the content or
precautions that you actually send valid UTF-8 content.
.IP CURLWS_BINARY
This is binary data.
.IP CURLWS_CONT
This is not the final fragment of the message, which implies that there will
be another fragment coming as part of the same message where this bit is not
set.
.IP CURLWS_CLOSE
Close this transfer.
.IP CURLWS_PING
This as a ping.
.IP CURLWS_PONG
This as a pong.
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
2022-10-03 23:40:02 +08:00
.IP CURLWS_OFFSET
The provided data is only a partial fragment and there will be more in a
following call to \fIcurl_ws_send()\fP. When sending only a piece of the
fragment like this, the \fIframesize\fP must be provided with the total
expected frame size in the first call and it needs to be zero in subsequent
calls.
ws: initial websockets support Closes #8995
2022-09-09 21:11:14 +08:00
.SH EXAMPLE
.nf
.fi
.SH AVAILABILITY
docs: the websockets symbols are added in 7.86.0 Nothing else Closes #9459
2022-09-09 21:36:06 +08:00
Added in 7.86.0.
ws: initial websockets support Closes #8995
2022-09-09 21:11:14 +08:00
.SH RETURN VALUE
.SH "SEE ALSO"
.BR curl_easy_setopt "(3), " curl_easy_perform "(3), "
.BR curl_easy_getinfo "(3), "
.BR curl_ws_recv "(3) "
Reference in New Issue Copy Permalink