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