diff options
| -rw-r--r-- | docs/libcurl/Makefile.inc | 3 | ||||
| -rw-r--r-- | docs/libcurl/curl_ws_meta.3 | 87 | ||||
| -rw-r--r-- | include/curl/websockets.h | 7 |
3 files changed, 97 insertions, 0 deletions
diff --git a/docs/libcurl/Makefile.inc b/docs/libcurl/Makefile.inc index f1e79ab50..3e62ff0b0 100644 --- a/docs/libcurl/Makefile.inc +++ b/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 \ diff --git a/docs/libcurl/curl_ws_meta.3 b/docs/libcurl/curl_ws_meta.3 new file mode 100644 index 000000000..111de986e --- /dev/null +++ b/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), " diff --git a/include/curl/websockets.h b/include/curl/websockets.h index ffb9c19b8..dde0987e4 100644 --- a/include/curl/websockets.h +++ b/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 */ |