curl/docs/libcurl/curl_ws_meta.3

.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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 7.85.0" "libcurl Manual"
.SH NAME
curl_ws_meta - meta data WebSocket information
.SH SYNOPSIS
.nf
#include <curl/easy.h>

struct curl_ws_metadata {
  int age;       /* zero */
  int recvflags; /* See the CURLWS_* defines */
};

struct curl_ws_metadata *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 data.

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 recvflags
This is a bitmask with the exact same meaning as the \fBrecvflags\fP
documented for \fIcurl_ws_recv(3)\fP.
.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;
  struct curl_ws_metadata *m = curl_ws_meta(c->easy);

  /* m->recvflags 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 metadata struct with 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), "
.BR curl_easy_getinfo "(3), "
.BR curl_ws_send "(3), " curl_ws_recv "(3), "