Artifactspublic-v0

curl

master
ply4 git calls231 ms289 KiB2 cachedprotocol v2
134 lines4.3 KiBRaw

NAME

curl_ws_recv - receive WebSocket data

SYNOPSIS

c
#include <curl/curl.h>

CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen,
                      size_t *recv, const struct curl_ws_frame **meta);

DESCRIPTION

Retrieves as much as possible of a received WebSocket frame into the buffer, but not more than buflen bytes. recv is set to the number of bytes actually stored.

If the function call is successful, the meta pointer gets set to point to a const struct curl_ws_frame that contains information about the received data. That struct must not be freed and its contents must not be relied upon anymore once another WebSocket function is called. See curl_ws_meta(3) for more details on that struct.

The application must check meta->bytesleft to determine whether the complete frame has been received. If more payload is pending, the application must call this function again with an updated buffer and buflen to resume receiving. This may for example happen when the data does not fit into the provided buffer or when not all frame data has been delivered over the network yet.

If the application wants to read the metadata without consuming any payload, it may call this function with a buflen of zero. Setting buffer to a NULL pointer is permitted in this case. Note that frames without payload are consumed by this action.

If the received message consists of multiple fragments, the CURLWS_CONT bit is set in all frames except the final one. The appropriate CURLWS_TEXT or CURLWS_BINARY flag is set in every frame, regardless whether it is the first fragment, an intermediate fragment or the final fragment. The application is responsible for reassembling fragmented messages. Special care must be taken to correctly handle control frames (i.e. CLOSE, PING and PONG) arriving in between consecutive fragments of a fragmented TEXT or BINARY message. See curl_ws_meta(3) for more details on CURLWS_CONT.

The WebSocket protocol consists of messages that can be delivered over the wire as one or more frames - but since a frame can be too large to buffer in memory, libcurl may need to deliver partial frames to the application. Fragments, or chunks, of frames.

%PROTOCOLS%

EXAMPLE

c
int main(void)
{
  char buffer[256];
  size_t offset = 0;
  CURLcode result = CURLE_OK;
  CURL *curl = curl_easy_init();

  curl_easy_setopt(curl, CURLOPT_URL, "wss://example.com/");
  curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L);
  /* start HTTPS connection and upgrade to WSS, then return control */
  curl_easy_perform(curl);

  /* Note: This example neglects fragmented messages.
     (CURLWS_CONT bit) A real application must handle them
     appropriately. */

  while(!result) {
    size_t recv;
    const struct curl_ws_frame *meta;
    result = curl_ws_recv(curl, buffer + offset,
                          sizeof(buffer) - offset, &recv,
                          &meta);
    offset += recv;

    if(result == CURLE_OK) {
      if(meta->bytesleft == 0)
        break; /* finished receiving */
      if(meta->bytesleft > (curl_off_t)(sizeof(buffer) - offset))
        result = CURLE_TOO_LARGE;
    }

    if(result == CURLE_AGAIN)
      /* in real application: wait for socket here, e.g. using select() */
      result = CURLE_OK;
  }

  curl_easy_cleanup(curl);
  return (int)result;
}

%AVAILABILITY%

RETURN VALUE

This function returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3) there can be an error message stored in the error buffer when non-zero is returned.

Returns CURLE_GOT_NOTHING if the associated connection is closed.

Instead of blocking, the function returns CURLE_AGAIN. The correct behavior is then to wait for the socket to signal readability before calling this function again.

Any other non-zero return value indicates an error. See the libcurl-errors(3) man page for the full list with descriptions.

