libcurl-ws(3)

1libcurl(3)                          libcurl                         libcurl(3)
2
3
4

NAME

6       libcurl-ws - WebSocket interface overview
7

DESCRIPTION

9       The  WebSocket  interface  provides functions for receiving and sending
10       WebSocket data.
11

INCLUDE

13       You still only include <curl/curl.h> in your code.
14

SETUP

16       WebSocket is also often known as WebSockets, in plural. It is  done  by
17       upgrading a regular HTTP(S) GET request to a WebSocket connection.
18
19       WebSocket  is a TCP-like message-based communication protocol done over
20       HTTP, specified in RFC 6455.
21
22       To initiate a WebSocket session with libcurl, setup an easy  handle  to
23       use a URL with a "WS://" or "WSS://" scheme. "WS" is for cleartext com‐
24       munication over HTTP and "WSS" is for  doing  WebSocket  securely  over
25       HTTPS.
26
27       A  WebSocket  request is done as an HTTP/1 GET request with an "Upgrade
28       WebSocket" request header field. When the upgrade is  accepted  by  the
29       server,  it responds with a 101 Switching and then the client can speak
30       WebSocket with the server. The communication can happen in both  direc‐
31       tions at the same time.
32

MESSAGES

34       WebSocket  communication  is  message  based. That means that both ends
35       send and receive entire messages, not streams  like  TCP.  A  WebSocket
36       message  is  sent  over the wire in one or more frames. Each frame in a
37       message can have a size up to 2^63 bytes.
38
39       libcurl delivers WebSocket data as frame fragments.  It  might  send  a
40       whole frame, but it might also deliver them in pieces depending on size
41       and network patterns. It makes sure to provide the API user  about  the
42       exact  specifics  about  the  fragment: type, offset, size and how much
43       data there is pending to arrive for the same frame.
44
45       A message has an unknown size until the last frame header for the  mes‐
46       sage has been received since only frames have set sizes.
47

Raw mode

49       libcurl  can  be  told  to speak WebSocket in "raw mode" by setting the
50       CURLWS_RAW_MODE bit to the CURLOPT_WS_OPTIONS(3) option.
51
52       Raw WebSocket means that libcurl will pass on the data from the network
53       without  parsing it leaving that entirely to the application. This mode
54       assumes that the user of this knows WebSocket and can parse and  figure
55       out the data all by itself.
56
57       This  mode  is  intended for applications that already have a WebSocket
58       parser/engine that want to switch over to use libcurl for enabling Web‐
59       Socket, but keep parts of the existing software architecture.
60

PING

62       WebSocket is designed to allow long-lived sessions and in order to keep
63       the connections alive, both ends can send PING messages for  the  other
64       end to respond with a PONG.
65
66       libcurl  automatically responds to server PING messages with a PONG. It
67       does not send any PING messages automatically.
68

MODELS

70       Because of the many different ways WebSocket can be used, which is much
71       more  flexible  than limited to plain downloads or uploads, libcurl of‐
72       fers two different API models to use it:
73
74       1. Using a write callback with CURLOPT_WRITEFUNCTION(3) much like other
75       downloads for when the traffic is download oriented.
76
77       2.  Using CURLOPT_CONNECT_ONLY(3) and use the WebSocket recv/send func‐
78       tions at will.
79

Callback model

81       When a write callback is set and a WebSocket transfer is performed, the
82       callback will be called to deliver all WebSocket data that arrives.
83
84       The  callback  can then call curl_ws_meta(3) to learn about the details
85       of the incoming data fragment.
86

CONNECT_ONLY model

88       By setting CURLOPT_CONNECT_ONLY(3) to 2L, the transfer will only estab‐
89       lish and setup the WebSocket communication and then return control back
90       to the application.
91
92       Once such a setup has been successfully performed, the application  can
93       proceed  and use curl_ws_recv(3) and curl_ws_send(3) freely to exchange
94       WebSocket messages with the server.
95

AVAILABILITY

97       The WebSocket API was introduced as experimental in 7.86.0 and is still
98       experimental today.
99
100       It is only built-in if explicitly opted in at build time. We discourage
101       use of the WebSocket API in  production  because  of  its  experimental
102       state. We might change API, ABI and behavior before this "goes live".
103