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 this 41function again to continue draining the buffer. 42 43If the function call is successful, the *meta* pointer gets set to point to a 44*const struct curl_ws_frame* that contains information about the received 45data. That struct must not be freed and its contents must not be relied upon 46anymore once another WebSocket function is called. See the curl_ws_meta(3) for 47details on that struct.a 48 49# %PROTOCOLS% 50 51# EXAMPLE 52 53~~~c 54int main(void) 55{ 56 size_t rlen; 57 const struct curl_ws_frame *meta; 58 char buffer[256]; 59 CURL *curl = curl_easy_init(); 60 if(curl) { 61 CURLcode res = curl_ws_recv(curl, buffer, sizeof(buffer), &rlen, &meta); 62 if(res) 63 printf("error: %s\n", curl_easy_strerror(res)); 64 } 65} 66~~~ 67 68# %AVAILABILITY% 69 70# RETURN VALUE 71 72Returns **CURLE_OK** if everything is okay, and a non-zero number for 73errors. Returns **CURLE_GOT_NOTHING** if the associated connection is 74closed. 75 76Instead of blocking, the function returns **CURLE_AGAIN**. The correct 77behavior is then to wait for the socket to signal readability before calling 78this function again. 79
