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