# CURLHandle (extras)

> Declared In:
>   CURLHandle+extras.h

## Category Description

This category adds useful methods to CURLHandle for setting options and getting results.

The descriptions are lifted from the current version of libcurl's documentation and modified where necessary.

## Method Types

> Miscellaneous functions
>   - setProgressIndicator:
> Set options for the transfer
>   - setConnectionTimeout:
>   - setTransferTimeout:
>   - setCookieFile:
>   - setRequestCookies:
>   - setFailsOnError:
>   - setFollowsRedirects:
>   - setPostString:
>   - setPostDictionary:
>   - setPostDictionary:encoding:
>   - setReferer:
>   - setUserAgent:
>   - setUserName:password:
>   - setNoBody:
>   - setRange:
>   - setIfModSince:
>   - setLowSpeedTime:
>   - setLowSpeedLimit:
>   - setVerbose:
> Get information about the transfer
>   - downloadContentLength
>   - downloadSize
>   - downloadSpeed
>   - nameLookupTime
>   - pretransferTime
>   - totalTime
>   - uploadContentLength
>   - uploadSize
>   - uploadSpeed
>   - fileTime
>   - headerSize
>   - httpCode
>   - requestSize
> Multipart post operations
>   - setMultipartPostDictionary:
>   - setMultipartPostDictionary:headers:

## Instance Methods

### downloadContentLength

`- (double)downloadContentLength`

Return the content length of the download. This is the value read from the Content-Length: field.

### downloadSize

`- (double)downloadSize`

Return the total amount of bytes that were downloaded.

### downloadSpeed

`- (double)downloadSpeed`

Return the average download speed that curl measured for the complete download.

### fileTime

`- (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.

### headerSize

`- (long)headerSize`

Return the total size of all the headers received.

### httpCode

`- (long)httpCode`

Return the last received HTTP code.

### nameLookupTime

`- (double)nameLookupTime`

Return the time, in seconds, it took from the start until the name resolving was completed.

### pretransferTime

`- (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.

### requestSize

`- (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.

### setConnectionTimeout:

`- (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.)

### setCookieFile:

`- (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

### setFailsOnError:

`- (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.

### setFollowsRedirects:

`- (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.

### setIfModSince:

`- (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.

### setLowSpeedLimit:

`- (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.

### setLowSpeedTime:

`- (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.

### setMultipartPostDictionary:

`- (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

### setMultipartPostDictionary:headers:

`- (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--

### setNoBody:

`- (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.

### setPostDictionary:

`- (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.

### setPostDictionary: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.

### setPostString:

`- (void)setPostString:(NSString *)inPostString`

Set post data as a string, for XML-RPC communication and such that doesn't want data pairs.

### setProgressIndicator:

`- (void)setProgressIndicator:(id)inProgressIndicator`

Set a progress indicator for showing foreground load progress.

### setRange:

`- (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

### setReferer:

`- (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.

### setRequestCookies:

`- (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.

### setTransferTimeout:

`- (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.)

### setUserAgent:

`- (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.

### setUserName:password:

`- (void)setUserName:(NSString*)inUserName password:(NSString *)inPassword`

Set the user and password.

Pass strings to use for the connection.

### setVerbose:

`- (void)setVerbose:(BOOL)beVerbose`

Set the verbosity of CURL.

### totalTime

`- (double)totalTime`

Return the total transaction time in seconds for the previous transfer.

### uploadContentLength

`- (double)uploadContentLength`

Return the specified size of the upload.

### uploadSize

`- (double)uploadSize`

Return the total amount of bytes that were uploaded.

### uploadSpeed

`- (double)uploadSpeed`

Return the average upload speed that curl measured for the complete upload.