Returns CURLE_GOT_NOTHING if the associated connection is closed.

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_ws_recv
5Section: 3
6Source: libcurl
7See-also:
8 - curl_easy_getinfo (3)
9 - curl_easy_perform (3)
10 - curl_easy_setopt (3)
11 - curl_ws_send (3)
12 - libcurl-ws (3)
13Protocol:
14 - WS
15Added-in: 7.86.0
16---
18# NAME
20curl_ws_recv - receive WebSocket data
22# SYNOPSIS
24~~~c
25#include <curl/curl.h>
27CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen,
28 size_t *recv, const struct curl_ws_frame **meta);
29~~~
31# DESCRIPTION
33Retrieves as much as possible of a received WebSocket frame into the *buffer*,
34but not more than *buflen* bytes. *recv* is set to the number of bytes
35actually stored.
37If the function call is successful, the *meta* pointer gets set to point to a
38*const struct curl_ws_frame* that contains information about the received
39data. That struct must not be freed and its contents must not be relied upon
40anymore once another WebSocket function is called. See curl_ws_meta(3) for
41more details on that struct.
43The application must check `meta->bytesleft` to determine whether the complete
44frame has been received. If more payload is pending, the application must call
45this function again with an updated *buffer* and *buflen* to resume receiving.
46This may for example happen when the data does not fit into the provided
47buffer or when not all frame data has been delivered over the network yet.
49If the application wants to read the metadata without consuming any payload,
50it may call this function with a *buflen* of zero. Setting *buffer* to a NULL
51pointer is permitted in this case. Note that frames without payload are
52consumed by this action.
54If the received message consists of multiple fragments, the *CURLWS_CONT* bit
55is set in all frames except the final one. The appropriate *CURLWS_TEXT* or
56*CURLWS_BINARY* flag is set in every frame, regardless whether it is the first
57fragment, an intermediate fragment or the final fragment. The application is
58responsible for reassembling fragmented messages. Special care must be taken
59to correctly handle control frames (i.e. CLOSE, PING and PONG) arriving in
60between consecutive fragments of a fragmented TEXT or BINARY message. See
61curl_ws_meta(3) for more details on *CURLWS_CONT*.
63The WebSocket protocol consists of *messages* that can be delivered over the
64wire as one or more *frames* - but since a frame can be too large to buffer in
65memory, libcurl may need to deliver partial frames to the application.
66Fragments, or chunks, of frames.
68# %PROTOCOLS%
70# EXAMPLE
72~~~c
73int main(void)
75 char buffer[256];
76 size_t offset = 0;
77 CURLcode result = CURLE_OK;
78 CURL *curl = curl_easy_init();
80 curl_easy_setopt(curl, CURLOPT_URL, "wss://example.com/");
81 curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L);
82 /* start HTTPS connection and upgrade to WSS, then return control */
83 curl_easy_perform(curl);
85 /* Note: This example neglects fragmented messages.
86 (CURLWS_CONT bit) A real application must handle them
87 appropriately. */
89 while(!result) {
90 size_t recv;
91 const struct curl_ws_frame *meta;
92 result = curl_ws_recv(curl, buffer + offset,
93 sizeof(buffer) - offset, &recv,
94 &meta);
95 offset += recv;
97 if(result == CURLE_OK) {
98 if(meta->bytesleft == 0)
99 break; /* finished receiving */
100 if(meta->bytesleft > (curl_off_t)(sizeof(buffer) - offset))
101 result = CURLE_TOO_LARGE;
102 }
104 if(result == CURLE_AGAIN)
105 /* in real application: wait for socket here, e.g. using select() */
106 result = CURLE_OK;
107 }
109 curl_easy_cleanup(curl);
110 return (int)result;
112~~~
114# %AVAILABILITY%
116# RETURN VALUE
118This function returns a CURLcode indicating success or error.
120CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
121libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
122there can be an error message stored in the error buffer when non-zero is
123returned.
125Returns **CURLE_GOT_NOTHING** if the associated connection is closed.
127Instead of blocking, the function returns **CURLE_AGAIN**. The correct
128behavior is then to wait for the socket to signal readability before calling
129this function again.
131Any other non-zero return value indicates an error. See the libcurl-errors(3)
132man page for the full list with descriptions.
134Returns **CURLE_GOT_NOTHING** if the associated connection is closed.
Diagnostics4 git calls · 231 ms
CallStatusSizeTime0231 ms
discover200152 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
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 · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=227
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=2
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 KiB227 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=2118
git.response.cache=MISS
git.response.duration_ms=227
git.fetch.wants=0b56c578bae58f7cc0e4588a01a7392824e13671
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=2118
git.pkt.payload.max=2097
git.sideband.band1.bytes=2096
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
a5e36a3c281e724e
Request
4452a6d7…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format