curl_ws_meta(3)

1curl_ws_meta(3)                     libcurl                    curl_ws_meta(3)
2
3
4

NAME

6       curl_ws_meta - meta data WebSocket information
7

SYNOPSIS

9       #include <curl/easy.h>
10
11       struct curl_ws_frame {
12         int age;              /* zero */
13         int flags;            /* See the CURLWS_* defines */
14         curl_off_t offset;    /* the offset of this data into the frame */
15         curl_off_t bytesleft; /* number of pending bytes left of the payload */
16       };
17
18       const struct curl_ws_frame *curl_ws_meta(CURL *curl);
19

DESCRIPTION

21       This function call is EXPERIMENTAL.
22
23       When  the  write  callback (CURLOPT_WRITEFUNCTION(3)) is invoked on re‐
24       ceived WebSocket traffic, curl_ws_meta(3) can be called from within the
25       callback to provide additional information about the current frame.
26
27       This  function  only  works from within the callback, and only when re‐
28       ceiving WebSocket data.
29
30       This function requires an easy handle as input argument for libcurl  to
31       know  what  transfer  the  question  is  about, but as there is no such
32       pointer provided to the callback by libcurl itself,  applications  that
33       want  to  use curl_ws_meta(3) need to pass it on to the callback on its
34       own.
35
36

struct fields

38       age    This field specify the age of this struct. It is always zero for
39              now.
40
41       flags  This  is  a  bitmask with individual bits set that describes the
42              WebSocket data. See the list below.
43
44       offset When this frame is a continuation of fragment data  already  de‐
45              livered,  this  is the offset into the final fragment where this
46              piece belongs.
47
48       bytesleft
49              If this is not a complete fragment, the bytesleft field  informs
50              about  how  many  additional bytes are expected to arrive before
51              this fragment is complete.
52

FLAGS

54       CURLWS_TEXT
55              The buffer contains text data. Note that this makes a difference
56              to  WebSocket  but libcurl itself will not make any verification
57              of the content or precautions that you  actually  receive  valid
58              UTF-8 content.
59
60       CURLWS_BINARY
61              This is binary data.
62
63       CURLWS_CONT
64              This  is  not the final fragment of the message, it implies that
65              there will be another fragment coming as part of the  same  mes‐
66              sage.
67
68       CURLWS_CLOSE
69              This transfer is now closed.
70
71       CURLWS_PING
72              This as an incoming ping message, that expects a pong response.
73

EXAMPLE

75       /* we pass a pointer to this struct to the callback */
76       struct customdata {
77         CURL *easy;
78         void *ptr;
79       };
80
81       static size_t writecb(unsigned char *buffer,
82                             size_t size, size_t nitems, void *p)
83       {
84         struct customdata *c = (struct customdata *)p;
85         const struct curl_ws_frame *m = curl_ws_meta(c->easy);
86
87         /* m->flags tells us about the traffic */
88       }
89
90       {
91         struct customdata custom;
92         custom.easy = easy;
93         custom.ptr = NULL;
94         curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writecb);
95         curl_easy_setopt(curl, CURLOPT_WRITEDATA, &custom);
96       }
97

AVAILABILITY

99       Added in 7.86.0.
100

RETURN VALUE

102       This  function  returns  a pointer to a curl_ws_frame struct with read-
103       only information that is valid for this specific  callback  invocation.
104       If  it  cannot return this information, or if the function is called in
105       the wrong context, it returns NULL.
106