vendor/curl-sys/curl/docs/libcurl/libcurl-ws.3 - toolchain/rustc - Git at Google

 .\" **************************************************************************
 .\" *                                  _   _ ____  _
 .\" *  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. The communication can happen in both directions at the same time.
 .SH MESSAGES
 WebSocket communication is message based. That means that both ends send and
 receive 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 "Raw mode"
 libcurl can be told to speak WebSocket in "raw mode" by setting the
 \fBCURLWS_RAW_MODE\fP bit to the \fICURLOPT_WS_OPTIONS(3)\fP option.

 Raw WebSocket means that libcurl passes on the data from the network without
 parsing it leaving that entirely to the application. This mode assumes that
 the user of this knows WebSocket and can parse and figure out the data all by
 itself.

 This mode is intended for applications that already have a WebSocket
 parser/engine that want to switch over to use libcurl for enabling WebSocket,
 but keep parts of the existing software architecture.
 .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.
 .SH "Callback model"
 When a write callback is set and a WebSocket transfer is performed, the
 callback is 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 only
 establishes and setups the WebSocket communication and then returns 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_easy_init (3),
 .BR curl_ws_meta (3),
 .BR curl_ws_recv (3),
 .BR curl_ws_send (3),
 .BR CURLOPT_CONNECT_ONLY (3),
 .BR CURLOPT_WRITEFUNCTION (3),
 .BR CURLOPT_WS_OPTIONS (3)
	.\" **************************************************************************
	.\" * _ _ ____ _
	.\" * 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. The communication can happen in both directions at the same time.
	.SH MESSAGES
	WebSocket communication is message based. That means that both ends send and
	receive 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 "Raw mode"
	libcurl can be told to speak WebSocket in "raw mode" by setting the
	\fBCURLWS_RAW_MODE\fP bit to the \fICURLOPT_WS_OPTIONS(3)\fP option.

	Raw WebSocket means that libcurl passes on the data from the network without
	parsing it leaving that entirely to the application. This mode assumes that
	the user of this knows WebSocket and can parse and figure out the data all by
	itself.

	This mode is intended for applications that already have a WebSocket
	parser/engine that want to switch over to use libcurl for enabling WebSocket,
	but keep parts of the existing software architecture.
	.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.
	.SH "Callback model"
	When a write callback is set and a WebSocket transfer is performed, the
	callback is 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 only
	establishes and setups the WebSocket communication and then returns 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_easy_init (3),
	.BR curl_ws_meta (3),
	.BR curl_ws_recv (3),
	.BR curl_ws_send (3),
	.BR CURLOPT_CONNECT_ONLY (3),
	.BR CURLOPT_WRITEFUNCTION (3),
	.BR CURLOPT_WS_OPTIONS (3)