Artifactspublic-v0

curl

master
ply4 git calls175 ms289 KiB2 cachedprotocol v2
182 lines4.7 KiBRaw

NAME

curl_ws_meta - meta data WebSocket information

SYNOPSIS

c
#include <curl/curl.h>

const struct curl_ws_frame *curl_ws_meta(CURL *curl);

DESCRIPTION

When the write callback (CURLOPT_WRITEFUNCTION(3)) is invoked on received WebSocket traffic, curl_ws_meta(3) 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 curl_ws_meta(3) need to pass it on to the callback on its own.

WebSocket messages are split into frames. A WebSocket message can be made up of an arbitrary number of frames. Each WebSocket frame payload can be up to 2^63-1 bytes. When libcurl delivers WebSocket data, it splits each frame into chunks; each chunk is therefore part of a frame, or at most a full frame.

Each callback delivers data for a single chunk that is then part of a single frame.

struct curl_ws_frame

c
struct curl_ws_frame {
  int age;
  int flags;
  curl_off_t offset;
  curl_off_t bytesleft;
  size_t len;
};

age

This field specify the age of this struct. It is always zero for now.

flags

This is a bitmask with individual bits set that describes the WebSocket data. See the list below.

offset

When this chunk is a continuation of frame data already delivered in a previous callback, this is the offset into the complete frame payload where this chunk's data belongs.

bytesleft

When this is not a complete frame nor the last chunk for a frame, the bytesleft field informs about how many additional bytes are expected to arrive before this frame is complete.

len

The length of the current data chunk.

FLAGS

The message type flags (CURLWS_TEXT/BINARY/CLOSE/PING/PONG) are mutually exclusive.

CURLWS_TEXT

This is a message with 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.

CURLWS_BINARY

This is a message with binary data.

CURLWS_CLOSE

This is a close message. No more data follows.

It may contain a 2-byte unsigned integer in network byte order that indicates the close reason and may additionally contain up to 123 bytes of further textual payload for a total of at most 125 bytes. libcurl does not verify that the textual description is valid UTF-8.

CURLWS_PING

This is a ping message. It may contain up to 125 bytes of payload text. libcurl does not verify that the payload is valid UTF-8.

Upon receiving a ping message, libcurl automatically responds with a pong message unless the CURLWS_NOAUTOPONG or CURLWS_RAW_MODE bit of CURLOPT_WS_OPTIONS(3) is set.

CURLWS_PONG

This is a pong message. It may contain up to 125 bytes of payload text. libcurl does not verify that the payload is valid UTF-8.

CURLWS_CONT

Can only occur in conjunction with CURLWS_TEXT or CURLWS_BINARY.

This is not the final frame of the message, it implies that there is another frame coming as part of the same message. The application must reassemble the frames to receive the complete message.

Only a single multi-frame message can be transmitted at a time, but it may be interrupted by CURLWS_CLOSE, CURLWS_PING or CURLWS_PONG frames.

%PROTOCOLS%

EXAMPLE

c

/* we pass a pointer to this struct to the callback */
struct customdata {
  CURL *easy;
  void *ptr;
};

static size_t writecb(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);

  printf("flags: %x\n", (unsigned int)m->flags);
  return 0;
}

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    struct customdata custom;
    custom.easy = curl;
    custom.ptr = NULL;
    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writecb);
    curl_easy_setopt(curl, CURLOPT_WRITEDATA, &custom);

    curl_easy_perform(curl);
  }
  return 0;
}

%AVAILABILITY%

RETURN VALUE

