CURLOPT_CHUNK_BGN_FUNCTION.md (3606B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Title: CURLOPT_CHUNK_BGN_FUNCTION 5 Section: 3 6 Source: libcurl 7 See-also: 8 - CURLOPT_CHUNK_END_FUNCTION (3) 9 - CURLOPT_WILDCARDMATCH (3) 10 Protocol: 11 - FTP 12 Added-in: 7.21.0 13 --- 14 15 # NAME 16 17 CURLOPT_CHUNK_BGN_FUNCTION - callback before a transfer with FTP wildcard match 18 19 # SYNOPSIS 20 21 ~~~c 22 #include <curl/curl.h> 23 24 struct 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 51 long chunk_bgn_callback(const void *transfer_info, void *ptr, 52 int remains); 53 54 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_BGN_FUNCTION, 55 chunk_bgn_callback); 56 ~~~ 57 58 # DESCRIPTION 59 60 Pass a pointer to your callback function, which should match the prototype 61 shown above. 62 63 This callback function gets called by libcurl before a part of the stream is 64 going to be transferred (if the transfer supports chunks). 65 66 The *transfer_info* pointer points to a **curl_fileinfo** struct with 67 details about the file that is about to get transferred. 68 69 This callback makes sense only when using the CURLOPT_WILDCARDMATCH(3) 70 option for now. 71 72 The target of transfer_info parameter is a "feature depended" structure. For 73 the FTP wildcard download, the target is **curl_fileinfo** structure (see 74 *curl/curl.h*). The parameter *ptr* is a pointer given by 75 CURLOPT_CHUNK_DATA(3). The parameter remains contains number of chunks 76 remaining per the transfer. If the feature is not available, the parameter has 77 zero value. 78 79 Return *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 85 NULL 86 87 # %PROTOCOLS% 88 89 # EXAMPLE 90 91 ~~~c 92 #include <stdio.h> 93 94 struct callback_data { 95 FILE *output; 96 }; 97 98 static 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 134 int 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 151 curl_easy_setopt(3) returns a CURLcode indicating success or error. 152 153 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see 154 libcurl-errors(3).