General Notes

BlackRaccoon is a collection of routines used to act as an FTP client. It was specifically designed to work correctly under ARC and to "fix" a leak in the listing of directories.

With BlackRaccoon you can:

• Download a file
• Upload a file
• Delete a file
• Create a directory
• Delete a directory
• List a directory

A function to queue requests has been left in the code, but has not been tested. As this is not a normal FTP function, the user should assume it is deprecated and will be removed from future releases.

As with WhiteRaccoon, the user needs to assure that the CFNetwork framework has been added to the project.

Differences Between WhiteRaccoon and BlackRaccoon

BlackRaccoon works correctly with ARC. A lot of time and effort went in to assure there were no leaks.

BlackRaccoon, unlike WhiteRaccoon, breaks up files by objects. This is for this author's convenience. If you wish to combine them again, feel free.

BlackRaccoon has been tested with an unencrypted FTP server. However, it has NOT been tested with all manner of usernames and passwords.

Added helper function initWithDelegate to major classes.

All FTP operations will either call RequestCompleted for a positive response or RequestFailed if it is a negative response.

Made the shouldOverwriteFileWithRequest a required implementation in the code.

Added Features

Black Raccoon expands the delegate protocol by adding the following OPTIONAL methods:

- (void) percentCompleted: (BRRequest *) request;

This is an optional method that allows Black Raccoon to send regular updates to the user indicating the percent completed. This is from 0.0 to 1.0 and is accessed via request.percentCompleted If you wish to know how much data was transfered in the last read/write then you can access request.bytesThisIteration. For total bytes it wold be request.bytesTotal.

- (void) requestDataAvailable: (BRRequestDownload *) request;

Download now requires a new method. Black Raccoon will have an NSData object in request.receivedData that the user can then store in a file, another stream, or log.

Uploading a file has two methods, only one of which is required.

- (long) requestDataSendSize: (BRRequestUpload *) request

This tells Black Raccoon the total size in bytes that will be sent. It is only used to assure that percentComplete is correct and not in actual transfer of data.

- (NSData *) requestDataToSend: (BRRequestUpload *) request

Each block of data is returned as a block of NSData. When done, nil is returned.

Usage

The following code assumes the following:

@interface myclass : NSObject <BRRequestDelegate>
{
	BRRequestCreateDirectory *createDir;
	BRRequestDelete * deleteDir;
	BRRequestListDirectory *listDir;
	
	BRRequestDownload *downloadFile;
	BRRequestUpload *uploadFile;
	BRRequestDelete *deleteFile;
    
    NSMutableData *downloadData;
    NSData *uploadData;
}

Create Directory

- (IBAction) createDirectory:(id)sender
{
	createDir = [BRRequestCreateDirectory initWithDelegate: self];
			
	//----- for anonymous login just leave the username and password nil
	createDir.path = @"/home/user/newdirectory/;
	createDir.hostname = @"192.168.1.100";
	createDir.username = @"yourusername";
	createDir.password = @"yourpassword";
	
	//we start the request
	[createDir start];
}

Delete Directory

- (IBAction) deleteDirectory:(id)sender
{
	deleteDir = [BRRequestDelete initWithDelegate: self];
	
	//----- for anonymous login just leave the username and password nil
	deleteDir.path = @"/home/user/newdirectory/;
	deleteDir.hostname = @"192.168.1.100";
	deleteDir.username = @"yourusername";
	deleteDir.password = @"yourpassword";
	
	//we start the request
	[deleteDir start];
}

List Directory

- (IBAction) listDirectory:(id)sender
{
	listDir = [BRRequestListDirectory initWithDelegate: self];	
			
	//----- for anonymous login just leave the username and password nil
	listDir.path = @"/home/user/newdirectory/;
	listDir.hostname = @"192.168.1.100";
	listDir.username = @"yourusername";
	listDir.password = @"yourpassword";
	
	[listDir start];
}

Download a File

- (IBAction) downloadFile :(id)sender
{
    downloadData = [NSMutableData dataWithCapacity: 1];

	downloadFile = [BRRequestDownload initWithDelegate: self];
	
	//----- for anonymous login just leave the username and password nil
	downloadFile.path = @"/home/user/myfile.txt";	
	downloadFile.hostname = @"192.168.1.100";
	downloadFile.username = @"yourusername";
	downloadFile.password = @"yourpassword";
	
	//we start the request
	[downloadFile start];
}

Upload a File

- (IBAction) uploadFile :(id)sender
{
	//----- get the file to upload as an NSData object
	NSString *applicationDocumentsDir = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0];
	NSString *filepath = [NSString stringWithFormat: @"%@/%@", applicationDocumentsDir, @"file.text"];
	uploadData = [NSData dataWithContentsOfFile: filepath];
	
	uploadFile = [BRRequestUpload initWithDelegate: self];
	
	//----- for anonymous login just leave the username and password nil
	uploadFile.sentData = dataToUpload;		
	uploadFile.path = @"/home/user/myfile.txt";		
	uploadFile.hostname = @"192.168.1.100";
	uploadFile.username = @"yourusername";
	uploadFile.password = @"yourpassword";
	
	//we start the request
	[uploadFile start];
}

