Debian Codegraph @

deps/curl/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3

raw
1 .\" **************************************************************************
2 .\" * _ _ ____ _
3 .\" * Project ___| | | | _ \| |
4 .\" * / __| | | | |_) | |
5 .\" * | (__| |_| | _ <| |___
6 .\" * \___|\___/|_| \_\_____|
7 .\" *
8 .\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <[email protected]>, et al.
9 .\" *
10 .\" * This software is licensed as described in the file COPYING, which
11 .\" * you should have received as part of this distribution. The terms
12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
13 .\" *
14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
15 .\" * copies of the Software, and permit persons to whom the Software is
16 .\" * furnished to do so, under the terms of the COPYING file.
17 .\" *
18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
19 .\" * KIND, either express or implied.
20 .\" *
21 .\" **************************************************************************
22 .\"
23 .TH CURLOPT_CHUNK_BGN_FUNCTION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
24 .SH NAME
25 CURLOPT_CHUNK_BGN_FUNCTION \- callback before a transfer with FTP wildcardmatch
26 .SH SYNOPSIS
27 .nf
28 #include <curl/curl.h>
29
30 struct curl_fileinfo {
31 char *filename;
32 curlfiletype filetype;
33 time_t time; /* always zero! */
34 unsigned int perm;
35 int uid;
36 int gid;
37 curl_off_t size;
38 long int hardlinks;
39
40 struct {
41 /* If some of these fields is not NULL, it is a pointer to b_data. */
42 char *time;
43 char *perm;
44 char *user;
45 char *group;
46 char *target; /* pointer to the target filename of a symlink */
47 } strings;
48
49 unsigned int flags;
50
51 /* used internally */
52 char *b_data;
53 size_t b_size;
54 size_t b_used;
55 };
56
57 long chunk_bgn_callback(const void *transfer_info, void *ptr,
58 int remains);
59
60 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_BGN_FUNCTION,
61 chunk_bgn_callback);
62 .SH DESCRIPTION
63 Pass a pointer to your callback function, which should match the prototype
64 shown above.
65
66 This callback function gets called by libcurl before a part of the stream is
67 going to be transferred (if the transfer supports chunks).
68
69 The \fItransfer_info\fP pointer will point to a struct curl_fileinfo with
70 details about the file that is about to get transferred.
71
72 This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH(3)\fP
73 option for now.
74
75 The target of transfer_info parameter is a "feature depended" structure. For
76 the FTP wildcard download, the target is curl_fileinfo structure (see
77 \fIcurl/curl.h\fP). The parameter \fIptr\fP is a pointer given by
78 \fICURLOPT_CHUNK_DATA(3)\fP. The parameter remains contains number of chunks
79 remaining per the transfer. If the feature is not available, the parameter has
80 zero value.
81
82 Return \fICURL_CHUNK_BGN_FUNC_OK\fP if everything is fine,
83 \fICURL_CHUNK_BGN_FUNC_SKIP\fP if you want to skip the concrete chunk or
84 \fICURL_CHUNK_BGN_FUNC_FAIL\fP to tell libcurl to stop if some error occurred.
85 .SH DEFAULT
86 NULL
87 .SH PROTOCOLS
88 FTP
89 .SH EXAMPLE
90 .nf
91 static long file_is_coming(struct curl_fileinfo *finfo,
92 struct callback_data *data,
93 int remains)
94 {
95 printf("%3d %40s %10luB ", remains, finfo->filename,
96 (unsigned long)finfo->size);
97
98 switch(finfo->filetype) {
99 case CURLFILETYPE_DIRECTORY:
100 printf(" DIR\\n");
101 break;
102 case CURLFILETYPE_FILE:
103 printf("FILE ");
104 break;
105 default:
106 printf("OTHER\\n");
107 break;
108 }
109
110 if(finfo->filetype == CURLFILETYPE_FILE) {
111 /* do not transfer files >= 50B */
112 if(finfo->size > 50) {
113 printf("SKIPPED\\n");
114 return CURL_CHUNK_BGN_FUNC_SKIP;
115 }
116
117 data->output = fopen(finfo->filename, "wb");
118 if(!data->output) {
119 return CURL_CHUNK_BGN_FUNC_FAIL;
120 }
121 }
122
123 return CURL_CHUNK_BGN_FUNC_OK;
124 }
125
126 int main()
127 {
128 /* data for callback */
129 struct callback_data callback_info;
130
131 /* callback is called before download of concrete file started */
132 curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming);
133 curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info);
134 }
135 .fi
136 .SH AVAILABILITY
137 This was added in 7.21.0
138 .SH RETURN VALUE
139 Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
140 .SH "SEE ALSO"
141 .BR CURLOPT_CHUNK_END_FUNCTION "(3), " CURLOPT_WILDCARDMATCH "(3), "