[tidev#3344] - Support for outbound Ti.Network.Socket

- New tests for sockets in KS
- Updated iOS TCPSocket docs to indicate DEPRECATION

Author: sptramer

apidoc/Titanium/Network/Network.tdoc

@@ -22,9 +22,10 @@ android, iphone, ipad
 - methods
 
 createHTTPClient : returns an HttpClient instance
-createBonjourBrowser : returns a BonjourBrowser instance
-createBonjourService : returns a BonjourService instance
-createTCPSocket : returns a TPCPSocket instance
+createBonjourBrowser : returns a BonjourBrowser instance (iOS only)
+createBonjourService : returns a BonjourService instance (iOS only)
+createTCPSocket : returns a TPCPSocket instance (iOS only; DEPRECATED)
+createSocket : Returns a Socket instance
 registerForPushNotifications: register for push notifications with the Apple Push Notification Service. Only available on iPhone.
 encodeURIComponent: encode a URI component part using URI encoding
 decodeURIComponent: decode a URI component part using URI encoding
@@ -87,6 +88,14 @@ WRITE_MODE[int]: constant value specifying write-only mode for sockets
 READ_WRITE_MODE[int]: constant value specifying read-write mode for sockets
 INADDR_ANY[string]: constant value representing the ability for sockets to listen on any locally available network device
 
+TCP[int]: constant value representing TCP transport protocol
+
+SOCKET_INITIALIZED[int]: constant value representing a socket in the INITIALIZED state
+SOCKET_CONNECTED[int]: constant value representing a socket in the CONNECTED state
+SOCKET_LISTENING[int]: constant value representing a socket in the LISTENING state
+SOCKET_CLOSED[int]: constant value representing a socket in the CLOSED state
+SOCKET_ERROR[int]: constant value representing a socket in the ERROR state
+
 online[boolean]: readonly boolean value that indicates if the network is reachable to the Internet either via WIFI or Carrier network
 networkTypeName[string]: the network type name constant. Returns one of `NONE`, `WIFI`, `LAN` or `MOBILE`.
 networkType[int]: the network type value as a constant.

apidoc/Titanium/Network/Socket.tdoc

@@ -9,7 +9,7 @@ object
 
 - description
 
-The TCPSocket instance returned from `Titanium.Network.createTCPSocket`.  This object represents a socket which either listens locally on the device for connections, or connects to a remote machine.
+DEPRECATED: USE `Ti.Network.Socket` WHERE POSSIBLE.  The TCPSocket instance returned from `Titanium.Network.createTCPSocket`.  This object represents a socket which either listens locally on the device for connections, or connects to a remote machine.
 
 - since
 

apidoc/Titanium/Network/TCPSocket.tdoc

@@ -0,0 +1,136 @@
+var win = Ti.UI.currentWindow;
+
+/*
+ * Assumes the existence of a `Ti.Blob Ti.createBlob(string text)` method
+ */
+var connectingSocket = null;
+
+var hostField = Ti.UI.createTextField({
+	value:'HOSTNAME',
+	top:20,
+	left:20,
+	width:140,
+	height:40,
+	borderStyle:Ti.UI.INPUT_BORDERSTYLE_ROUNDED,
+	autocorrect:false,
+	autocapitalization:Ti.UI.TEXT_AUTOCAPITALIZATION_NONE,
+	clearOnEdit:true
+});
+win.add(hostField);
+
+var portField = Ti.UI.createTextField({
+	value:'PORT',
+	top:20,
+	right:20,
+	width:100,
+	height:40,
+	borderStyle:Ti.UI.INPUT_BORDERSTYLE_ROUNDED,
+	autocorrect:false,
+	autocapitalization:Ti.UI.TEXT_AUTOCAPITALIZATION_NONE,
+	clearOnEdit:true
+});
+win.add(portField);
+
+var writeArea = Ti.UI.createTextArea({
+	editable:true,
+	value:'Data to write',
+	height:100,
+	width:300,
+	top:80,
+	textAlign:'left',
+	borderWidth:2,
+	borderColor:'#bbb',
+	borderRadius:5,
+	suppressReturn:false	
+});
+win.add(writeArea);
+
+var statusArea = Ti.UI.createTextArea({
+	editable:false,
+	value:'Socket status',
+	height:100,
+	width:300,
+	bottom:80,
+	textAlign:'left',
+	borderWidth:2,
+	borderColor:'#bbb',
+	borderRadius:5,
+	suppressReturn:false
+});
+win.add(statusArea);
+
+var connectButton = Ti.UI.createButton({
+	title:'Connect',
+	width:80,
+	height:40,
+	left:20,
+	bottom:20
+});
+connectButton.addEventListener('click', function() {
+	if (connectingSocket == null) {
+		try {
+			connectingSocket = Ti.Network.createSocket({
+				hostName:hostField.value,
+				port:portField.value,
+				type:Ti.Network.TCP,
+				connected:function(e) {
+					e.socket.write(Ti.createBlob("Well, hello there!"));
+				},
+				error:function(e) {
+					statusArea.value = "ERROR ("+e.errorCode+"): "+e.error;
+				},
+				closed:function(e) {
+					statusArea.value = "CLOSED CONNECTION TO: "+e.socket.host+":"+e.socket.port;
+				},
+				read:function(e) {
+					statusArea.value = "DATA: "+e.data.toString();
+				}
+			});
+			connectingSocket.connect();
+		}
+		catch (e) {
+			statusArea.value = "EXCEPTION (connect): "+e.toString();
+		}
+	}
+	else {
+		statusArea.value = 'Already connected: '+connectingSocket.hostName +':'+connectingSocket.port;
+	}
+});
+win.add(connectButton);
+
+var disconnectButton = Ti.UI.createButton({
+	title:'Disconnect',
+	width:100,
+	height:40,
+	right:20,
+	bottom:20
+});
+disconnectButton.addEventListener('click', function() {
+	if (connectingSocket != null) {
+		try {
+			connectingSocket.close();
+			connectingSocket = null;
+		}
+		catch (e) {
+			statusArea.value = "EXCEPTION (close): "+e.toString();
+		}
+	}
+	else {
+		statusArea.value = 'Not connected';
+	}
+});
+win.add(disconnectButton);
+
+var writeButton = Ti.UI.createButton({
+	title:'Write',
+	width:80,
+	height:40,
+	bottom:20,
+	left:110
+});
+writeButton.addEventListener('click', function() {
+	if (connectingSocket != null && connectingSocket.state == Ti.Network.SOCKET_CONNECTED) {
+		connectingSocket.write(Ti.createBlob(writeArea.value));
+	}
+});
+win.add(writeButton);

demos/KitchenSink/Resources/examples/socket_connect.js

@@ -18,7 +18,8 @@ var data = [
 	{title:'JSON', hasChild:true, test:'../examples/json.js'},
 	{title:'JS search', hasChild:true, test:'../examples/search_case_insensitive.js'},
 	{title:'Clipboard', hasChild:true, test:'../examples/clipboard.js'},
-	{title:'Sockets', hasChild:true, test:'../examples/sockets.js'}
+	{title:'Connecting socket', hasChild:true, test:'../examples/socket_connect.js'},
+	{title:'Listening socket', hasChild:true, test:'../examples/socket_listener.js'}
 ];
 
 if (Titanium.Platform.name == 'iPhone OS')

demos/KitchenSink/Resources/examples/sockets.js renamed to demos/KitchenSink/Resources/examples/socket_listener.js

@@ -29,7 +29,8 @@ enum AsyncSocketError
 };
 typedef enum AsyncSocketError AsyncSocketError;
 
