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 15Added-in: 7.86.0 16--- 17 18# NAME 19 20curl_ws_send - send WebSocket data 21 22# SYNOPSIS 23 24~~~c 25#include <curl/curl.h> 26 27CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen, 28 size_t *sent, curl_off_t fragsize, 29 unsigned int flags); 30~~~ 31 32# DESCRIPTION 33 34Send the specific message chunk over an established WebSocket 35connection. *buffer* must point to a valid memory location containing 36(at least) *buflen* bytes of payload memory. 37 38*sent* is set to the number of payload bytes actually sent. If the return value 39is **CURLE_OK** but *sent* is less than the given *buflen*, libcurl was unable 40to consume the complete payload in a single call. In this case the application 41must call this function again until all payload is processed. *buffer* and 42*buflen* must be updated on every following invocation to only point to the 43remaining piece of the payload. 44 45*fragsize* should always be set to zero unless a (huge) frame shall be sent 46using multiple calls with partial content per call explicitly. In that 47case you must set the *CURLWS_OFFSET* bit and set the *fragsize* as documented 48in the section on *CURLWS_OFFSET* below. 49 50*flags* must contain at least one flag indicating the type of the message. 51To send a fragmented message consisting of multiple frames, additionally set 52the *CURLWS_CONT* bit in all frames except the final one. 53 54For more details on the supported flags see below and in curl_ws_meta(3). 55 56If *CURLWS_RAW_MODE* is enabled in CURLOPT_WS_OPTIONS(3), the 57*flags* argument should be set to 0. 58 59Warning: while it is possible to invoke this function from a callback, 60such a call is blocking in this situation, e.g. only returns after all data 61has been sent or an error is encountered. 62 63# FLAGS 64 65Supports all flags documented in curl_ws_meta(3) and additionally the following 66flags. 67 68## CURLWS_OFFSET 69 70The provided data is only a partial frame and there is more coming in a 71following call to *curl_ws_send()*. When sending only a piece of the 72frame like this, the *fragsize* must be provided with the total 73expected frame size in the first call and must be zero in all subsequent 74calls. 75 76# %PROTOCOLS% 77 78# EXAMPLE 79 80~~~c 81#include <string.h> /* for strlen */ 82 83int main(void) 84{ 85 const char *buffer = "PAYLOAD"; 86 size_t offset = 0; 87 CURLcode res = CURLE_OK; 88 CURL *curl = curl_easy_init(); 89 90 curl_easy_setopt(curl, CURLOPT_URL, "wss://example.com/"); 91 curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L); 92 /* start HTTPS connection and upgrade to WSS, then return control */ 93 curl_easy_perform(curl); 94 95 while(!res) { 96 size_t sent; 97 res = curl_ws_send(curl, buffer + offset, strlen(buffer) - offset, &sent, 98 0, CURLWS_TEXT); 99 offset += sent; 100 101 if(res == CURLE_OK) { 102 if(offset == strlen(buffer)) 103 break; /* finished sending */ 104 } 105 106 if(res == CURLE_AGAIN) 107 /* in real application: wait for socket here, e.g. using select() */ 108 res = CURLE_OK; 109 } 110 111 curl_easy_cleanup(curl); 112 return (int)res; 113} 114~~~ 115 116# %AVAILABILITY% 117 118# RETURN VALUE 119 120This function returns a CURLcode indicating success or error. 121 122CURLE_OK (0) means everything was OK, non-zero means an error occurred, see 123libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3) 124there can be an error message stored in the error buffer when non-zero is 125returned. 126 127Instead of blocking, the function returns **CURLE_AGAIN**. The correct 128behavior is then to wait for the socket to signal readability before calling 129this function again. 130 131Any other non-zero return value indicates an error. See the libcurl-errors(3) 132man page for the full list with descriptions. 133