libcurl-ws.md (5225B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Title: libcurl-ws 5 Section: 3 6 Source: libcurl 7 See-also: 8 - CURLOPT_CONNECT_ONLY (3) 9 - CURLOPT_WRITEFUNCTION (3) 10 - CURLOPT_WS_OPTIONS (3) 11 - curl_easy_init (3) 12 - curl_ws_meta (3) 13 - curl_ws_recv (3) 14 - curl_ws_send (3) 15 Protocol: 16 - All 17 Added-in: 7.86.0 18 --- 19 20 # NAME 21 22 libcurl-ws - WebSocket interface overview 23 24 # DESCRIPTION 25 26 The WebSocket interface provides functions for receiving and sending WebSocket 27 data. 28 29 # INCLUDE 30 31 You still only include \<curl/curl.h\> in your code. 32 33 # SETUP 34 35 WebSocket is also often known as *WebSockets*, in plural. It is done by 36 upgrading a regular HTTP(S) GET request to a WebSocket connection. 37 38 WebSocket is a TCP-like message-based communication protocol done over HTTP, 39 specified in RFC 6455. 40 41 To initiate a WebSocket session with libcurl, setup an easy handle to use a 42 URL with a "WS://" or "WSS://" scheme. "WS" is for cleartext communication 43 over HTTP and "WSS" is for doing WebSocket securely over HTTPS. 44 45 A WebSocket request is done as an HTTP/1 GET request with an "Upgrade 46 WebSocket" request header field. When the upgrade is accepted by the server, 47 it responds with a 101 Switching and then the client can speak WebSocket with 48 the server. The communication can happen in both directions at the same time. 49 50 # EXTENSIONS 51 52 The WebSocket protocol allows the client to request and negotiate *extensions* 53 can add additional features and restrictions to the protocol. 54 55 libcurl does not support the use of extensions and always sets up a connection 56 without them. 57 58 # MESSAGES 59 60 WebSocket communication is message based. That means that both ends send and 61 receive entire messages, not streams like TCP. A WebSocket message is sent 62 over the wire in one or more frames. A message which is split into several 63 frames is referred to as a *fragmented* message and the individual frames are 64 called *fragments*. Each frame (or fragment) in a message can have a size of 65 up to 2^63 bytes and declares the frame size in the header. The total size of 66 a message that is fragmented into multiple frames is not limited by the 67 protocol and the number of fragments is not known until the final fragment is 68 received. 69 70 Transmission of a frame must not be interrupted by any other data transfers and 71 transmission of the different fragments of a message must not be interrupted by 72 other user data frames. Control frames - PING, PONG and CLOSE - may be 73 transmitted in between any other two frames, even in between two fragments of 74 the same user data message. The control frames themselves on the other hand 75 must never be fragmented and are limited to a size of 125 bytes. 76 77 libcurl delivers WebSocket data as chunks of frames. It might deliver a whole 78 frame as a single chunk, but it might also deliver it in several pieces 79 depending on size and network patterns. See the individual API documentations 80 for further information. 81 82 # PING 83 84 WebSocket is designed to allow long-lived sessions and in order to keep the 85 connections alive, both ends can send PING messages for the other end to 86 respond with a PONG. Both ends may also send unsolicited PONG messages as 87 unidirectional heartbeat. 88 89 libcurl automatically responds to server PING messages with a PONG that echoes 90 the payload of the PING message. libcurl does neither send any PING messages 91 nor any unsolicited PONG messages automatically. The automatic reply to PING 92 messages can be disabled through CURLOPT_WS_OPTIONS(3). 93 94 # MODELS 95 96 Because of the many different ways WebSocket can be used, which is much more 97 flexible than limited to plain downloads or uploads, libcurl offers two 98 different API models to use it: 99 100 1. CURLOPT_WRITEFUNCTION model: 101 Using a write callback with CURLOPT_WRITEFUNCTION(3) much like other 102 downloads for when the traffic is download oriented. 103 104 2. CURLOPT_CONNECT_ONLY model: 105 Using curl_ws_recv(3) and curl_ws_send(3) functions. 106 107 ## CURLOPT_WRITEFUNCTION MODEL 108 109 CURLOPT_CONNECT_ONLY(3) must be unset or **0L** for this model to take effect. 110 111 curl_easy_perform(3) establishes and sets up the WebSocket communication and 112 then blocks for the whole duration of the connection. libcurl calls the 113 callback configured in CURLOPT_WRITEFUNCTION(3), whenever an incoming chunk 114 of WebSocket data is received. The callback is handed a pointer to the payload 115 data as an argument and can call curl_ws_meta(3) to get relevant metadata. 116 117 ## CURLOPT_CONNECT_ONLY MODEL 118 119 CURLOPT_CONNECT_ONLY(3) must be **2L** for this model to take effect. 120 121 curl_easy_perform(3) only establishes and sets up the WebSocket communication 122 and then returns control back to the application. The application can then use 123 curl_ws_recv(3) and curl_ws_send(3) to exchange WebSocket messages with the 124 server. 125 126 # RAW MODE 127 128 libcurl can be told to speak WebSocket in "raw mode" by setting the 129 **CURLWS_RAW_MODE** bit of the CURLOPT_WS_OPTIONS(3) option. 130 131 Raw WebSocket means that libcurl passes on the data from the network without 132 parsing it, leaving that entirely to the application. 133 134 This mode is intended for applications that already have a WebSocket 135 parser/engine and want to switch over to use libcurl for enabling WebSocket, 136 and keep parts of the existing software architecture.