Some refactoring and added a bunch of comments.

More to do.

QuietUnrar.xcodeproj/rob.mode1v3

@@ -252,7 +252,7 @@
 						<dict>
 							<key>PBXSmartGroupTreeModuleColumnWidthsKey</key>
 							<array>
-								<real>186</real>
+								<real>150</real>
 							</array>
 							<key>PBXSmartGroupTreeModuleColumnsKey_v4</key>
 							<array>
@@ -279,7 +279,7 @@
 								</array>
 							</array>
 							<key>PBXSmartGroupTreeModuleOutlineStateVisibleRectKey</key>
-							<string>{{0, 0}, {186, 664}}</string>
+							<string>{{0, 0}, {150, 664}}</string>
 						</dict>
 						<key>PBXTopSmartGroupGIDs</key>
 						<array/>
@@ -291,19 +291,19 @@
 					<key>GeometryConfiguration</key>
 					<dict>
 						<key>Frame</key>
-						<string>{{0, 0}, {203, 682}}</string>
+						<string>{{0, 0}, {167, 682}}</string>
 						<key>GroupTreeTableConfiguration</key>
 						<array>
 							<string>MainColumn</string>
-							<real>186</real>
+							<real>150</real>
 						</array>
 						<key>RubberWindowFrame</key>
-						<string>53 55 1227 723 0 0 1280 778 </string>
+						<string>4 55 1276 723 0 0 1280 778 </string>
 					</dict>
 					<key>Module</key>
 					<string>PBXSmartGroupTreeModule</string>
 					<key>Proportion</key>
-					<string>203pt</string>
+					<string>167pt</string>
 				</dict>
 				<dict>
 					<key>Dock</key>
@@ -328,7 +328,7 @@
 										<key>_historyCapacity</key>
 										<integer>0</integer>
 										<key>bookmark</key>
-										<string>D488BEE510B0769000B3451C</string>
+										<string>D488BF0110B1926600B3451C</string>
 										<key>history</key>
 										<array>
 											<string>D4A4963610541A1C00BE38AE</string>
@@ -346,8 +346,8 @@
 											<string>D488BD8E10AF7F6900B3451C</string>
 											<string>D488BD8F10AF7F6900B3451C</string>
 											<string>D488BD9010AF7F6900B3451C</string>
-											<string>D488BEE010B075CA00B3451C</string>
+											<string>D488BEFE10B18CFC00B3451C</string>
-											<string>D488BEE110B075CA00B3451C</string>
+											<string>D488BEFF10B18CFC00B3451C</string>
 										</array>
 									</dict>
 									<key>SplitCount</key>
@@ -359,14 +359,14 @@
 							<key>GeometryConfiguration</key>
 							<dict>
 								<key>Frame</key>
-								<string>{{0, 0}, {1019, 554}}</string>
+								<string>{{0, 0}, {1104, 618}}</string>
 								<key>RubberWindowFrame</key>
-								<string>53 55 1227 723 0 0 1280 778 </string>
+								<string>4 55 1276 723 0 0 1280 778 </string>
 							</dict>
 							<key>Module</key>
 							<string>PBXNavigatorGroup</string>
 							<key>Proportion</key>
-							<string>554pt</string>
+							<string>618pt</string>
 						</dict>
 						<dict>
 							<key>ContentConfiguration</key>
@@ -379,18 +379,18 @@
 							<key>GeometryConfiguration</key>
 							<dict>
 								<key>Frame</key>
-								<string>{{0, 559}, {1019, 123}}</string>
+								<string>{{0, 623}, {1104, 59}}</string>
 								<key>RubberWindowFrame</key>
-								<string>53 55 1227 723 0 0 1280 778 </string>
+								<string>4 55 1276 723 0 0 1280 778 </string>
 							</dict>
 							<key>Module</key>
 							<string>XCDetailModule</string>
 							<key>Proportion</key>
-							<string>123pt</string>
+							<string>59pt</string>
 						</dict>
 					</array>
 					<key>Proportion</key>
-					<string>1019pt</string>
+					<string>1104pt</string>
 				</dict>
 			</array>
 			<key>Name</key>
@@ -545,17 +545,17 @@
 	<integer>5</integer>
 	<key>WindowOrderList</key>
 	<array>
