- Declared In:
- CURLHandle+extras.h
The descriptions are lifted from the current version of libcurl's documentation and modified where necessary.
Miscellaneous functionsSet options for the transfer
- - setProgressIndicator:
Get information about the transfer
- - setConnectionTimeout:
- - setTransferTimeout:
- - setCookieFile:
- - setRequestCookies:
- - setFailsOnError:
- - setFollowsRedirects:
- - setPostString:
- - setPostDictionary:
- - setPostDictionary:encoding:
- - setReferer:
- - setUserAgent:
- - setUserName:password:
- - setNoBody:
- - setRange:
- - setIfModSince:
- - setLowSpeedTime:
- - setLowSpeedLimit:
- - setVerbose:
Multipart post operations
- - downloadContentLength
- - downloadSize
- - downloadSpeed
- - nameLookupTime
- - pretransferTime
- - totalTime
- - uploadContentLength
- - uploadSize
- - uploadSpeed
- - fileTime
- - headerSize
- - httpCode
- - requestSize
- - setMultipartPostDictionary:
- - setMultipartPostDictionary:headers:
- (double)downloadContentLength
Return the content length of the download. This is the value read from the Content-Length: field.
- (double)downloadSize
Return the total amount of bytes that were downloaded.
- (double)downloadSpeed
Return the average download speed that curl measured for the complete download.
- (long)fileTime
Return the remote time of the retrieved document. If you get 0, it can be because of many reasons (unknown, the server hides it or the server doesn't support the command that tells document time etc) and the time of the document is unknown.
- (long)headerSize
Return the total size of all the headers received.
- (long)httpCode
Return the last received HTTP code.
- (double)nameLookupTime
Return the time, in seconds, it took from the start until the name resolving was completed.
- (double)pretransferTime
Return the time, in seconds, it took from the start until the file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved.
- (long)requestSize
Return the total size of the issued requests. This is so far only for HTTP requests. Note that this may be more than one request if setFollowsRedirects is YES.
- (void)setConnectionTimeout:(long)inSeconds
Set the connection timeout.
Pass a long. It should contain the maximum time in seconds that you allow the connection to the server to take. This only limits the connection phase, once it has connected, this option is of no more use. Set to zero to disable connection timeout (it will then only timeout on the system's internal timeouts).
According to man 3 curl_easy_setopt, CURLOPT_CONNECTTIMEOUT uses signals and thus isn't thread-safe. However, in the same man page it's stated that if you TURN OFF SIGNALLING, you can still use CURLOPT_CONNECTTIMEOUT! This will DISABLE any features that use signals, so beware! (But turning off the connection timeout by setting to zero will turn it back on.)
- (void)setCookieFile:(NSString *)inFilePath
Set the cookie repository file.
Pass a string as parameter. It should contain the name of a file for holding cookie data. The cookie data may be in Netscape/ Mozilla cookie data format or just regular HTTP-style headers dumped to a file.
Use this method to avoid manual cookie manipulation with setRequestCookies & getResponseCookies
- (void)setFailsOnError:(BOOL)inFlag
Set whether failure codes should return an error.
A YES parameter tells the library to fail silently if the HTTP code returned is equal to or larger than 300. The default action would be to return the page normally, ignoring that code.
- (void)setFollowsRedirects:(BOOL)inFlag
Set whether redirects are followed automatically. (Default to true)
A YES parameter tells the library to follow any Location: header that the server sends as part of a HTTP header.
NOTE: this means that the library will re-send the same request on the new location and follow new Location: headers all the way until no more such headers are returned.
- (void)setIfModSince:(NSDate *)inModDate
Set the if-modified-since timestamp.
Pass an NSDate as parameter. It will be used to set the If-Modified-Since: header in the http request sent to the remote server. This can be used to get a 304 result if the remote file isn't newer than inModDate.
- (void)setLowSpeedLimit:(long)inBytes
Pass in the transfer speed in bytes per second that the transfer should be below during the low speed seconds for the library to consider it too slow and abort.
- (void)setLowSpeedTime:(long)inSeconds
Pass in the time in seconds that the transfer should be below the given speed limit for the library to consider it too slow and abort.
- (void)setMultipartPostDictionary:(NSDictionary *)inDictionary
Sets the values to use for a multipart POST operation. The values dictionary may include NSString, NSNumber, and NSData objects. NSString objects will automatically be converted to UTF8.
The method setPostDictionary: is similar, except that it encodes all of the form data into a single string that is sent along with the request. For example, given a dictionary such as:
{name = "Andrew Zamler-Carhart"; company = "KavaSoft"}
...setPostDictionary: will cause curl to send an HTTP request such as the following:
POST /form.php HTTP/1.1 Content-Type: application/x-www-form-urlencoded name=Andrew+Zamler-Carhart&company=KavaSoft
Some web servers expect to receive form data in a multipart format, especially those that accept binary file uploads. Passing the same dictionary to this method will result in an HTTP request like the following:
POST /form.php HTTP/1.1 Expect: 100-continue Content-Type: multipart/form-data; boundary=curlf2RiuFIdRn36daIvycelja9wqMl
After the client receives a "HTTP/1.1 100 Continue" message, multipart data such as the following will be sent:
--curlf2RiuFIdRn36daIvycelja9wqMl Content-Disposition: form-data; name="name"
Andrew Zamler-Carhart --curlf2RiuFIdRn36daIvycelja9wqMl Content-Disposition: form-data; name="company"
KavaSoft --curlf2RiuFIdRn36daIvycelja9wqMl--
This method is based on sample code included in the libcurl guide:
http://curl.haxx.se/libcurl/c/the-guide.html
The command-line utility tcpdump is useful for debugging HTTP transactions. You can monitor all traffic to and from the web server www.myserver.com using the following command:
sudo tcpdump -Atq -s 0 host www.myserver.com
- (void)setMultipartPostDictionary:(NSDictionary *)values headers:(NSDictionary *)headers
This method is like setMultipartPostDictionary:, but it allows you to specify custom headers for some of the values. It takes a dictionary of headers, using keys that match those in the values dictionary. Custom headers are optional, so you only need to supply key/value pairs for those form elements that require custom headers. If you don't need any custom headers at all, just pass nil or use the simpler method above.
For example, given these dictionaries as input:
values = {title = "Hello"; body = "<HTML><BODY>Hello, world!</BODY></HTML>"} headers = {body = "Content-Type: text/html; filename = \"hello.html\""}
...the following data will sent to the HTTP server:
--curlf2RiuFIdRn36daIvycelja9wqMl Content-Disposition: form-data; name="title"
Hello --curlf2RiuFIdRn36daIvycelja9wqMl Content-Disposition: form-data; name="body" Content-Type: text/html; filename = "hello.html"
<HTML><BODY>Hello, world!</BODY></HTML> --curlf2RiuFIdRn36daIvycelja9wqMl--
- (void)setNoBody:(BOOL)inNoBody
Set the http operation to HEAD instead of GET.
Pass a BOOL as parameter. It will be used to set the verb to HEAD in the http request sent to the remote server. This means that no body will be returned, just the mime header.
- (void)setPostDictionary:(NSDictionary *)inDictionary
Set the dictionary of post options, and make the request be a HTTP POST. Note that this does not have a way to specify the encoding.
- (void)setPostDictionary:(NSDictionary *)inDictionary encoding:(NSStringEncoding)inEncoding
Set the dictionary of post options, and make the request be a HTTP POST, specifying the string encoding.
- (void)setPostString:(NSString *)inPostString
Set post data as a string, for XML-RPC communication and such that doesn't want data pairs.
- (void)setProgressIndicator:(id)inProgressIndicator
Set a progress indicator for showing foreground load progress.
- (void)setRange:(NSString *)inRange
Set the byte range.
Pass a string as parameter. It will be used to set the Range: header in the http request sent to the remote server. This is used to get partial downloads. String in the form of X-Y or X-Y,N-M
- (void)setReferer:(NSString *)inReferer
Set the referer [sic] string.
Pass a string as parameter. It will be used to set the Referer: header in the http request sent to the remote server. This can be used to fool servers or scripts.
- (void)setRequestCookies:(NSDictionary *)inDict
Set the HTTP request's cookie data manually. The Dictionary contains any number of entries where the key is the cookie name, as identified in an incoming response header "Set-Cookie:" line, and the value is either the cookie value as a string (the simple case) or an NSDictionary with the value of the cookie stored under the "value" key; any other key/values representing other cookie attributes will be ignored.
- (void)setTransferTimeout:(long)inSeconds
Set the transfer timeout.
Pass a long. It should contain the maximum time in seconds that you allow the transfer from the server to take.
According to man 3 curl_easy_setopt, CURLOPT_TIMEOUT uses signals and thus isn't thread-safe. However, in the same man page it's stated that if you TURN OFF SIGNALLING, you can still use CURLOPT_TIMEOUT! This will DISABLE any features that use signals, so beware! (But turning off the connection timeout by setting to zero will turn it back on.)
- (void)setUserAgent:(NSString *)inUserAgent
Set the user agent string.
Pass a string as parameter. It will be used to set the User-Agent: header in the http request sent to the remote server. This can be used to fool servers or scripts.
- (void)setUserName:(NSString*)inUserName password:(NSString *)inPassword
Set the user and password.
Pass strings to use for the connection.
- (void)setVerbose:(BOOL)beVerbose
Set the verbosity of CURL.
- (double)totalTime
Return the total transaction time in seconds for the previous transfer.
- (double)uploadContentLength
Return the specified size of the upload.
- (double)uploadSize
Return the total amount of bytes that were uploaded.
- (double)uploadSpeed
Return the average upload speed that curl measured for the complete upload.