120 lines
4.2 KiB
Groff
120 lines
4.2 KiB
Groff
|
.\" **************************************************************************
|
||
|
|
.\" * _ _ ____ _
|
||
|
|
.\" * 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 "August 22, 2023" "libcurl 8.3.0" "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 does 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 is
|
||
|
|
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), "
|