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