From 0825cd80a62c21725fb3615f1fdd3aa6cc5f0f34 Mon Sep 17 00:00:00 2001
From: Pavel Raiskup <xraisk00@gmail.com>
Date: Wed, 12 May 2010 15:33:22 +0200
Subject: FTP: WILDCARDMATCH/CHUNKING/FNMATCH added

---
 docs/libcurl/curl_easy_setopt.3 | 85 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

(limited to 'docs/libcurl/curl_easy_setopt.3')

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
-- 
cgit v1.2.3