curl/docs/libcurl/curl_ws_meta.3

.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_ws_meta 3 "12 Jun 2022" "libcurl" "libcurl"
.SH NAME
curl_ws_meta - meta data WebSocket information
.SH SYNOPSIS
.nf
#include <curl/easy.h>

struct curl_ws_frame {
  int age;              /* zero */
  int flags;            /* See the CURLWS_* defines */
  curl_off_t offset;    /* the offset of this data into the frame */
  curl_off_t bytesleft; /* number of pending bytes left of the payload */
};

const struct curl_ws_frame *curl_ws_meta(CURL *curl);
.fi
.SH DESCRIPTION
This function call is EXPERIMENTAL.

When the write callback (\fICURLOPT_WRITEFUNCTION(3)\fP) is invoked on
received WebSocket traffic, \fIcurl_ws_meta(3)\fP 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
\fIcurl_ws_meta(3)\fP need to pass it on to the callback on its own.

.SH "struct fields"
.IP age
This field specify the age of this struct. It is always zero for now.
.IP flags
This is a bitmask with individual bits set that describes the WebSocket
data. See the list below.
.IP offset
When this frame is a continuation of fragment data already delivered, this is
the offset into the final fragment where this piece belongs.
.IP bytesleft
If this is not a complete fragment, the \fIbytesleft\fP field informs about
how many additional bytes are expected to arrive before this fragment is
complete.
.SH FLAGS
.IP CURLWS_TEXT
The buffer contains text data. Note that this makes a difference to WebSocket
but libcurl itself will not make any verification of the content or
precautions that you actually receive valid UTF-8 content.
.IP CURLWS_BINARY
This is binary data.
.IP CURLWS_CONT
This is not the final fragment of the message, it implies that there will be
another fragment coming as part of the same message.
.IP CURLWS_CLOSE
This transfer is now closed.
.IP CURLWS_PING
This as an incoming ping message, that expects a pong response.
.SH EXAMPLE
.nf

/* 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);

  /* m->flags tells us about the traffic */
}

{
  struct customdata custom;
  custom.easy = easy;
  custom.ptr = NULL;
  curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writecb);
  curl_easy_setopt(curl, CURLOPT_WRITEDATA, &custom);
}
.fi
.SH AVAILABILITY
Added in 7.86.0.
.SH RETURN VALUE
This function returns a pointer to a \fIcurl_ws_frame\fP 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.
.SH "SEE ALSO"
.BR curl_easy_setopt "(3), " curl_easy_getinfo "(3), "
.BR curl_ws_send "(3), " curl_ws_recv "(3), " libcurl-ws "(3), "