This function returns a pointer to a curl_ws_frame 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.

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_ws_meta
5Section: 3
6Source: libcurl
7See-also:
8 - curl_easy_getinfo (3)
9 - curl_easy_setopt (3)
10 - curl_ws_recv (3)
11 - curl_ws_send (3)
12 - libcurl-ws (3)
13Protocol:
14 - WS
15Added-in: 7.86.0
16---
18# NAME
20curl_ws_meta - meta data WebSocket information
22# SYNOPSIS
24~~~c
25#include <curl/curl.h>
27const struct curl_ws_frame *curl_ws_meta(CURL *curl);
28~~~
30# DESCRIPTION
32When the write callback (CURLOPT_WRITEFUNCTION(3)) is invoked on received
33WebSocket traffic, curl_ws_meta(3) can be called from within the callback to
34provide additional information about the current frame.
36This function only works from within the callback, and only when receiving
37WebSocket data.
39This function requires an easy handle as input argument for libcurl to know
40what transfer the question is about, but as there is no such pointer provided
41to the callback by libcurl itself, applications that want to use
42curl_ws_meta(3) need to pass it on to the callback on its own.
44WebSocket messages are split into *frames*. A WebSocket message can be made up
45of an arbitrary number of frames. Each WebSocket frame payload can be up to
462^63-1 bytes. When libcurl delivers WebSocket data, it splits each frame into
47*chunks*; each chunk is therefore part of a frame, or at most a full frame.
49Each callback delivers data for a single chunk that is then part of a single
50frame.
52# struct curl_ws_frame
54~~~c
55struct curl_ws_frame {
56 int age;
57 int flags;
58 curl_off_t offset;
59 curl_off_t bytesleft;
60 size_t len;
61};
62~~~
64## `age`
66This field specify the age of this struct. It is always zero for now.
68## `flags`
70This is a bitmask with individual bits set that describes the WebSocket data.
71See the list below.
73## `offset`
75When this chunk is a continuation of frame data already delivered in a
76previous callback, this is the offset into the complete frame payload where
77this chunk's data belongs.
79## `bytesleft`
81When this is not a complete frame nor the last chunk for a frame, the
82*bytesleft* field informs about how many additional bytes are expected to
83arrive before this frame is complete.
85## `len`
87The length of the current data chunk.
89# FLAGS
91The *message type* flags (CURLWS_TEXT/BINARY/CLOSE/PING/PONG) are mutually
92exclusive.
94## CURLWS_TEXT
96This is a message with text data. Note that this makes a difference to WebSocket
97but libcurl itself does not make any verification of the content or
98precautions that you actually receive valid UTF-8 content.
100## CURLWS_BINARY
102This is a message with binary data.
104## CURLWS_CLOSE
106This is a close message. No more data follows.
108It may contain a 2-byte unsigned integer in network byte order that indicates
109the close reason and may additionally contain up to 123 bytes of further
110textual payload for a total of at most 125 bytes. libcurl does not verify that
111the textual description is valid UTF-8.
113## CURLWS_PING
115This is a ping message. It may contain up to 125 bytes of payload text.
116libcurl does not verify that the payload is valid UTF-8.
118Upon receiving a ping message, libcurl automatically responds with a pong
119message unless the **CURLWS_NOAUTOPONG** or **CURLWS_RAW_MODE** bit of
120CURLOPT_WS_OPTIONS(3) is set.
122## CURLWS_PONG
124This is a pong message. It may contain up to 125 bytes of payload text.
125libcurl does not verify that the payload is valid UTF-8.
127## CURLWS_CONT
129Can only occur in conjunction with CURLWS_TEXT or CURLWS_BINARY.
131This is not the final *frame* of the message, it implies that there is another
132*frame* coming as part of the same message. The application must reassemble
133the frames to receive the complete message.
135Only a single multi-frame message can be transmitted at a time, but it may be
136interrupted by CURLWS_CLOSE, CURLWS_PING or CURLWS_PONG frames.
138# %PROTOCOLS%
140# EXAMPLE
142~~~c
144/* we pass a pointer to this struct to the callback */
145struct customdata {
146 CURL *easy;
147 void *ptr;
148};
150static size_t writecb(char *buffer, size_t size, size_t nitems, void *p)
152 struct customdata *c = (struct customdata *)p;
153 const struct curl_ws_frame *m = curl_ws_meta(c->easy);
155 printf("flags: %x\n", (unsigned int)m->flags);
156 return 0;
159int main(void)
161 CURL *curl = curl_easy_init();
162 if(curl) {
163 struct customdata custom;
164 custom.easy = curl;
165 custom.ptr = NULL;
166 curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writecb);
167 curl_easy_setopt(curl, CURLOPT_WRITEDATA, &custom);
169 curl_easy_perform(curl);
170 }
171 return 0;
173~~~
175# %AVAILABILITY%
177# RETURN VALUE
179This function returns a pointer to a *curl_ws_frame* struct with read-only
180information that is valid for this specific callback invocation. If it cannot
181return this information, or if the function is called in the wrong context, it
182returns NULL.
Diagnostics4 git calls · 175 ms
CallStatusSizeTime0175 ms
discover200152 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=2
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit25 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=25
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2002.1 KiB148 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=148
git.response.bytes=2193
git.response.cache=MISS
git.response.duration_ms=148
git.fetch.wants=6fd44ac6bfda4ca4fb8fec29328b72c985d97597
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2193
git.pkt.payload.max=2172
git.sideband.band1.bytes=2171
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e35044ec9b14c2
Request
6fbc9b97…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format