From 0825cd80a62c21725fb3615f1fdd3aa6cc5f0f34 Mon Sep 17 00:00:00 2001 From: Pavel Raiskup Date: Wed, 12 May 2010 15:33:22 +0200 Subject: FTP: WILDCARDMATCH/CHUNKING/FNMATCH added --- docs/libcurl/curl_easy_setopt.3 | 85 +++++++++++++++++++++++++++++++++++++++++ docs/libcurl/libcurl-errors.3 | 10 +++++ 2 files changed, 95 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 88b216c3d..295eb749d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -84,6 +84,54 @@ If this option is set and libcurl has been built with the standard name resolver, timeouts will not occur while the name resolve takes place. Consider building libcurl with c-ares support to enable asynchronous DNS lookups, which enables nice timeouts for name resolves without signals. +.IP CURLOPT_WILDCARDMATCH +Set this option to 1 if you want to transfer multiple files according to a +file name pattern. The pattern can be specified as part of the \fICURLOPT_URL\fP +option, using an fnmatch-like pattern (Shell Pattern Matching) in the last part +of URL (file name). + +By default, libcurl uses its internal implementation of fnmatch(). You can +provide your own matching function by the \fICURLOPT_FNMATCH_FUNCTION\fR option. + +This feature is only supported by the FTP download for now. + +A brief introduction of its syntax follows: +.RS +.IP "\fB*\fR - ASTERISK" +\&ftp://example.com/some/path/\fB*.txt\fR (for all txt's from the root +directory) +.RE +.RS +.IP "\fB?\fR - QUESTION MARK" +Question mark matches any (exactly one) character. + +\&ftp://example.com/some/path/\fBphoto?.jpeg\fR +.RE +.RS +.IP "\fB[\fR - BRACKET EXPRESSION" +The left bracket opens a bracket expression. The question mark and asterisk have +no special meaning in a bracket expression. Each bracket expression ends by the +right bracket and matches exactly one character. Some examples follow: + +\fB[a-zA-Z0\-9]\fR or \fB[f\-gF\-G]\fR \- character interval + +\fB[abc]\fR - character enumeration + +\fB[^abc]\fR or \fB[!abc]\fR - negation + +\fB[[:\fR\fIname\fR\fB:]]\fR class expression. Supported classes are +\fBalnum\fR,\fBlower\fR, \fBspace\fR, \fBalpha\fR, \fBdigit\fR, \fBprint\fR, +\fBupper\fR, \fBblank\fR, \fBgraph\fR, \fBxdigit\fR. + +\fB[][-!^]\fR - special case \- matches only '\-', ']', '[', '!' or '^'. These +characters have no special purpose. + +\fB[\\[\\]\\\\]\fR - escape syntax. Matches '[', ']' or '\\'. + +Using the rules above, a file name pattern can be constructed: + +\&ftp://example.com/some/path/\fB[a-z[:upper:]\\\\].jpeg\fR +.RE .PP .SH CALLBACK OPTIONS .IP CURLOPT_WRITEFUNCTION @@ -424,6 +472,43 @@ in 7.20.0) .IP CURLOPT_INTERLEAVEDATA This is the stream that will be passed to \fICURLOPT_INTERLEAVEFUNCTION\fP when interleaved RTP data is received. (Added in 7.20.0) +.IP CURLOPT_CHUNK_BGN_FUNCTION +Function pointer that should match the following prototype: \fBlong function +(const void *transfer_info, void *ptr, int remains)\fR. This function +gets called by libcurl before a part of the stream is going to be transferred +(if the transfer supports chunks). + +This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH\fR +option for now. + +The target of transfer_info parameter is a "feature depended" structure. For the +FTP wildcard download, the target is curl_fileinfo structure (see +\fIcurl/curl.h\fR). +The parameter ptr is a pointer given by \fICURLOPT_CHUNK_DATA\fR. The parameter +remains contains number of chunks remaining per the transfer. If the feature is +not available, the parameter has zero value. + +Return \fICURL_CHUNK_BGN_FUNC_OK\fR if everything is fine, +\fICURL_CHUNK_BGN_FUNC_SKIP\fR if you want to skip the concrete chunk or +\fICURL_CHUNK_BGN_FUNC_FAIL\fR to tell libcurl to stop if some error occurred. +.IP CURLOPT_CHUNK_END_FUNCTION +Function pointer that should match the following prototype: +\fBlong function(void *ptr)\fR. This function gets called by libcurl as soon as +a part of the stream has been transferred (or skipped). + +Return \fICURL_CHUNK_END_FUNC_OK\fR if everything is fine or +\fBCURL_CHUNK_END_FUNC_FAIL\fR to tell the lib to stop if some error occurred. +.IP CURLOPT_CHUNK_DATA +Pass a pointer that will be untouched by libcurl and passed as the ptr argument +to the \fICURL_CHUNK_BGN_FUNTION\fR and \fICURL_CHUNK_END_FUNTION\fR. +.IP CURLOPT_FNMATCH_FUNCTION +Function pointer that should match \fBint function(const char *pattern, const +char *string)\fR prototype (see \fIcurl/curl.h\fR). It is used internally for +the wildcard matching feature. + +Return \fICURL_FNMATCHFUNC_MATCH\fR if pattern matches the string, +\fICURL_FNMATCHFUNC_NOMATCH\fR if not or \fICURL_FNMATCHFUNC_FAIL\fR if an error +occurred. .SH ERROR OPTIONS .IP CURLOPT_ERRORBUFFER Pass a char * to a buffer that the libcurl may store human readable error diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index b4f2940b2..c3c854e90 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -218,6 +218,16 @@ return code is only returned from \fIcurl_easy_recv(3)\fP and Failed to load CRL file (Added in 7.19.0) .IP "CURLE_SSL_ISSUER_ERROR (83)" Issuer check failed (Added in 7.19.0) +.IP "CURLE_FTP_PRET_FAILED (84)" +PRET command failed +.IP "CURLE_RTSP_CSEQ_ERROR (85)" +Mismatch of RTSP CSeq numbers. +.IP "CURLE_RTSP_SESSION_ERROR (86)" +Mismatch of RTSP Session Identifiers. +.IP "CURLE_FTP_BAD_FILE_LIST (87)" +Unable to parse FTP file list (during FTP wildcard downloading). +.IP "CURLE_CHUNK_FAILED (88)" +Chunk callback reported error. .IP "CURLE_OBSOLETE*" These error codes will never be returned. They were used in an old libcurl version and are currently unused. -- cgit v1.2.3