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