1--- 2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al. 3SPDX-License-Identifier: curl 4Title: curl_ws_send 5Section: 3 6Source: libcurl 7See-also: 8 - curl_easy_getinfo (3) 9 - curl_easy_perform (3) 10 - curl_easy_setopt (3) 11 - curl_ws_recv (3) 12 - libcurl-ws (3) 13--- 14 15# NAME 16 17curl_ws_send - send WebSocket data 18 19# SYNOPSIS 20 21~~~c 22#include <curl/curl.h> 23 24CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen, 25 size_t *sent, curl_off_t fragsize, 26 unsigned int flags); 27~~~ 28 29# DESCRIPTION 30 31This function call is EXPERIMENTAL. 32 33Send the specific message fragment over an established WebSocket 34connection. The *buffer* holds the data to send and it is *buflen* 35number of payload bytes in that memory area. 36 37*sent* is returned as the number of payload bytes actually sent. 38 39To send a (huge) fragment using multiple calls with partial content per 40invoke, set the *CURLWS_OFFSET* bit and the *fragsize* argument as the 41total expected size for the first part, then set the *CURLWS_OFFSET* with 42a zero *fragsize* for the following parts. 43 44If not sending a partial fragment or if this is raw mode, *fragsize* 45should be set to zero. 46 47If **CURLWS_RAW_MODE** is enabled in CURLOPT_WS_OPTIONS(3), the 48**flags** argument should be set to 0. 49 50To send a message consisting of multiple frames, set the *CURLWS_CONT* bit 51in all frames except the final one. 52 53# FLAGS 54 55## CURLWS_TEXT 56 57The buffer contains text data. Note that this makes a difference to WebSocket 58but libcurl itself does not make any verification of the content or 59precautions that you actually send valid UTF-8 content. 60 61## CURLWS_BINARY 62 63This is binary data. 64 65## CURLWS_CONT 66 67This is not the final fragment of the message, which implies that there is 68another fragment coming as part of the same message where this bit is not set. 69 70## CURLWS_CLOSE 71 72Close this transfer. 73 74## CURLWS_PING 75 76This is a ping. 77 78## CURLWS_PONG 79 80This is a pong. 81 82## CURLWS_OFFSET 83 84The provided data is only a partial fragment and there is more coming in a 85following call to *curl_ws_send()*. When sending only a piece of the 86fragment like this, the *fragsize* must be provided with the total 87expected fragment size in the first call and it needs to be zero in subsequent 88calls. 89 90# EXAMPLE 91 92~~~c 93#include <string.h> /* for strlen */ 94 95const char *send_payload = "magic"; 96 97int main(void) 98{ 99 size_t sent; 100 CURLcode res; 101 CURL *curl = curl_easy_init(); 102 curl_easy_setopt(curl, CURLOPT_URL, "wss://example.com/"); 103 curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L); 104 curl_easy_perform(curl); 105 res = curl_ws_send(curl, send_payload, strlen(send_payload), &sent, 0, 106 CURLWS_PING); 107 curl_easy_cleanup(curl); 108 return (int)res; 109} 110~~~ 111 112# AVAILABILITY 113 114Added in 7.86.0. 115 116# RETURN VALUE 117 118*CURLE_OK* (zero) means that the data was sent properly, non-zero means an 119error occurred as *<curl/curl.h>* defines. See the libcurl-errors(3) 120man page for the full list with descriptions. 121