-@interface NSObject (AsyncSocketDelegate)
+@protocol AsyncSocketDelegate
+@optional
 
 /**
  * In the event of an error, the socket is closed.
@@ -49,11 +50,17 @@ typedef enum AsyncSocketError AsyncSocketError;
 - (void)onSocketDidDisconnect:(AsyncSocket *)sock;
 
 /**
- * Called when a socket accepts a connection.  Another socket is spawned to handle it. The new socket will have
+ * Called when a socket accepts a connection (listening w/autoaccept 'YES').  Another socket is spawned to handle it. The new socket will have
  * the same delegate and will call "onSocket:didConnectToHost:port:".
 **/
 - (void)onSocket:(AsyncSocket *)sock didAcceptNewSocket:(AsyncSocket *)newSocket;
 
+/**
+ * Called when there is a connection to accept (listening w/autoaccept 'NO').  Can retrieve the BSD socket
+ * handle from the passed socket and call accept() on it, guaranteed to nonblock
+**/
+- (void)onSocketHasConnectionToAccept:(AsyncSocket *)sock;
+
 /**
  * Called when a new socket is spawned to handle a connection.  This method should return the run-loop of the
  * thread on which the new socket and its delegate should operate. If omitted, [NSRunLoop currentRunLoop] is used.
@@ -90,7 +97,7 @@ typedef enum AsyncSocketError AsyncSocketError;
  * This would occur if using readToData: or readToLength: methods.
  * It may be used to for things such as updating progress bars.
 **/
