Artifactspublic-v0

curl

master
ply4 git calls51 ms289 KiB3 cachedprotocol v2
183 lines5.6 KiBRaw

NAME

curl_mime_data_cb - set a callback-based data source for a mime part's body

SYNOPSIS

c
#include <curl/curl.h>

size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);

int seekfunc(void *arg, curl_off_t offset, int origin);

void freefunc(void *arg);

CURLcode curl_mime_data_cb(curl_mimepart *part, curl_off_t datasize,
                           curl_read_callback readfunc,
                           curl_seek_callback seekfunc,
                           curl_free_callback freefunc, void *arg);

DESCRIPTION

curl_mime_data_cb(3) sets the data source of a mime part's body content from a data read callback function.

part is the part's to assign contents to.

datasize is the number of bytes the read callback is expected to provide.

readfunc is a pointer to a data read callback function, with a signature as shown by the above prototype. It may not be set to NULL.

seekfunc is a pointer to a seek callback function, with a signature as shown by the above prototype. This function is used when resending data (i.e.: after a redirect); this pointer may be set to NULL, in which case a resend might not be not possible.

freefunc is a pointer to a user resource freeing callback function, with a signature as shown by the above prototype. If no resource is to be freed, it may safely be set to NULL. This function is called upon mime structure freeing.

arg is a user defined argument to callback functions.

The read callback function gets called by libcurl as soon as it needs to read data in order to send it to the peer - like if you ask it to upload or post data to the server. The data area pointed at by the pointer buffer should be filled up with at most size multiplied with nitems number of bytes by your function.

Your read function must then return the actual number of bytes that it stored in that memory area. Returning 0 signals end-of-file to the library and cause it to stop the current transfer.

If you stop the current transfer by returning 0 "pre-maturely" (i.e. before the server expected it, like when you have said you intend to upload N bytes and yet you upload less than N bytes), you may experience that the server "hangs" waiting for the rest of the data that does not come.

The read callback may return CURL_READFUNC_ABORT to stop the current operation immediately, resulting in a CURLE_ABORTED_BY_CALLBACK error code from the transfer.

The callback can return CURL_READFUNC_PAUSE to cause reading from this connection to pause. See curl_easy_pause(3) for further details.

The seek function gets called by libcurl to rewind input stream data or to seek to a certain position. The function shall work like fseek(3) or lseek(3) and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for origin, although libcurl currently only passes SEEK_SET.

The callback function must return CURL_SEEKFUNC_OK on success, CURL_SEEKFUNC_FAIL to cause the upload operation to fail or CURL_SEEKFUNC_CANTSEEK to indicate that while the seek failed, libcurl is free to work around the problem if possible. The latter can sometimes be done by instead reading from the input or similar.

Care must be taken if the part is bound to a curl easy handle that is later duplicated: the arg pointer argument is also duplicated, resulting in the pointed item to be shared between the original and the copied handle. In particular, special attention should be given to the freefunc procedure code since it then gets called twice with the same argument.

%PROTOCOLS%

EXAMPLE

Sending a huge data string causes the same amount of memory to be allocated: to avoid overhead resources consumption, one might want to use a callback source to avoid data duplication. In this case, original data must be retained until after the transfer terminates.

c
#include <string.h> /* for memcpy */
static char hugedata[512000];

struct ctl {
  char *buffer;
  curl_off_t size;
  curl_off_t position;
};

static size_t read_callback(char *buffer, size_t size, size_t nitems,
                            void *arg)
{
  struct ctl *p = (struct ctl *)arg;
  size_t sz = (size_t)(p->size - p->position);

  nitems *= size;
  if(sz > nitems)
    sz = nitems;
  if(sz)
    memcpy(buffer, p->buffer + p->position, sz);
  p->position += sz;
  return sz;
}

static int seek_callback(void *arg, curl_off_t offset, int origin)
{
  struct ctl *p = (struct ctl *)arg;

  switch(origin) {
  case SEEK_END:
    offset += p->size;
    break;
  case SEEK_CUR:
    offset += p->position;
    break;
  default:
    break;
  }

  if(offset < 0)
    return CURL_SEEKFUNC_FAIL;
  p->position = offset;
  return CURL_SEEKFUNC_OK;
}

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    curl_mime *mime = curl_mime_init(curl);
    curl_mimepart *part = curl_mime_addpart(mime);
    struct ctl hugectl;

    hugectl.buffer = hugedata;
    hugectl.size = sizeof(hugedata);
    hugectl.position = 0;
    curl_mime_data_cb(part, hugectl.size, read_callback,
                      seek_callback, NULL, &hugectl);
  }
}

