1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_CHUNK_BGN_FUNCTION
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_CHUNK_END_FUNCTION (3)
9  - CURLOPT_WILDCARDMATCH (3)
10Protocol:
11  - FTP
12---
13
14# NAME
15
16CURLOPT_CHUNK_BGN_FUNCTION - callback before a transfer with FTP wildcard match
17
18# SYNOPSIS
19
20~~~c
21#include <curl/curl.h>
22
23struct curl_fileinfo {
24  char *filename;
25  curlfiletype filetype;
26  time_t time;   /* always zero! */
27  unsigned int perm;
28  int uid;
29  int gid;
30  curl_off_t size;
31  long int hardlinks;
32
33  struct {
34    /* If some of these fields is not NULL, it is a pointer to b_data. */
35    char *time;
36    char *perm;
37    char *user;
38    char *group;
39    char *target; /* pointer to the target filename of a symlink */
40  } strings;
41
42  unsigned int flags;
43
44  /* used internally */
45  char *b_data;
46  size_t b_size;
47  size_t b_used;
48};
49
50long chunk_bgn_callback(const void *transfer_info, void *ptr,
51                        int remains);
52
53CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_BGN_FUNCTION,
54                          chunk_bgn_callback);
55~~~
56
57# DESCRIPTION
58
59Pass a pointer to your callback function, which should match the prototype
60shown above.
61
62This callback function gets called by libcurl before a part of the stream is
63going to be transferred (if the transfer supports chunks).
64
65The *transfer_info* pointer points to a **curl_fileinfo** struct with
66details about the file that is about to get transferred.
67
68This callback makes sense only when using the CURLOPT_WILDCARDMATCH(3)
69option for now.
70
71The target of transfer_info parameter is a "feature depended" structure. For
72the FTP wildcard download, the target is **curl_fileinfo** structure (see
73*curl/curl.h*). The parameter *ptr* is a pointer given by
74CURLOPT_CHUNK_DATA(3). The parameter remains contains number of chunks
75remaining per the transfer. If the feature is not available, the parameter has
76zero value.
77
78Return *CURL_CHUNK_BGN_FUNC_OK* if everything is fine,
79*CURL_CHUNK_BGN_FUNC_SKIP* if you want to skip the concrete chunk or
80*CURL_CHUNK_BGN_FUNC_FAIL* to tell libcurl to stop if some error occurred.
81
82# DEFAULT
83
84NULL
85
86# EXAMPLE
87
88~~~c
89#include <stdio.h>
90
91struct callback_data {
92   FILE *output;
93};
94
95static long file_is_coming(struct curl_fileinfo *finfo,
96                           void *ptr,
97                           int remains)
98{
99  struct callback_data *data = ptr;
100  printf("%3d %40s %10luB ", remains, finfo->filename,
101         (unsigned long)finfo->size);
102
103  switch(finfo->filetype) {
104  case CURLFILETYPE_DIRECTORY:
105    printf(" DIR\n");
106    break;
107  case CURLFILETYPE_FILE:
108    printf("FILE ");
109    break;
110  default:
111    printf("OTHER\n");
112    break;
113  }
114
115  if(finfo->filetype == CURLFILETYPE_FILE) {
116    /* do not transfer files >= 50B */
117    if(finfo->size > 50) {
118      printf("SKIPPED\n");
119      return CURL_CHUNK_BGN_FUNC_SKIP;
120    }
121
122    data->output = fopen(finfo->filename, "wb");
123    if(!data->output) {
124      return CURL_CHUNK_BGN_FUNC_FAIL;
125    }
126  }
127
128  return CURL_CHUNK_BGN_FUNC_OK;
129}
130
131int main()
132{
133  /* data for callback */
134  struct callback_data callback_info;
135
136  CURL *curl = curl_easy_init();
137
138  /* callback is called before download of concrete file started */
139  curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming);
140  curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info);
141}
142~~~
143
144# AVAILABILITY
145
146This was added in 7.21.0
147
148# RETURN VALUE
149
150Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
151