-- (void)onSocket:(AsyncSocket *)sock didReadPartialDataOfLength:(CFIndex)partialLength tag:(long)tag;
+- (void)onSocket:(AsyncSocket *)sock didReadPartialDataOfLength:(NSUInteger)partialLength tag:(long)tag;
 
 /**
  * Called when a socket has completed writing the requested data. Not called if there is an error.
@@ -101,7 +108,7 @@ typedef enum AsyncSocketError AsyncSocketError;
  * Called when a socket has written some data, but has not yet completed the entire write.
  * It may be used to for things such as updating progress bars.
 **/
-- (void)onSocket:(AsyncSocket *)sock didWritePartialDataOfLength:(CFIndex)partialLength tag:(long)tag;
+- (void)onSocket:(AsyncSocket *)sock didWritePartialDataOfLength:(NSUInteger)partialLength tag:(long)tag;
 
 /**
  * Called if a read operation has reached its timeout without completing.
@@ -116,8 +123,8 @@ typedef enum AsyncSocketError AsyncSocketError;
 **/
 - (NSTimeInterval)onSocket:(AsyncSocket *)sock
   shouldTimeoutReadWithTag:(long)tag
-				   elapsed:(NSTimeInterval)elapsed
-				 bytesDone:(CFIndex)length;
+                   elapsed:(NSTimeInterval)elapsed
+                 bytesDone:(NSUInteger)length;
 
 /**
  * Called if a write operation has reached its timeout without completing.
@@ -132,8 +139,8 @@ typedef enum AsyncSocketError AsyncSocketError;
 **/
 - (NSTimeInterval)onSocket:(AsyncSocket *)sock
  shouldTimeoutWriteWithTag:(long)tag
-				   elapsed:(NSTimeInterval)elapsed
-				 bytesDone:(CFIndex)length;
+                   elapsed:(NSTimeInterval)elapsed
+                 bytesDone:(NSUInteger)length;
 
 /**
  * Called after the socket has successfully completed SSL/TLS negotiation.
@@ -249,6 +256,20 @@ typedef enum AsyncSocketError AsyncSocketError;
 **/
 - (BOOL)acceptOnInterface:(NSString *)interface port:(UInt16)port error:(NSError **)errPtr;
 
+/**
+ * This method is the same as acceptOnInterface:port:error: with the additional option
+ * of specifying whether or not the listening socket will autoaccept incoming connections.  If 'YES',
+ * then the onSocket:didAcceptNewSocket: callback is called; otherwise, onSocketHasConnectionToAccept:
+ * is called.
+**/
+- (BOOL)acceptOnInterface:(NSString *)interface port:(UInt16)port autoaccept:(BOOL)autoaccept error:(NSError **)errPtr;
+
+/**
+ * This method is used to create a new async socket from an accepted socket, and fires the onSocket:didAcceptNewSocket: delegate callback.
+ * Returns the new async socket, or nil if the accept failed.
+**/
+- (AsyncSocket*)doAcceptFromSocket:(CFSocketRef)parentSocket withNewNativeSocket:(CFSocketNativeHandle)newNativeSocket;
+
 /**
  * Connects to the given host and port.
  * The host may be a domain name (e.g. "deusty.com") or an IP address string (e.g. "192.168.0.2")
@@ -280,6 +301,11 @@ typedef enum AsyncSocketError AsyncSocketError;
 **/
 - (BOOL)connectToAddress:(NSData *)remoteAddr withTimeout:(NSTimeInterval)timeout error:(NSError **)errPtr;
 
+- (BOOL)connectToAddress:(NSData *)remoteAddr
+     viaInterfaceAddress:(NSData *)interfaceAddr
+             withTimeout:(NSTimeInterval)timeout
+                   error:(NSError **)errPtr;
+
 /**
  * Disconnects immediately. Any pending reads or writes are dropped.
  * If the socket is not already disconnected, the onSocketDidDisconnect delegate method
@@ -389,7 +415,7 @@ typedef enum AsyncSocketError AsyncSocketError;
  * 
  * If the timeout value is negative, the read operation will not use a timeout.
  * If the buffer if nil, a buffer will automatically be created for you.
- * If maxLength is negative, no length restriction is enforced.
+ * If maxLength is zero, no length restriction is enforced.
  * 
  * If the bufferOffset is greater than the length of the given buffer,
  * the method will do nothing, and the delegate will not be called.
@@ -401,7 +427,7 @@ typedef enum AsyncSocketError AsyncSocketError;
 - (void)readDataWithTimeout:(NSTimeInterval)timeout
                      buffer:(NSMutableData *)buffer
                bufferOffset:(NSUInteger)offset
-                  maxLength:(CFIndex)length
+                  maxLength:(NSUInteger)length
                         tag:(long)tag;
 
 /**
@@ -411,7 +437,7 @@ typedef enum AsyncSocketError AsyncSocketError;
  * 
  * If the length is 0, this method does nothing and the delegate is not called.
 **/