Delete a File

- (IBAction) deleteFile: (id) sender
{
	deleteFile = [BRRequestDelete initWithDelegate: self];
			
	//----- for anonymous login just leave the username and password nil
	deleteFile.path = @"/home/user/myfile.txt";
	deleteFile.hostname = @"192.168.1.100";
	deleteFile.username = @"yourusername";
	deleteFile.password = @"yourpassword";
	
	//----- we start the request
	[deleteFile start];
}

Cancel Upload or Download

- (IBAction) cancelAction :(id)sender
{
    if (uploadFile)
    {
        //----- Remove comment if you do not want success delegate called
        //----- upon completion of the cancel
        // uploadFile.cancelDoesNotCallDelegate = TRUE;
        [uploadFile cancelRequest];
    }
    
    if (downloadFile)
    {
        //----- Remove comment if you do not want success delegate called
        //----- upon completion of the cancel
        // downloadFile.cancelDoesNotCallDelegate = TRUE;
        [downloadFile cancelRequest];
    }
}

Delegate callback required to download a file REQUIRED TO DOWNLOAD

- (void) requestDataAvailable: (BRRequestDownload *) request;
{
    [downloadData appendData: request.receivedData];
}

Delegate callback to determine if something should be overwritten REQUIRED

-(BOOL) shouldOverwriteFileWithRequest: (BRRequest *) request
{
	//----- set this as appropriate if you want the file to be overwritten
	if (request == uploadFile)
	{
		//----- if uploading a file, we set it to YES
		return YES;
	}
	
	//----- anything else (directories, etc) we set to NO
	return NO;
}

Delegate callback to get percent upload, download or directory OPTIONAL

- (void) percentCompleted: (BRRequest *) request
{
    NSLog(@"%f completed...", request.percentCompleted);
}

Delegate callback to upload a file OPTIONAL TO UPLOAD

- (long) requestDataSendSize: (BRRequestUpload *) request
{
    //----- user returns the total size of data to send. Used ONLY for percentComplete
    return [uploadData length];
}

Delegate callback required to upload a file REQUIRED TO UPLOAD

- (NSData *) requestDataToSend: (BRRequestUpload *) request
{
    //----- returns data object or nil when complete
    //----- basically, first time we return the pointer to the NSData.
    //----- and BR will upload the data.
    //----- Second time we return nil which means no more data to send
    NSData *temp = uploadData;   // this is a shallow copy of the pointer
    
    uploadData = nil;            // next time around, return nil...
    
    return temp;
}

Request Completed REQUIRED

-(void) requestCompleted: (BRRequest *) request
{
	//----- handle Create Directory
	if (request == createDir)
	{
		NSLog(@"%@ completed!", request);
		
		createDir = nil;
	}
	
	//----- handle Delete Directory
	if (request == deleteDir)
	{
		NSLog(@"%@ completed!", request);
		
		deleteDir = nil;
	}
	
	//----- handle List Directory
	if (request == listDir)
	{
		//----- called after 'request' is completed successfully
		NSLog(@"%@ completed!", request);
		
		//----- we print each of the file names
		for (NSDictionary *file in listDir.filesInfo) 
		{
			NSLog(@"%@", [file objectForKey: (id) kCFFTPResourceName]);
		}
		
		logview.text = [NSString stringWithFormat: @"%@\n", logview.text];
		[logview scrollRangeToVisible: NSMakeRange([logview.text length] - 1, 1)];
					
		listDir = nil;
	}
	
	//----- handle Download File
	if (request == downloadFile)
	{
		//called after 'request' is completed successfully
		NSLog(@"%@ completed!", request);
		
		NSData *data = downloadFile.receivedData;
		
		//----- save the NSData as a file object
		NSError *error;
		NSString *applicationDocumentsDir = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0];
		NSString *filepath = [NSString stringWithFormat: @"%@/%@", applicationDocumentsDir, @"image.jpg"];
		[data writeToFile: filepath options: NSDataWritingFileProtectionNone error: &error];
		
		downloadFile = nil;
	}
	
	if (request == uploadFile)
	{
		NSLog(@"%@ completed!", request);
		uploadFile = nil;
	}
	
	if (request == deleteFile)
	{
		NSLog(@"%@ completed!", request);
		deleteFile = nil;
	}	
}

Request Failed REQUIRED

-(void) requestFailed:(BRRequest *) request
{
	if (request == createDir)
	{
		NSLog(@"%@", request.error.message);
		
		createDir = nil;
	}
	
	if (request == deleteDir)
	{
		NSLog(@"%@", request.error.message);
		
		deleteDir = nil;
	}
	
	if (request == listDir)
	{
		NSLog(@"%@", request.error.message);
		
		listDir = nil;
	}
	
	if (request == downloadFile)
	{
		NSLog(@"%@", request.error.message);
		
		downloadFile = nil;
	}
	
	if (request == uploadFile)
	{
		NSLog(@"%@", request.error.message);
		
		uploadFile = nil;
	}
	
	if (request == deleteFile)
	{
		NSLog(@"%@", request.error.message);
		
		deleteFile = nil;
	}
}