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