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