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