+		<string>1C530D57069F1CE1000CFCEE</string>
 		<string>D488BD7710AF722600B3451C</string>
 		<string>D488B03D10AF1C2900B3451C</string>
 		<string>D488B03E10AF1C2900B3451C</string>
 		<string>1C78EAAD065D492600B07095</string>
 		<string>1CD10A99069EF8BA00B06720</string>
 		<string>D4A49630105419F700BE38AE</string>
-		<string>1C530D57069F1CE1000CFCEE</string>
 		<string>/Users/rob/Programming/Projects - Mine/QuietUnrar/QuietUnrar.xcodeproj</string>
 	</array>
 	<key>WindowString</key>
-	<string>53 55 1227 723 0 0 1280 778 </string>
+	<string>4 55 1276 723 0 0 1280 778 </string>
 	<key>WindowToolsV3</key>
 	<array>
 		<dict>
@@ -862,7 +862,7 @@
 			<key>WindowToolGUID</key>
 			<string>1C530D57069F1CE1000CFCEE</string>
 			<key>WindowToolIsVisible</key>
-			<true/>
+			<false/>
 		</dict>
 		<dict>
 			<key>Identifier</key>

QuietUnrarAppDelegate.h

@@ -37,6 +37,6 @@ enum
 - (BOOL) extractRarWith:(NSString *) filename;
 - (BOOL) shouldFileBeReplaced:(NSString *) filename;
 - (void) alertUserOfMissing:(const char *) volume;
-- (NSString *) requestArchivePassword:(id) archive;
+- (NSString *) requestArchivePassword;
 
 @end

QuietUnrarAppDelegate.m

@@ -10,39 +10,62 @@
 #import "QuietUnrarAppDelegate.h"
 #import "libunrar/dll.hpp"
 
+#pragma mark Callbacks
+// Declartions that are not to be part of the public interface.
+// The two methods are for callbacks passed to the RAR library
 QuietUnrarAppDelegate * quietUnrar;
 
 int changeVolume(char * volumeName, int mode);
 int callbackFunction(UINT message, LPARAM userData, LPARAM parameterOne, LPARAM parameterTwo);
 
+// Called everytime a new volume (part) of the RAR is needed.
+// mode will either be
+// RAR_VOL_NOTIFY that just notifies us that the volume has changed
+// RAR_VOL_ASK indicates that a volume is needed and the library is asking for it.
+// 
+// in both case volumeName is that name of the volume (for instance .r00)
+//
+// Note in the event of a volume being missing, there is no way to indicate to the
+// library that you have found it. You would need to block the copy, let the user find the 
+// volume, copy it to where the other volumes are and unblock to let the library
+// continue processing
 int changeVolume(char * volumeName, int mode) {
-	//NSLog(@"Volume Name: %s and mode %d", volumeName, mode);
-	
 	if (mode == RAR_VOL_ASK)
-	{
 		[(QuietUnrarAppDelegate *) quietUnrar alertUserOfMissing:volumeName];
 }
 
-}
+// Multipurpose callback function that is called un changing a volume, when data is being processed
-
+// and when a password is required. This is indicated by the message parameter
+//
+// UCM_CHANGEVOLUME sent when changing volumes
+// UCM_PROCESSDATA sent as each file in the archive is being extracted in chunks, useful for progress bars
+// UCM_NEEDPASSWORD sent when the library discovers a password is needed.
+//
+// The userData param is a pointer to something we supplied when the callback was registered. In my
+// case I am passing in the pointer to the archive data so that the requestArchivePassword method
+// can supply the password to the RAR library via RARSetPassword
+//
+// parameterOne & parameterTwo have different meanings depending on what message is passed.
 int callbackFunction(UINT message, LPARAM userData, LPARAM parameterOne, LPARAM parameterTwo) {
 	if (message == UCM_NEEDPASSWORD) {
-		//NSLog(@"Archive password required");
+		NSString * password = [(QuietUnrarAppDelegate *) quietUnrar requestArchivePassword];
-		[(QuietUnrarAppDelegate *) quietUnrar requestArchivePassword: (id) userData];
+		if (password)
-		
+			RARSetPassword((HANDLE)userData, (char *) [password cStringUsingEncoding:NSISOLatin1StringEncoding]);
 	}
-		//NSLog(@"Callback Function, args: %d, %D, %D, %D", message, userData, parameterOne, parameterTwo);
 }
 
