CURLOPT_CHUNK_BGN_FUNCTION(3)

1CURLOPT_CHUNK_BGN_FUNCTION(3)       libcurl      CURLOPT_CHUNK_BGN_FUNCTION(3)
2
3
4

NAME

6       CURLOPT_CHUNK_BGN_FUNCTION  - callback before a transfer with FTP wild‐
7       card match
8

SYNOPSIS

10       #include <curl/curl.h>
11
12       struct curl_fileinfo {
13         char *filename;
14         curlfiletype filetype;
15         time_t time;   /* always zero! */
16         unsigned int perm;
17         int uid;
18         int gid;
19         curl_off_t size;
20         long int hardlinks;
21
22         struct {
23           /* If some of these fields is not NULL, it is a pointer to b_data. */
24           char *time;
25           char *perm;
26           char *user;
27           char *group;
28           char *target; /* pointer to the target filename of a symlink */
29         } strings;
30
31         unsigned int flags;
32
33         /* used internally */
34         char *b_data;
35         size_t b_size;
36         size_t b_used;
37       };
38
39       long chunk_bgn_callback(const void *transfer_info, void *ptr,
40                               int remains);
41
42       CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_BGN_FUNCTION,
43                                 chunk_bgn_callback);
44

DESCRIPTION

46       Pass a pointer to your callback function, which should match the proto‐
47       type shown above.
48
49       This  callback  function  gets  called  by libcurl before a part of the
50       stream is going to be transferred (if the transfer supports chunks).
51
52       The transfer_info pointer will point to a curl_fileinfo struct with de‐
53       tails about the file that is about to get transferred.
54
55       This  callback makes sense only when using the CURLOPT_WILDCARDMATCH(3)
56       option for now.
57
58       The target of transfer_info parameter is a  "feature  depended"  struc‐
59       ture. For the FTP wildcard download, the target is curl_fileinfo struc‐
60       ture (see curl/curl.h).  The parameter ptr is a pointer given  by  CUR‐
61       LOPT_CHUNK_DATA(3). The parameter remains contains number of chunks re‐
62       maining per the transfer. If the feature is not available, the  parame‐
63       ter has zero value.
64
65       Return     CURL_CHUNK_BGN_FUNC_OK     if     everything     is    fine,
66       CURL_CHUNK_BGN_FUNC_SKIP if you want to  skip  the  concrete  chunk  or
67       CURL_CHUNK_BGN_FUNC_FAIL  to  tell  libcurl  to  stop if some error oc‐
68       curred.
69

DEFAULT

71       NULL
72

PROTOCOLS

74       FTP
75

EXAMPLE

77       static long file_is_coming(struct curl_fileinfo *finfo,
78                                  struct callback_data *data,
79                                  int remains)
80       {
81         printf("%3d %40s %10luB ", remains, finfo->filename,
82                (unsigned long)finfo->size);
83
84         switch(finfo->filetype) {
85         case CURLFILETYPE_DIRECTORY:
86           printf(" DIR\n");
87           break;
88         case CURLFILETYPE_FILE:
89           printf("FILE ");
90           break;
91         default:
92           printf("OTHER\n");
93           break;
94         }
95
96         if(finfo->filetype == CURLFILETYPE_FILE) {
97           /* do not transfer files >= 50B */
98           if(finfo->size > 50) {
99             printf("SKIPPED\n");
100             return CURL_CHUNK_BGN_FUNC_SKIP;
101           }
102
103           data->output = fopen(finfo->filename, "wb");
104           if(!data->output) {
105             return CURL_CHUNK_BGN_FUNC_FAIL;
106           }
107         }
108
109         return CURL_CHUNK_BGN_FUNC_OK;
110       }
111
112       int main()
113       {
114         /* data for callback */
115         struct callback_data callback_info;
116
117         /* callback is called before download of concrete file started */
118         curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming);
119         curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info);
120       }
121

AVAILABILITY

123       This was added in 7.21.0
124

RETURN VALUE

126       Returns CURLE_OK if the option is supported,  and  CURLE_UNKNOWN_OPTION
127       if not.
128