curl_ws_meta.3: added docs

docs/libcurl/Makefile.inc

@@ -102,6 +102,9 @@ man_MANS = \
  curl_url_strerror.3 \
  curl_version.3 \
  curl_version_info.3 \
+ curl_ws_meta.3 \
+ curl_ws_recv.3 \
+ curl_ws_send.3 \
  libcurl-easy.3 \
  libcurl-env.3 \
  libcurl-errors.3 \

docs/libcurl/curl_ws_meta.3

@@ -0,0 +1,87 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  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 EXAMPLE
+.nf
+
+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;
+  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), "

include/curl/websockets.h

@@ -65,4 +65,11 @@ typedef ssize_t (*curl_ws_write_callback)(void *userdata, char *data,
 /* bits for the CURLOPT_WS_OPTIONS bitmask: */
 #define CURLWS_RAW_MODE (1<<0)
 
+struct curl_ws_metadata {
+  int age;       /* zero */
+  int recvflags; /* See the CURLWS_* defines */
+};
+
+struct curl_ws_metadata *curl_ws_meta(CURL *curl);
+
 #endif /* CURLINC_WEBSOCKETS_H */