luo980/curl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

libcurl-ws.3. WebSocket API overview

Browse Source 
Closes #11314
This commit is contained in:
Daniel Stenberg 2023-06-14 10:57:50 +02:00
parent 4257ab41ed
commit 4337242345
No known key found for this signature in database
GPG Key ID: 5CC908FDB71E12C2
3 changed files with 105 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/scripts/cleanspell.pl vendored
View File

@ -70,7 +70,7 @@ while(<F>) {
$_ =~ s/curl_ws_(send|recv|meta)//g;
$_ =~ s/curl_url_(dup)//g;
$_ =~ s/curl_pushheader_by(name|num)//g;
$_ =~ s/libcurl-env//g;
$_ =~ s/libcurl-(env|ws)//g;
$_ =~ s/(^|\W)((tftp|https|http|ftp):\/\/[a-z0-9\-._~%:\/?\#\[\]\@!\$&'()*+,;=]+)//gi;
print O $_;
}

1
docs/libcurl/Makefile.inc
View File

@ -117,4 +117,5 @@ man_MANS = \
libcurl-thread.3 \
libcurl-tutorial.3 \
libcurl-url.3 \
libcurl-ws.3 \
libcurl.3

103
docs/libcurl/libcurl-ws.3 Normal file
View File

@ -0,0 +1,103 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 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 libcurl 3 "10 Sep 2018" "libcurl" "libcurl"
.SH NAME
libcurl-ws \- WebSocket interface overview
.SH DESCRIPTION
The WebSocket interface provides functions for receiving and sending WebSocket
data.
.SH INCLUDE
You still only include <curl/curl.h> in your code.
.SH SETUP
WebSocket is also often known as \fIWebSockets\fP, in plural. It is done by
upgrading a regular HTTP(S) GET request to a WebSocket connection.
WebSocket is a TCP-like message-based communication protocol done over HTTP,
specified in RFC 6455.
To initiate a WebSocket session with libcurl, setup an easy handle to use a
URL with a "WS://" or "WSS://" scheme. "WS" is for cleartext communication
over HTTP and "WSS" is for doing WebSocket securely over HTTPS.
A WebSocket request is done as an HTTP/1 GET request with an "Upgrade
WebSocket" request header field. When the upgrade is accepted by the server,
it responds with a 101 Switching and then the client can speak WebSocket with
the server.
.SH MESSAGES
WebSocket communication is message based. That means that is sends and
receives entire messages, not streams like TCP. A WebSocket message is sent
over the wire in one or more frames. Each frame in a message can have a size
up to 2^63 bytes.
libcurl delivers WebSocket data as frame fragments. It might send a whole
frame, but it might also deliver them in pieces depending on size and network
patterns. It makes sure to provide the API user about the exact specifics
about the fragment: type, offset, size and how much data there is pending to
arrive for the same frame.
A message has an unknown size until the last frame header for the message has
been received since only frames have set sizes.
.SH PING
WebSocket is designed to allow long-lived sessions and in order to keep the
connections alive, both ends can send PING messages for the other end to
respond with a PONG.
libcurl automatically responds to server PING messages with a PONG. It does
not send any PING messages automatically.
.SH MODELS
Because of the many different ways WebSocket can be used, which is much more
flexible than limited to plain downloads or uploads, libcurl offers two
different API models to use it:
1. Using a write callback with \fICURLOPT_WRITEFUNCTION(3)\fP much like other
downloads for when the traffic is download oriented.
2. Using \fICURLOPT_CONNECT_ONLY(3)\fP and use the WebSocket recv/send
functions at will.
.SH "Callback model"
When a write callback is set and a WebSocket transfer is performed, the
callback will be called to deliver all WebSocket data that arrives.
The callback can then call \fIcurl_ws_meta(3)\fP to learn about the details of
the incoming data fragment.
.SH "CONNECT_ONLY model"
By setting \fICURLOPT_CONNECT_ONLY(3)\fP to \fB2L\fP, the transfer will only
establish and setup the WebSocket communication and then return control back
to the application.
Once such a setup has been successfully performed, the application can proceed
and use \fIcurl_ws_recv(3)\fP and \fIcurl_ws_send(3)\fP freely to exchange
WebSocket messages with the server.
.SH AVAILABILITY
The WebSocket API was introduced as experimental in 7.86.0 and is still
experimental today.
It is only built-in if explicitly opted in at build time. We discourage use of
the WebSocket API in production because of its experimental state. We might
change API, ABI and behavior before this "goes live".
.SH "SEE ALSO"
.BR curl_ws_meta "(3), " curl_ws_recv "(3), " curl_ws_send "(3), "
.BR curl_easy_init "(3), " CURLOPT_CONNECT_ONLY "(3), "
.BR CURLOPT_WRITEFUNCTION "(3)"