Added startTLS method to AsyncSocket, and corresponding onSocket:didS…

…ecure: delegate method. This allows one to start SSL/TLS on a socket at any time, and be notified when the connection has been secured.

Also added disconnectAfterReading method.

AsyncSocket.h

@@ -93,8 +93,18 @@ typedef enum AsyncSocketError AsyncSocketError;
 **/
 - (void)onSocket:(AsyncSocket *)sock didWriteDataWithTag:(long)tag;
 
+/**
+ * Called after the socket has completed SSL/TLS negotiation.
+ * This method is not called unless you use the provided startTLS method.
+**/
+- (void)onSocket:(AsyncSocket *)sock didSecure:(BOOL)flag;
+
 @end
 
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+#pragma mark -
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
 @interface AsyncSocket : NSObject
 {
 	CFSocketRef theSocket;             // IPv4 accept or connect socket
@@ -162,13 +172,26 @@ typedef enum AsyncSocketError AsyncSocketError;
 **/
 - (void)disconnect;
 
+/**
+ * Disconnects after all pending reads have completed.
+ * After calling this, the read and write methods will do nothing.
+ * The socket will disconnect even if there are still pending writes.
+**/
+- (void)disconnectAfterReading;
+
 /**
  * Disconnects after all pending writes have completed.
- * After calling this, the read and write methods (including "readDataWithTimeout:tag:") will do nothing.
+ * After calling this, the read and write methods will do nothing.
  * The socket will disconnect even if there are still pending reads.
 **/
 - (void)disconnectAfterWriting;
 
+/**
+ * Disconnects after all pending reads and writes have completed.
+ * After calling this, the read and write methods will do nothing.
+**/
+- (void)disconnectAfterReadingAndWriting;
+
 /* Returns YES if the socket and streams are open, connected, and ready for reading and writing. */
 - (BOOL)isConnected;
 
@@ -227,7 +250,8 @@ typedef enum AsyncSocketError AsyncSocketError;
 **/
 - (void)readDataWithTimeout:(NSTimeInterval)timeout tag:(long)tag;
 
-/* Writes data to the socket, and calls the delegate when finished.
+/**
+ * Writes data to the socket, and calls the delegate when finished.
  * 
  * If you pass in nil or zero-length data, this method does nothing and the delegate will not be called.
 **/
@@ -240,12 +264,37 @@ typedef enum AsyncSocketError AsyncSocketError;
 - (float)progressOfReadReturningTag:(long *)tag bytesDone:(CFIndex *)done total:(CFIndex *)total;
 - (float)progressOfWriteReturningTag:(long *)tag bytesDone:(CFIndex *)done total:(CFIndex *)total;
 
+/**
+ * Secures the connection using SSL/TLS.
+ * 
+ * This method may be called at any time, and the TLS handshake will occur after all pending reads and writes
+ * are finished. This allows one the option of sending a protocol dependent StartTLS message, and queuing
+ * the upgrade to TLS at the same time, without having to wait for the write to finish.
+ * Any reads or writes scheduled after this method is called will occur over the secured connection.
+ * 
+ * The possible keys and values for the TLS settings are well documented.
+ * Some possible keys are:
+ * - kCFStreamSSLLevel
+ * - kCFStreamSSLAllowsExpiredCertificates
+ * - kCFStreamSSLAllowsExpiredRoots
+ * - kCFStreamSSLAllowsAnyRoot
+ * - kCFStreamSSLValidatesCertificateChain
+ * - kCFStreamSSLPeerName
+ * - kCFStreamSSLCertificates
+ * - kCFStreamSSLIsServer
+ * 
+ * Please refer to Apple's documentation for associated values, as well as other possible keys.
+ * 
+ * If you pass in nil or an empty dictionary, this method does nothing and the delegate will not be called.
+**/
+- (void)startTLS:(NSDictionary *)tlsSettings;
+
 /**
  * For handling readDataToData requests, data is necessarily read from the socket in small increments.
  * The performance can be much improved by allowing AsyncSocket to read larger chunks at a time and
  * store any overflow in a small internal buffer.
  * This is termed pre-buffering, as some data may be read for you before you ask for it.
- * If you use readDataToData a lot, enabling pre-buffering will result in better performance.
+ * If you use readDataToData a lot, enabling pre-buffering will result in better performance, especially on the iPhone.
  * 
  * The default pre-buffering state is controlled by the DEFAULT_PREBUFFERING definition.
  * It is highly recommended one leave this set to YES.
@@ -273,13 +322,15 @@ typedef enum AsyncSocketError AsyncSocketError;
 - (BOOL)moveToRunLoop:(NSRunLoop *)runLoop;
 
 /**
- * Allows you to configure which run modes the socket uses.
+ * Allows you to configure which run loop modes the socket uses.
  * The default set of run loop modes is NSDefaultRunLoopMode.
  * 
  * If you'd like your socket to continue operation during other modes, you may want to add modes such as
  * NSModalPanelRunLoopMode or NSEventTrackingRunLoopMode. Or you may simply want to use NSRunLoopCommonModes.
  * 
- * Note: Accepted sockets will automatically inherit the same run loop modes as the listening socket.
+ * Accepted sockets will automatically inherit the same run loop modes as the listening socket.
+ * 
+ * Note: NSRunLoopCommonModes is defined in 10.5. For previous versions one can use kCFRunLoopCommonModes.
 **/
 - (BOOL)setRunLoopModes:(NSArray *)runLoopModes;
 
@@ -289,7 +340,7 @@ typedef enum AsyncSocketError AsyncSocketError;
 **/
 - (NSData *)unreadData;
 
-/* A few common line separators, for use with "readDataToData:withTimeout:tag:". */
+/* A few common line separators, for use with the readDataToData:... methods. */
 + (NSData *)CRLFData;   // 0x0D0A
 + (NSData *)CRData;     // 0x0D
 + (NSData *)LFData;     // 0x0A