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