luo980/curl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

curl_ws_meta.3: added docs

Browse Source
This commit is contained in:
Daniel Stenberg 2022-09-09 15:11:14 +02:00
parent 664249d095
commit 07cb887ed3
No known key found for this signature in database
GPG Key ID: 5CC908FDB71E12C2
3 changed files with 97 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/libcurl/Makefile.inc
View File

@ -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 \

87
docs/libcurl/curl_ws_meta.3 Normal file
View File

@ -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), "

7
include/curl/websockets.h
View File

@ -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 */