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