-- (void)readDataToLength:(CFIndex)length withTimeout:(NSTimeInterval)timeout tag:(long)tag;
+- (void)readDataToLength:(NSUInteger)length withTimeout:(NSTimeInterval)timeout tag:(long)tag;
 
 /**
  * Reads the given number of bytes.
@@ -429,7 +455,7 @@ typedef enum AsyncSocketError AsyncSocketError;
  * After completion, the data returned in onSocket:didReadData:withTag: will be a subset of the given buffer.
  * That is, it will reference the bytes that were appended to the given buffer.
 **/
-- (void)readDataToLength:(CFIndex)length
+- (void)readDataToLength:(NSUInteger)length
              withTimeout:(NSTimeInterval)timeout
                   buffer:(NSMutableData *)buffer
             bufferOffset:(NSUInteger)offset
@@ -478,9 +504,11 @@ typedef enum AsyncSocketError AsyncSocketError;
  * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
  * 
  * If the timeout value is negative, the read operation will not use a timeout.
- * If maxLength is negative, no length restriction is enforced.
  * 
- * If the max length is surpassed, it is treated the same as a timeout - the socket is closed.
+ * If maxLength is zero, no length restriction is enforced.
+ * Otherwise if maxLength bytes are read without completing the read,
+ * it is treated similarly to a timeout - the socket is closed with a AsyncSocketReadMaxedOutError.
+ * The read will complete successfully if exactly maxLength bytes are read and the given data is found at the end.
  * 
  * If you pass nil or zero-length data as the "data" parameter,
  * the method will do nothing, and the delegate will not be called.
@@ -491,7 +519,7 @@ typedef enum AsyncSocketError AsyncSocketError;
  * Note that this method is not character-set aware, so if a separator can occur naturally as part of the encoding for
  * a character, the read will prematurely end.
 **/
-- (void)readDataToData:(NSData *)data withTimeout:(NSTimeInterval)timeout maxLength:(CFIndex)length tag:(long)tag;
+- (void)readDataToData:(NSData *)data withTimeout:(NSTimeInterval)timeout maxLength:(NSUInteger)length tag:(long)tag;
 
 /**
  * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
@@ -501,9 +529,11 @@ typedef enum AsyncSocketError AsyncSocketError;
  * 
  * If the timeout value is negative, the read operation will not use a timeout.
  * If the buffer if nil, a buffer will automatically be created for you.
- * If maxLength is negative, no length restriction is enforced.
  * 
- * If the max length is surpassed, it is treated the same as a timeout - the socket is closed.
+ * If maxLength is zero, no length restriction is enforced.
+ * Otherwise if maxLength bytes are read without completing the read,
+ * it is treated similarly to a timeout - the socket is closed with a AsyncSocketReadMaxedOutError.
+ * The read will complete successfully if exactly maxLength bytes are read and the given data is found at the end.
  * 
  * If you pass a maxLength parameter that is less than the length of the data parameter,
  * the method will do nothing, and the delegate will not be called.
@@ -522,7 +552,7 @@ typedef enum AsyncSocketError AsyncSocketError;
            withTimeout:(NSTimeInterval)timeout
                 buffer:(NSMutableData *)buffer
           bufferOffset:(NSUInteger)offset
-             maxLength:(CFIndex)length
+             maxLength:(NSUInteger)length
                    tag:(long)tag;
 
 /**
@@ -537,8 +567,8 @@ typedef enum AsyncSocketError AsyncSocketError;
  * Returns progress of current read or write, from 0.0 to 1.0, or NaN if no read/write (use isnan() to check).
  * "tag", "done" and "total" will be filled in if they aren't NULL.
 **/
-- (float)progressOfReadReturningTag:(long *)tag bytesDone:(CFIndex *)done total:(CFIndex *)total;
-- (float)progressOfWriteReturningTag:(long *)tag bytesDone:(CFIndex *)done total:(CFIndex *)total;
+- (float)progressOfReadReturningTag:(long *)tag bytesDone:(NSUInteger *)done total:(NSUInteger *)total;
+- (float)progressOfWriteReturningTag:(long *)tag bytesDone:(NSUInteger *)done total:(NSUInteger *)total;
 
 /**
  * Secures the connection using SSL/TLS.
@@ -625,6 +655,8 @@ typedef enum AsyncSocketError AsyncSocketError;
  * Note: NSRunLoopCommonModes is defined in 10.5. For previous versions one can use kCFRunLoopCommonModes.
 **/
 - (BOOL)setRunLoopModes:(NSArray *)runLoopModes;
+- (BOOL)addRunLoopMode:(NSString *)runLoopMode;
+- (BOOL)removeRunLoopMode:(NSString *)runLoopMode;
 
 /**
  * Returns the current run loop modes the AsyncSocket instance is operating in.