-
+#pragma mark
 @implementation QuietUnrarAppDelegate
 
 @synthesize window, passwordView, passwordField;
 
 - (void) applicationWillFinishLaunching:(NSNotification *)notification {
+	// The following is used to determine is the left or right shift keys were depressed
+	// as the application was launched. Could be used to display a gui on Application start.
 	KeyMap map;
 	GetKeys(map);
-	//NSLog(@"Shift or Right Shift: %d", KEYMAP_GET(map, kVKC_Shift) || KEYMAP_GET(map, kVKC_rShift));	
+	if (KEYMAP_GET(map, kVKC_Shift) || KEYMAP_GET(map, kVKC_rShift))
+		NSLog(@"Shift or Right Shift");	
 }
 
 - (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
@@ -50,11 +73,7 @@ int callbackFunction(UINT message, LPARAM userData, LPARAM parameterOne, LPARAM
 	[[NSApplication sharedApplication] terminate:self];
 }
 
-//- (BOOL)application:(id)sender openFileWithoutUI:(NSString *)filename {
+// Call one at a time for each file selected when app is run
-//	NSLog(@"openFileWithoutUI with file: %@", filename);
-//	return YES;
-//}
-
 - (BOOL)application:(NSApplication *)theApplication openFile:(NSString *)filename {
 	//NSLog(@"openFile: %@", filename);
 	
@@ -65,15 +84,7 @@ int callbackFunction(UINT message, LPARAM userData, LPARAM parameterOne, LPARAM
 	return YES;
 }
 
-//- (void)application:(NSApplication *)sender openFiles:(NSArray *)filenames {
+#pragma mark "Main" 
-//	for (NSString * filename in filenames) {
-//		NSLog(@"openFiles: %@", filename);
-//	}
-//	
-//	// If we get passed files don't open the UI
-//	[sender replyToOpenOrPrint:NSApplicationDelegateReplySuccess];
-//}
-
 - (BOOL) extractRarWith:(NSString *) filename {
 	quietUnrar = (void *) self;
 	char commentBuffer[BUF_LEN];
@@ -146,6 +157,8 @@ int callbackFunction(UINT message, LPARAM userData, LPARAM parameterOne, LPARAM
 	return extractionSuccessful;
 }
 
+// Presents a dialog to the user allowing them to Skip a file or overwrite an existing version
+// returns YES or NO
 - (BOOL) shouldFileBeReplaced:(NSString *) filename {
 	BOOL result = NO;
 	
@@ -166,8 +179,8 @@ int callbackFunction(UINT message, LPARAM userData, LPARAM parameterOne, LPARAM
 	return result;
 }
 
+// Indicate to the user that part of the RAR volume is missing.
 - (void) alertUserOfMissing:(const char *) volume {
-	//NSLog(@"Alerting user of missing volume");
 	NSAlert *alert = [[NSAlert alloc] init];
 	[alert addButtonWithTitle:@"OK"];
 	[alert setMessageText:[NSString stringWithFormat:@"Archive part %s is missing.", volume]];
@@ -179,11 +192,15 @@ int callbackFunction(UINT message, LPARAM userData, LPARAM parameterOne, LPARAM
 	[alert release];
 }
 
-- (NSString *) requestArchivePassword:(id) archive {
+// Creates a dialog with a custom view with a NSSecureTextField which is displayed
+// to the user so they can provide a password. Returns the entered password or nil
+- (NSString *) requestArchivePassword {
 	if (!passwordView) {
 		[NSBundle loadNibNamed:@"PasswordView" owner:self];
 	}
 	
+	NSString * password = nil;
+	
 	NSAlert *alert = [[NSAlert alloc] init];
     [alert addButtonWithTitle:@"OK"];
     [alert addButtonWithTitle:@"Cancel"];
@@ -193,12 +210,13 @@ int callbackFunction(UINT message, LPARAM userData, LPARAM parameterOne, LPARAM
     [alert setAlertStyle:NSWarningAlertStyle];
 	
 	if ([alert runModal] == NSAlertFirstButtonReturn) {
-		NSString * password = [passwordField stringValue];
+		password = [passwordField stringValue];
-		RARSetPassword((HANDLE)archive, (char *) [password cStringUsingEncoding:NSISOLatin1StringEncoding]);
+		[password autorelease];
-		//NSLog(@"Password is: %@", password);
 	}
 	
 	[alert release];
+	
+	return password;
 }
 
 @end