Artifactspublic-v0

curl

master
ply4 git calls123 ms289 KiB2 cachedprotocol v2
137 lines4.2 KiBRaw

NAME

curl_ws_send - send WebSocket data

SYNOPSIS

c
#include <curl/curl.h>

CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen,
                      size_t *sent, curl_off_t fragsize,
                      unsigned int flags);

DESCRIPTION

Send the specific message chunk over an established WebSocket connection. buffer must point to a valid memory location containing (at least) buflen bytes of payload memory.

sent is set to the number of payload bytes actually sent. If the return value is CURLE_OK but sent is less than the given buflen, libcurl was unable to consume the complete payload in a single call. In this case the application must call this function again until all payload is processed. buffer and buflen must be updated on every following invocation to only point to the remaining piece of the payload.

fragsize should always be set to zero unless a (huge) frame shall be sent using multiple calls with partial content per call explicitly. In that case you must set the CURLWS_OFFSET bit and set the fragsize as documented in the section on CURLWS_OFFSET below.

flags must contain at least one flag indicating the type of the message. To send a fragmented message consisting of multiple frames, additionally set the CURLWS_CONT bit in all frames except the final one. The appropriate message type bit should be set in every frame of a fragmented message without exemption. Omitting the message type for continuation frames of a fragmented message is only supported for backwards compatibility and highly discouraged.

For more details on the supported flags see below and in curl_ws_meta(3).

If CURLWS_RAW_MODE is enabled in CURLOPT_WS_OPTIONS(3), the flags argument should be set to 0.

Warning: while it is possible to invoke this function from a callback, such a call is blocking in this situation, e.g. only returns after all data has been sent or an error is encountered.

FLAGS

Supports all flags documented in curl_ws_meta(3) and additionally the following flags.

CURLWS_OFFSET

The provided data is only a partial frame and there is more coming in a following call to curl_ws_send(). When sending only a piece of the frame like this, the fragsize must be provided with the total expected frame size in the first call and must be zero in all subsequent calls.

%PROTOCOLS%

EXAMPLE

c
#include <string.h> /* for strlen */

int main(void)
{
  static const char *buffer = "PAYLOAD";
  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);

  while(!result) {
    size_t sent;
    result = curl_ws_send(curl, buffer + offset,
                          strlen(buffer) - offset, &sent,
                          0, CURLWS_TEXT);
    offset += sent;

    if(result == CURLE_OK) {
      if(offset == strlen(buffer))
        break; /* finished sending */
    }

    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.

Instead of blocking, the function returns CURLE_AGAIN. The correct behavior is then to wait until the socket is writable before calling this function again. Retry with the same data and length.

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

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_ws_send
5Section: 3
6Source: libcurl
7See-also:
8 - curl_easy_getinfo (3)
9 - curl_easy_perform (3)
10 - curl_easy_setopt (3)
11 - curl_ws_recv (3)
12 - curl_ws_start_frame (3)
13 - libcurl-ws (3)
14Protocol:
15 - WS
16Added-in: 7.86.0
17---
19# NAME
21curl_ws_send - send WebSocket data
23# SYNOPSIS
25~~~c
26#include <curl/curl.h>
28CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen,
29 size_t *sent, curl_off_t fragsize,
30 unsigned int flags);
31~~~
33# DESCRIPTION
35Send the specific message chunk over an established WebSocket
36connection. *buffer* must point to a valid memory location containing
37(at least) *buflen* bytes of payload memory.
39*sent* is set to the number of payload bytes actually sent. If the return value
40is **CURLE_OK** but *sent* is less than the given *buflen*, libcurl was unable
41to consume the complete payload in a single call. In this case the application
42must call this function again until all payload is processed. *buffer* and
43*buflen* must be updated on every following invocation to only point to the
44remaining piece of the payload.
46*fragsize* should always be set to zero unless a (huge) frame shall be sent
47using multiple calls with partial content per call explicitly. In that
48case you must set the *CURLWS_OFFSET* bit and set the *fragsize* as documented
49in the section on *CURLWS_OFFSET* below.
51*flags* must contain at least one flag indicating the type of the message.
52To send a fragmented message consisting of multiple frames, additionally set
53the *CURLWS_CONT* bit in all frames except the final one. The appropriate
54message type bit should be set in every frame of a fragmented message without
55exemption. Omitting the message type for continuation frames of a fragmented
56message is only supported for backwards compatibility and highly discouraged.
58For more details on the supported flags see below and in curl_ws_meta(3).
60If *CURLWS_RAW_MODE* is enabled in CURLOPT_WS_OPTIONS(3), the
61*flags* argument should be set to 0.
63Warning: while it is possible to invoke this function from a callback,
64such a call is blocking in this situation, e.g. only returns after all data
65has been sent or an error is encountered.
67# FLAGS
69Supports all flags documented in curl_ws_meta(3) and additionally the following
70flags.
72## CURLWS_OFFSET
74The provided data is only a partial frame and there is more coming in a
75following call to *curl_ws_send()*. When sending only a piece of the
76frame like this, the *fragsize* must be provided with the total
77expected frame size in the first call and must be zero in all subsequent
78calls.
80# %PROTOCOLS%
82# EXAMPLE
84~~~c
85#include <string.h> /* for strlen */
87int main(void)
89 static const char *buffer = "PAYLOAD";
90 size_t offset = 0;
91 CURLcode result = CURLE_OK;
92 CURL *curl = curl_easy_init();
94 curl_easy_setopt(curl, CURLOPT_URL, "wss://example.com/");
95 curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L);
96 /* start HTTPS connection and upgrade to WSS, then return control */
97 curl_easy_perform(curl);
99 while(!result) {
100 size_t sent;
101 result = curl_ws_send(curl, buffer + offset,
102 strlen(buffer) - offset, &sent,
103 0, CURLWS_TEXT);
104 offset += sent;
106 if(result == CURLE_OK) {
107 if(offset == strlen(buffer))
108 break; /* finished sending */
109 }
111 if(result == CURLE_AGAIN)
112 /* in real application: wait for socket here, e.g. using select() */
113 result = CURLE_OK;
114 }
116 curl_easy_cleanup(curl);
117 return (int)result;
119~~~
121# %AVAILABILITY%
123# RETURN VALUE
125This function returns a CURLcode indicating success or error.
127CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
128libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
129there can be an error message stored in the error buffer when non-zero is
130returned.
132Instead of blocking, the function returns **CURLE_AGAIN**. The correct
133behavior is then to wait until the socket is writable before calling
134this function again. Retry with the same data and length.
136Any other non-zero return value indicates an error. See the libcurl-errors(3)
137man page for the full list with descriptions.
Diagnostics4 git calls · 123 ms
CallStatusSizeTime0123 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=1
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=118
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.0 KiB118 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=2091
git.response.cache=MISS
git.response.duration_ms=118
git.fetch.wants=64f336a93169176ff38a2fcc0dc9c98e88c54b74
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=2091
git.pkt.payload.max=2070
git.sideband.band1.bytes=2069
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
a5e32a9d2d845094
Request
3c574e91…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format