Return to CURLOPT_CHUNK_BGN_FUNCTION.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl / opts

Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3, revision 1.1.1.1

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