Setting Up the FTP Streams

Begin by creating a read stream using the CFReadStreamCreateWithFTPURL function and passing it the URL string of the file to be downloaded on the remote server. An example of a URL string might be ftp://ftp.example.com/file.txt. Note that the string contains the server name, the path, and the file. Next, create a write stream for the local location where the file will be downloaded. This is accomplished using the CFWriteStreamCreateWithFile function, passing the path where the file will be downloaded.

Since the write stream and the read stream need to stay in sync, it is a good idea to create a structure that contains all of the common information, such as the proxy dictionary, the file size, the number of bytes written, the number of bytes left over, and a buffer. This structure might look like that in Listing 5-1.

Listing 5-1  A stream structure

typedef struct MyStreamInfo {

    CFWriteStreamRef  writeStream;

    CFReadStreamRef   readStream;

    CFDictionaryRef   proxyDict;

    SInt64            fileSize;

    UInt32            totalBytesWritten;

    UInt32            leftOverByteCount;

    UInt8             buffer[kMyBufferSize];

} MyStreamInfo;

Initialize your structure with the read stream and write stream you just created. You can then define the info field of your stream client context (CFStreamClientContext) to point to your structure. This will become useful later.

Open your write stream with the CFWriteStreamOpen function so you can begin writing to the local file. To make sure the stream opens properly, call the function CFWriteStreamGetStatus and check whether it returns either kCFStreamStatusOpen or kCFStreamStatusOpening.

With the write stream open, associate a callback function with the read stream. Call the function CFReadStreamSetClient and pass the read stream, the network events your callback function should receive, the callback function's name and the CFStreamClientContext object. By having earlier set the info field of the stream client context, your structure will now be sent to your callback function whenever it is run.

Some FTP servers may require a user name, and some may also require a password. If the server you are accessing needs a user name for authentication, call the CFReadStreamSetProperty function and pass the read stream, kCFStreamPropertyFTPUserName for the property, and a reference to a CFString object containing the user name. In addition, if you need to set a password, set the kCFStreamPropertyFTPPassword property.

Some network configurations may also use FTP proxies. You obtain the proxy information in different ways depending on whether your code is running in OS X or iOS.

• In OS X, you can retrieve the proxy settings in a dictionary by calling the SCDynamicStoreCopyProxies function and passing it NULL.

• In iOS, you can retrieve the proxy settings by calling CFNetworkCopyProxiesForURL.

These functions return a dynamic store reference. You can use this value to set the kCFStreamPropertyFTPProxy property of the read stream. This sets the proxy server, specifies the port, and returns a Boolean value indicating whether passive mode is enforced for the FTP stream.

In addition to the properties mentioned, there are a number of other properties available for FTP streams. The complete list follows.

• kCFStreamPropertyFTPUserName — user name to use to log in (settable and retrievable; do not set for anonymous FTP connections)

• kCFStreamPropertyFTPPassword — password to use to log in (settable and retrievable; do not set for anonymous FTP connections)

• kCFStreamPropertyFTPUsePassiveMode — whether to use passive mode (settable and retrievable)

• kCFStreamPropertyFTPResourceSize — the expected size of an item that is being downloaded, if available (retrievable; available only for FTP read streams)

• kCFStreamPropertyFTPFetchResourceInfo — whether to require that resource information, such as size, be required before starting a download (settable and retrievable); setting this property may impact performance

• kCFStreamPropertyFTPFileTransferOffset — file offset at which to start a transfer (settable and retrievable)

• kCFStreamPropertyFTPAttemptPersistentConnection — whether to try to reuse connections (settable and retrievable)

• kCFStreamPropertyFTPProxy — CFDictionary type that holds key-value pairs of proxy dictionary (settable and retrievable)

• kCFStreamPropertyFTPProxyHost — name of an FTP proxy host (settable and retrievable)

• kCFStreamPropertyFTPProxyPort — port number of an FTP proxy host (settable and retrievable)

After the correct properties have been assigned to the read stream, open the stream using the CFReadStreamOpen function. Assuming that this does not return an error, all the streams have been properly set up.

Implementing the Callback Function

Your callback function will receive three parameters: the read stream, the type of event, and your MyStreamInfo structure. The type of event determines what action must be taken.

The most common event is kCFStreamEventHasBytesAvailable, which is sent when the read stream has received bytes from the server. First, check how many bytes have been read by calling the CFReadStreamRead function. Make sure the return value is not less than zero (an error), or equal to zero (download has completed). If the return value is positive, then you can begin writing the data in the read stream to disk via the write stream.

Call the CFWriteStreamWrite function to write the data to the write stream. Sometimes CFWriteStreamWrite can return without writing all of the data from the read stream. For this reason, set up a loop to run as long as there is still data to be written. The code for this loop is in Listing 5-2, where info is the MyStreamInfo structure from Setting up the Streams. This method of writing to the write stream uses blocking streams. You can achieve better performance by making the write stream event driven, but the code is more complex.

Listing 5-2  Writing data to a write stream from the read stream

bytesRead = CFReadStreamRead(info->readStream, info->buffer, kMyBufferSize);

//...make sure bytesRead > 0 ...

bytesWritten = 0;

while (bytesWritten < bytesRead) {

    CFIndex result;

    result = CFWriteStreamWrite(info->writeStream, info->buffer + bytesWritten, bytesRead - bytesWritten);

    if (result <= 0) {

        fprintf(stderr, "CFWriteStreamWrite returned %ld\n", result);

        goto exit;

    }

    bytesWritten += result;

}

info->totalBytesWritten += bytesWritten;

Repeat this entire procedure as long as there are available bytes in the read stream.

The other two events you need to watch out for are kCFStreamEventErrorOccurred and kCFStreamEventEndEncountered. If an error occurs, retrieve the error using CFReadStreamGetError and then exit. If the end of the file occurs, then your download has completed and you can exit.

Make sure to remove all your streams after everything is completed and no other process is using the streams. First, close the write stream and set the client to NULL. Then unschedule the stream from the run loop and release it. Remove the streams from the run loop when you are done.