%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.

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_mime_data_cb
5Section: 3
6Source: libcurl
7See-also:
8 - curl_easy_duphandle (3)
9 - curl_mime_addpart (3)
10 - curl_mime_data (3)
11 - curl_mime_name (3)
12Protocol:
13 - HTTP
14 - IMAP
15 - SMTP
16Added-in: 7.56.0
17---
19# NAME
21curl_mime_data_cb - set a callback-based data source for a mime part's body
23# SYNOPSIS
25~~~c
26#include <curl/curl.h>
28size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);
30int seekfunc(void *arg, curl_off_t offset, int origin);
32void freefunc(void *arg);
34CURLcode curl_mime_data_cb(curl_mimepart *part, curl_off_t datasize,
35 curl_read_callback readfunc,
36 curl_seek_callback seekfunc,
37 curl_free_callback freefunc, void *arg);
38~~~
40# DESCRIPTION
42curl_mime_data_cb(3) sets the data source of a mime part's body content
43from a data read callback function.
45*part* is the part's to assign contents to.
47*datasize* is the number of bytes the read callback is expected to provide.
49*readfunc* is a pointer to a data read callback function, with a signature
50as shown by the above prototype. It may not be set to NULL.
52*seekfunc* is a pointer to a seek callback function, with a signature as
53shown by the above prototype. This function is used when resending data (i.e.:
54after a redirect); this pointer may be set to NULL, in which case a resend
55might not be not possible.
57*freefunc* is a pointer to a user resource freeing callback function, with
58a signature as shown by the above prototype. If no resource is to be freed, it
59may safely be set to NULL. This function is called upon mime structure
60freeing.
62*arg* is a user defined argument to callback functions.
64The read callback function gets called by libcurl as soon as it needs to
65read data in order to send it to the peer - like if you ask it to upload or
66post data to the server. The data area pointed at by the pointer *buffer*
67should be filled up with at most *size* multiplied with *nitems* number
68of bytes by your function.
70Your read function must then return the actual number of bytes that it stored
71in that memory area. Returning 0 signals end-of-file to the library and cause
72it to stop the current transfer.
74If you stop the current transfer by returning 0 "pre-maturely" (i.e. before
75the server expected it, like when you have said you intend to upload N bytes
76and yet you upload less than N bytes), you may experience that the server
77"hangs" waiting for the rest of the data that does not come.
79The read callback may return *CURL_READFUNC_ABORT* to stop the current
80operation immediately, resulting in a *CURLE_ABORTED_BY_CALLBACK* error
81code from the transfer.
83The callback can return *CURL_READFUNC_PAUSE* to cause reading from this
84connection to pause. See curl_easy_pause(3) for further details.
86The seek function gets called by libcurl to rewind input stream data or to
87seek to a certain position. The function shall work like fseek(3) or lseek(3)
88and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for *origin*,
89although libcurl currently only passes SEEK_SET.
91The callback function must return *CURL_SEEKFUNC_OK* on success,
92*CURL_SEEKFUNC_FAIL* to cause the upload operation to fail or
93*CURL_SEEKFUNC_CANTSEEK* to indicate that while the seek failed, libcurl
94is free to work around the problem if possible. The latter can sometimes be
95done by instead reading from the input or similar.
97Care must be taken if the part is bound to a curl easy handle that is later
98duplicated: the *arg* pointer argument is also duplicated, resulting in
99the pointed item to be shared between the original and the copied handle. In
100particular, special attention should be given to the *freefunc* procedure
101code since it then gets called twice with the same argument.
103# %PROTOCOLS%
105# EXAMPLE
107Sending a huge data string causes the same amount of memory to be allocated:
108to avoid overhead resources consumption, one might want to use a callback
109source to avoid data duplication. In this case, original data must be retained
110until after the transfer terminates.
111~~~c
112#include <string.h> /* for memcpy */
113static char hugedata[512000];
115struct ctl {
116 char *buffer;
117 curl_off_t size;
118 curl_off_t position;
119};
121static size_t read_callback(char *buffer, size_t size, size_t nitems,
122 void *arg)
124 struct ctl *p = (struct ctl *)arg;
125 size_t sz = (size_t)(p->size - p->position);
127 nitems *= size;
128 if(sz > nitems)
129 sz = nitems;
130 if(sz)
131 memcpy(buffer, p->buffer + p->position, sz);
132 p->position += sz;
133 return sz;
136static int seek_callback(void *arg, curl_off_t offset, int origin)
138 struct ctl *p = (struct ctl *)arg;
140 switch(origin) {
141 case SEEK_END:
142 offset += p->size;
143 break;
144 case SEEK_CUR:
145 offset += p->position;
146 break;
147 default:
148 break;
149 }
151 if(offset < 0)
152 return CURL_SEEKFUNC_FAIL;
153 p->position = offset;
154 return CURL_SEEKFUNC_OK;
157int main(void)
159 CURL *curl = curl_easy_init();
160 if(curl) {
161 curl_mime *mime = curl_mime_init(curl);
162 curl_mimepart *part = curl_mime_addpart(mime);
163 struct ctl hugectl;
165 hugectl.buffer = hugedata;
166 hugectl.size = sizeof(hugedata);
167 hugectl.position = 0;
168 curl_mime_data_cb(part, hugectl.size, read_callback,
169 seek_callback, NULL, &hugectl);
170 }
172~~~
174# %AVAILABILITY%
176# RETURN VALUE
178This function returns a CURLcode indicating success or error.
180CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
181libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
182there can be an error message stored in the error buffer when non-zero is
183returned.
Diagnostics4 git calls · 51 ms
CallStatusSizeTime051 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
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 · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
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 · hit29 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=29
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.5 KiB · hit19 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=19
git.response.bytes=2518
git.response.cache=HIT
git.response.duration_ms=19
git.fetch.wants=ba1a34ac68048f6a698352b94cab1d43eb48e8c1
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=2518
git.pkt.payload.max=2497
git.sideband.band1.bytes=2496
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
a5e348084f2e4652
Request
003bca2e…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format