1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_WS_OPTIONS
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_CONNECT_ONLY (3)
9  - curl_ws_recv (3)
10  - curl_ws_send (3)
11Protocol:
12  - WS
13---
14
15# NAME
16
17CURLOPT_WS_OPTIONS - WebSocket behavior options
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WS_OPTIONS, long bitmask);
25~~~
26
27# DESCRIPTION
28
29Pass a long with a bitmask to tell libcurl about specific WebSocket
30behaviors.
31
32To detach a WebSocket connection and use the curl_ws_send(3) and
33curl_ws_recv(3) functions after the HTTP upgrade procedure, set the
34CURLOPT_CONNECT_ONLY(3) option to 2L.
35
36Available bits in the bitmask
37
38## CURLWS_RAW_MODE (1)
39
40Deliver "raw" WebSocket traffic to the CURLOPT_WRITEFUNCTION(3)
41callback.
42
43In raw mode, libcurl does not handle pings or any other frame for the
44application.
45
46# DEFAULT
47
480
49
50# EXAMPLE
51
52~~~c
53int main(void)
54{
55  CURL *curl = curl_easy_init();
56  if(curl) {
57    CURLcode res;
58    curl_easy_setopt(curl, CURLOPT_URL, "ws://example.com/");
59    /* tell curl we deal with all the WebSocket magic ourselves */
60    curl_easy_setopt(curl, CURLOPT_WS_OPTIONS, (long)CURLWS_RAW_MODE);
61    res = curl_easy_perform(curl);
62    curl_easy_cleanup(curl);
63  }
64}
65~~~
66
67# AVAILABILITY
68
69Added in 7.86.0
70
71# RETURN VALUE
72
73Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
74