manpagez: man pages & more
man curl_ws_meta(3)
Home | html | info | man
curl_ws_meta(3)            Library Functions Manual            curl_ws_meta(3)


NAME

       curl_ws_meta - meta data WebSocket information


SYNOPSIS

       #include <curl/curl.h>

       const struct curl_ws_frame *curl_ws_meta(CURL *curl);


DESCRIPTION

       When the write callback (CURLOPT_WRITEFUNCTION(3)) is invoked on
       received WebSocket traffic, curl_ws_meta(3) can be called from within
       the callback to provide additional information about the current frame.

       This function only works from within the callback, and only when
       receiving WebSocket data.

       This function requires an easy handle as input argument for libcurl to
       know what transfer the question is about, but as there is no such
       pointer provided to the callback by libcurl itself, applications that
       want to use curl_ws_meta(3) need to pass it on to the callback on its
       own.


struct curl_ws_frame

       struct curl_ws_frame {
         int age;
         int flags;
         curl_off_t offset;
         curl_off_t bytesleft;
         size_t len;
       };

       age    This field specify the age of this struct. It is always zero for
              now.

       flags  This is a bitmask with individual bits set that describes the
              WebSocket data.  See the list below.

       offset When this chunk is a continuation of frame data already
              delivered, this is the offset into the final frame data where
              this piece belongs to.

       bytesleft
              If this is not a complete fragment, the bytesleft field informs
              about how many additional bytes are expected to arrive before
              this fragment is complete.

       len    The length of the current data chunk.


FLAGS

       The message type flags (CURLWS_TEXT/BINARY/CLOSE/PING/PONG) are
       mutually exclusive.

       CURLWS_TEXT
              This is a message with text data. Note that this makes a
              difference to WebSocket but libcurl itself does not make any
              verification of the content or precautions that you actually
              receive valid UTF-8 content.

       CURLWS_BINARY
              This is a message with binary data.

       CURLWS_CLOSE
              This is a close message. No more data follows.

              It may contain a 2-byte unsigned integer in network byte order
              that indicates the close reason and may additionally contain up
              to 123 bytes of further textual payload for a total of at most
              125 bytes. libcurl does not verify that the textual description
              is valid UTF-8.

       CURLWS_PING
              This is a ping message. It may contain up to 125 bytes of
              payload text.  libcurl does not verify that the payload is valid
              UTF-8.

              Upon receiving a ping message, libcurl automatically responds
              with a pong message unless the CURLWS_RAW_MODE bit of
              CURLOPT_WS_OPTIONS(3) is set.

       CURLWS_PONG
              This is a pong message. It may contain up to 125 bytes of
              payload text.  libcurl does not verify that the payload is valid
              UTF-8.

       CURLWS_CONT
              Can only occur in conjunction with CURLWS_TEXT or CURLWS_BINARY.

              This is not the final fragment of the message, it implies that
              there is another fragment coming as part of the same message.
              The application must reassemble the fragments to receive the
              complete message.

              Only a single fragmented message can be transmitted at a time,
              but it may be interrupted by CURLWS_CLOSE, CURLWS_PING or
              CURLWS_PONG frames.


PROTOCOLS

       This functionality affects ws only


EXAMPLE


       /* we pass a pointer to this struct to the callback */
       struct customdata {
         CURL *easy;
         void *ptr;
       };

       static size_t writecb(unsigned char *buffer,
                             size_t size, size_t nitems, void *p)
       {
         struct customdata *c = (struct customdata *)p;
         const struct curl_ws_frame *m = curl_ws_meta(c->easy);

         printf("flags: %x\n", m->flags);
       }

       int main(void)
       {
         CURL *curl = curl_easy_init();
         if(curl) {
           struct customdata custom;
           custom.easy = curl;
           custom.ptr = NULL;
           curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writecb);
           curl_easy_setopt(curl, CURLOPT_WRITEDATA, &custom);

           curl_easy_perform(curl);

         }
       }


AVAILABILITY

       Added in curl 7.86.0


RETURN VALUE

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


SEE ALSO

       curl_easy_getinfo(3), curl_easy_setopt(3), curl_ws_recv(3),
       curl_ws_send(3), libcurl-ws(3)

libcurl                           2025-02-08                   curl_ws_meta(3)

curl 8.12.0 - Generated Wed Feb 19 16:17:49 CST 2025
© manpagez.com 2000-2025
Individual documents may contain additional copyright information.