1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: curl_ws_meta 5Section: 3 6Source: libcurl 7See-also: 8 - curl_easy_getinfo (3) 9 - curl_easy_setopt (3) 10 - curl_ws_recv (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_meta - meta data WebSocket information 21 22# SYNOPSIS 23 24~~~c 25#include <curl/curl.h> 26 27const struct curl_ws_frame *curl_ws_meta(CURL *curl); 28~~~ 29 30# DESCRIPTION 31 32When the write callback (CURLOPT_WRITEFUNCTION(3)) is invoked on 33received WebSocket traffic, curl_ws_meta(3) can be called from within 34the callback to provide additional information about the current frame. 35 36This function only works from within the callback, and only when receiving 37WebSocket data. 38 39This function requires an easy handle as input argument for libcurl to know 40what transfer the question is about, but as there is no such pointer provided 41to the callback by libcurl itself, applications that want to use 42curl_ws_meta(3) need to pass it on to the callback on its own. 43 44# struct curl_ws_frame 45 46~~~c 47struct curl_ws_frame { 48 int age; 49 int flags; 50 curl_off_t offset; 51 curl_off_t bytesleft; 52 size_t len; 53}; 54~~~ 55 56## `age` 57 58This field specify the age of this struct. It is always zero for now. 59 60## `flags` 61 62This is a bitmask with individual bits set that describes the WebSocket data. 63See the list below. 64 65## `offset` 66 67When this chunk is a continuation of frame data already delivered, this is 68the offset into the final frame data where this piece belongs to. 69 70## `bytesleft` 71 72If this is not a complete fragment, the *bytesleft* field informs about how 73many additional bytes are expected to arrive before this fragment is complete. 74 75## `len` 76 77The length of the current data chunk. 78 79# FLAGS 80 81The *message type* flags (CURLWS_TEXT/BINARY/CLOSE/PING/PONG) are mutually 82exclusive. 83 84## CURLWS_TEXT 85 86This is a message with text data. Note that this makes a difference to WebSocket 87but libcurl itself does not make any verification of the content or 88precautions that you actually receive valid UTF-8 content. 89 90## CURLWS_BINARY 91 92This is a message with binary data. 93 94## CURLWS_CLOSE 95 96This is a close message. No more data follows. 97 98It may contain a 2-byte unsigned integer in network byte order that indicates 99the close reason and may additionally contain up to 123 bytes of further 100textual payload for a total of at most 125 bytes. libcurl does not verify that 101the textual description is valid UTF-8. 102 103## CURLWS_PING 104 105This is a ping message. It may contain up to 125 bytes of payload text. 106libcurl does not verify that the payload is valid UTF-8. 107 108Upon receiving a ping message, libcurl automatically responds with a pong 109message unless the **CURLWS_RAW_MODE** bit of CURLOPT_WS_OPTIONS(3) is set. 110 111## CURLWS_PONG 112 113This is a pong message. It may contain up to 125 bytes of payload text. 114libcurl does not verify that the payload is valid UTF-8. 115 116## CURLWS_CONT 117 118Can only occur in conjunction with CURLWS_TEXT or CURLWS_BINARY. 119 120This is not the final fragment of the message, it implies that there is 121another fragment coming as part of the same message. The application must 122reassemble the fragments to receive the complete message. 123 124Only a single fragmented message can be transmitted at a time, but it may 125be interrupted by CURLWS_CLOSE, CURLWS_PING or CURLWS_PONG frames. 126 127# %PROTOCOLS% 128 129# EXAMPLE 130 131~~~c 132 133/* we pass a pointer to this struct to the callback */ 134struct customdata { 135 CURL *easy; 136 void *ptr; 137}; 138 139static size_t writecb(unsigned char *buffer, 140 size_t size, size_t nitems, void *p) 141{ 142 struct customdata *c = (struct customdata *)p; 143 const struct curl_ws_frame *m = curl_ws_meta(c->easy); 144 145 printf("flags: %x\n", m->flags); 146} 147 148int main(void) 149{ 150 CURL *curl = curl_easy_init(); 151 if(curl) { 152 struct customdata custom; 153 custom.easy = curl; 154 custom.ptr = NULL; 155 curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writecb); 156 curl_easy_setopt(curl, CURLOPT_WRITEDATA, &custom); 157 158 curl_easy_perform(curl); 159 160 } 161} 162~~~ 163 164# %AVAILABILITY% 165 166# RETURN VALUE 167 168This function returns a pointer to a *curl_ws_frame* struct with read-only 169information that is valid for this specific callback invocation. If it cannot 170return this information, or if the function is called in the wrong context, it 171returns NULL. 172