1--- 2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al. 3SPDX-License-Identifier: curl 4Title: curl_ws_recv 5Section: 3 6Source: libcurl 7See-also: 8 - curl_easy_getinfo (3) 9 - curl_easy_perform (3) 10 - curl_easy_setopt (3) 11 - curl_ws_send (3) 12 - libcurl-ws (3) 13--- 14 15# NAME 16 17curl_ws_recv - receive WebSocket data 18 19# SYNOPSIS 20 21~~~c 22#include <curl/curl.h> 23 24CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen, 25 size_t *recv, const struct curl_ws_frame **meta); 26~~~ 27 28# DESCRIPTION 29 30This function call is EXPERIMENTAL. 31 32Retrieves as much as possible of a received WebSocket data fragment into the 33**buffer**, but not more than **buflen** bytes. *recv* is set to the 34number of bytes actually stored. 35 36If there is more fragment data to deliver than what fits in the provided 37*buffer*, libcurl returns a full buffer and the application needs to call 38this function again to continue draining the buffer. 39 40The *meta* pointer gets set to point to a *const struct curl_ws_frame* 41that contains information about the received data. See the 42curl_ws_meta(3) for details on that struct. 43 44# EXAMPLE 45 46~~~c 47int main(void) 48{ 49 size_t rlen; 50 const struct curl_ws_frame *meta; 51 char buffer[256]; 52 CURL *curl = curl_easy_init(); 53 if(curl) { 54 CURLcode res = curl_ws_recv(curl, buffer, sizeof(buffer), &rlen, &meta); 55 if(res) 56 printf("error: %s\n", curl_easy_strerror(res)); 57 } 58} 59~~~ 60 61# AVAILABILITY 62 63Added in 7.86.0. 64 65# RETURN VALUE 66 67Returns **CURLE_OK** if everything is okay, and a non-zero number for 68errors. Returns **CURLE_GOT_NOTHING** if the associated connection is 69closed. 70 71Instead of blocking, the function returns **CURLE_AGAIN**. The correct 72behavior is then to wait for the socket to signal readability before calling 73this function again. 74