1--- 2c: Copyright (C) Daniel Stenberg, <daniel.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) 13--- 14 15# NAME 16 17curl_ws_meta - meta data WebSocket information 18 19# SYNOPSIS 20 21~~~c 22#include <curl/curl.h> 23 24const struct curl_ws_frame *curl_ws_meta(CURL *curl); 25~~~ 26 27# DESCRIPTION 28 29This function call is EXPERIMENTAL. 30 31When the write callback (CURLOPT_WRITEFUNCTION(3)) is invoked on 32received WebSocket traffic, curl_ws_meta(3) can be called from within 33the callback to provide additional information about the current frame. 34 35This function only works from within the callback, and only when receiving 36WebSocket data. 37 38This function requires an easy handle as input argument for libcurl to know 39what transfer the question is about, but as there is no such pointer provided 40to the callback by libcurl itself, applications that want to use 41curl_ws_meta(3) need to pass it on to the callback on its own. 42 43# struct curl_ws_frame 44 45~~~c 46struct curl_ws_frame { 47 int age; 48 int flags; 49 curl_off_t offset; 50 curl_off_t bytesleft; 51}; 52~~~ 53 54## age 55 56This field specify the age of this struct. It is always zero for now. 57 58## flags 59 60This is a bitmask with individual bits set that describes the WebSocket 61data. See the list below. 62 63## offset 64 65When this frame is a continuation of fragment data already delivered, this is 66the offset into the final fragment where this piece belongs. 67 68## bytesleft 69 70If this is not a complete fragment, the *bytesleft* field informs about 71how many additional bytes are expected to arrive before this fragment is 72complete. 73 74# FLAGS 75 76## CURLWS_TEXT 77 78The buffer contains text data. Note that this makes a difference to WebSocket 79but libcurl itself does not make any verification of the content or 80precautions that you actually receive valid UTF-8 content. 81 82## CURLWS_BINARY 83 84This is binary data. 85 86## CURLWS_CONT 87 88This is not the final fragment of the message, it implies that there is 89another fragment coming as part of the same message. 90 91## CURLWS_CLOSE 92 93This transfer is now closed. 94 95## CURLWS_PING 96 97This as an incoming ping message, that expects a pong response. 98 99# EXAMPLE 100 101~~~c 102 103/* we pass a pointer to this struct to the callback */ 104struct customdata { 105 CURL *easy; 106 void *ptr; 107}; 108 109static size_t writecb(unsigned char *buffer, 110 size_t size, size_t nitems, void *p) 111{ 112 struct customdata *c = (struct customdata *)p; 113 const struct curl_ws_frame *m = curl_ws_meta(c->easy); 114 115 printf("flags: %x\n", m->flags); 116} 117 118int main(void) 119{ 120 CURL *curl = curl_easy_init(); 121 if(curl) { 122 struct customdata custom; 123 custom.easy = curl; 124 custom.ptr = NULL; 125 curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writecb); 126 curl_easy_setopt(curl, CURLOPT_WRITEDATA, &custom); 127 128 curl_easy_perform(curl); 129 130 } 131} 132~~~ 133 134# AVAILABILITY 135 136Added in 7.86.0. 137 138# RETURN VALUE 139 140This function returns a pointer to a *curl_ws_frame* struct with read-only 141information that is valid for this specific callback invocation. If it cannot 142return this information, or if the function is called in the wrong context, it 143returns NULL. 144