Public Member Functions |
| (id) | - init |
| (id) | - initWithDelegate: |
| (id) | - initWithDelegate:userData: |
| (NSString *) | - description |
| (id) | - delegate |
| | Use "canSafelySetDelegate" to see if there is any pending business (reads and writes) with the current delegate before changing it.
|
| (BOOL) | - canSafelySetDelegate |
| (void) | - setDelegate: |
| (long) | - userData |
| (void) | - setUserData: |
| (CFSocketRef) | - getCFSocket |
| (CFReadStreamRef) | - getCFReadStream |
| (CFWriteStreamRef) | - getCFWriteStream |
| (BOOL) | - acceptOnPort:error: |
| | Tells the socket to begin listening and accepting connections on the given port.
|
| (BOOL) | - acceptOnInterface:port:error: |
| | This method is the same as acceptOnPort:error: with the additional option of specifying which interface to listen on.
|
| (BOOL) | - connectToHost:onPort:error: |
| | Connects to the given host and port.
|
| (BOOL) | - connectToHost:onPort:withTimeout:error: |
| | This method is the same as connectToHost:onPort:error: with an additional timeout option.
|
| (BOOL) | - connectToAddress:error: |
| | Connects to the given address, specified as a sockaddr structure wrapped in a NSData object.
|
| (BOOL) | - connectToAddress:withTimeout:error: |
| | This method is the same as connectToAddress:error: with an additional timeout option.
|
| (BOOL) | - connectToAddress:viaInterfaceAddress:withTimeout:error: |
| | This method is similar to the one above, but allows you to specify which socket interface the connection should run over.
|
| (void) | - disconnect |
| | Disconnects immediately.
|
| (void) | - disconnectAfterReading |
| | Disconnects after all pending reads have completed.
|
| (void) | - disconnectAfterWriting |
| | Disconnects after all pending writes have completed.
|
| (void) | - disconnectAfterReadingAndWriting |
| | Disconnects after all pending reads and writes have completed.
|
| (BOOL) | - isConnected |
| (NSString *) | - connectedHost |
| | Returns the local or remote host and port to which this socket is connected, or nil and 0 if not connected.
|
| (UInt16) | - connectedPort |
| (NSString *) | - localHost |
| (UInt16) | - localPort |
| (NSData *) | - connectedAddress |
| | Returns the local or remote address to which this socket is connected, specified as a sockaddr structure wrapped in a NSData object.
|
| (NSData *) | - localAddress |
| (BOOL) | - isIPv4 |
| | Returns whether the socket is IPv4 or IPv6.
|
| (BOOL) | - isIPv6 |
| (void) | - readDataWithTimeout:tag: |
| | Reads the first available bytes that become available on the socket.
|
| (void) | - readDataWithTimeout:buffer:bufferOffset:tag: |
| | Reads the first available bytes that become available on the socket.
|
| (void) | - readDataWithTimeout:buffer:bufferOffset:maxLength:tag: |
| | Reads the first available bytes that become available on the socket.
|
| (void) | - readDataToLength:withTimeout:tag: |
| | Reads the given number of bytes.
|
| (void) | - readDataToLength:withTimeout:buffer:bufferOffset:tag: |
| | Reads the given number of bytes.
|
| (void) | - readDataToData:withTimeout:tag: |
| | Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
|
| (void) | - readDataToData:withTimeout:buffer:bufferOffset:tag: |
| | Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
|
| (void) | - readDataToData:withTimeout:maxLength:tag: |
| | Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
|
| (void) | - readDataToData:withTimeout:buffer:bufferOffset:maxLength:tag: |
| | Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
|
| (void) | - writeData:withTimeout:tag: |
| | Writes data to the socket, and calls the delegate when finished.
|
| (float) | - progressOfReadReturningTag:bytesDone:total: |
| | Returns progress of current read or write, from 0.0 to 1.0, or NaN if no read/write (use isnan() to check).
|
| (float) | - progressOfWriteReturningTag:bytesDone:total: |
| (void) | - startTLS: |
| | Secures the connection using SSL/TLS.
|
| (void) | - enablePreBuffering |
| | For handling readDataToData requests, data is necessarily read from the socket in small increments.
|
| (BOOL) | - moveToRunLoop: |
| | When you create an AsyncSocket, it is added to the runloop of the current thread.
|
| (BOOL) | - setRunLoopModes: |
| | Allows you to configure which run loop modes the socket uses.
|
| (BOOL) | - addRunLoopMode: |
| (BOOL) | - removeRunLoopMode: |
| (NSArray *) | - runLoopModes |
| | Returns the current run loop modes the AsyncSocket instance is operating in.
|
| (NSData *) | - unreadData |
| | In the event of an error, this method may be called during onSocket:willDisconnectWithError: to read any data that's left on the socket.
|
| (void) | - startConnectTimeout: |
| (void) | - endConnectTimeout |
| (void) | - doConnectTimeout: |
| (CFSocketRef) | - newAcceptSocketForAddress:error: |
| (BOOL) | - createSocketForAddress:error: |
| (BOOL) | - bindSocketToAddress:error: |
| (BOOL) | - attachSocketsToRunLoop:error: |
| (BOOL) | - configureSocketAndReturnError: |
| (BOOL) | - connectSocketToAddress:error: |
| (void) | - doAcceptWithSocket: |
| (void) | - doSocketOpen:withCFSocketError: |
| (BOOL) | - createStreamsFromNative:error: |
| (BOOL) | - createStreamsToHost:onPort:error: |
| (BOOL) | - attachStreamsToRunLoop:error: |
| (BOOL) | - configureStreamsAndReturnError: |
| (BOOL) | - openStreamsAndReturnError: |
| (void) | - doStreamOpen |
| (BOOL) | - setSocketFromStreamsAndReturnError: |
| (void) | - closeWithError: |
| (void) | - recoverUnreadData |
| (void) | - emptyQueues |
| (void) | - close |
| (NSError *) | - getErrnoError |
| (NSError *) | - getAbortError |
| (NSError *) | - getStreamError |
| (NSError *) | - getSocketError |
| (NSError *) | - getConnectTimeoutError |
| (NSError *) | - getReadMaxedOutError |
| (NSError *) | - getReadTimeoutError |
| (NSError *) | - getWriteTimeoutError |
| (NSError *) | - errorFromCFStreamError: |
| (BOOL) | - isDisconnected |
| (BOOL) | - areStreamsConnected |
| (NSString *) | - connectedHostFromNativeSocket4: |
| (NSString *) | - connectedHostFromNativeSocket6: |
| (NSString *) | - connectedHostFromCFSocket4: |
| (NSString *) | - connectedHostFromCFSocket6: |
| (UInt16) | - connectedPortFromNativeSocket4: |
| (UInt16) | - connectedPortFromNativeSocket6: |
| (UInt16) | - connectedPortFromCFSocket4: |
| (UInt16) | - connectedPortFromCFSocket6: |
| (NSString *) | - localHostFromNativeSocket4: |
| (NSString *) | - localHostFromNativeSocket6: |
| (NSString *) | - localHostFromCFSocket4: |
| (NSString *) | - localHostFromCFSocket6: |
| (UInt16) | - localPortFromNativeSocket4: |
| (UInt16) | - localPortFromNativeSocket6: |
| (UInt16) | - localPortFromCFSocket4: |
| (UInt16) | - localPortFromCFSocket6: |
| (NSString *) | - hostFromAddress4: |
| (NSString *) | - hostFromAddress6: |
| (UInt16) | - portFromAddress4: |
| (UInt16) | - portFromAddress6: |
| (void) | - doBytesAvailable |
| (void) | - completeCurrentRead |
| (void) | - endCurrentRead |
| (void) | - scheduleDequeueRead |
| (void) | - maybeDequeueRead |
| (void) | - doReadTimeout: |
| (void) | - doSendBytes |
| (void) | - completeCurrentWrite |
| (void) | - endCurrentWrite |
| (void) | - scheduleDequeueWrite |
| (void) | - maybeDequeueWrite |
| (void) | - maybeScheduleDisconnect |
| (void) | - doWriteTimeout: |
| (void) | - runLoopAddSource: |
| (void) | - runLoopRemoveSource: |
| (void) | - runLoopAddTimer: |
| (void) | - runLoopRemoveTimer: |
| (void) | - runLoopUnscheduleReadStream |
| (void) | - runLoopUnscheduleWriteStream |
| (void) | - maybeStartTLS |
| (void) | - onTLSHandshakeSuccessful |
| (void) | - doCFCallback:forSocket:withAddress:withData: |
| (void) | - doCFReadStreamCallback:forStream: |
| (void) | - doCFWriteStreamCallback:forStream: |
Static Public Member Functions |
| (NSData *) | + CRLFData |
| (NSData *) | + CRData |
| (NSData *) | + LFData |
| (NSData *) | + ZeroData |
Protected Attributes |
| CFSocketNativeHandle | theNativeSocket4 |
| CFSocketNativeHandle | theNativeSocket6 |
| CFSocketRef | theSocket4 |
| CFSocketRef | theSocket6 |
| CFReadStreamRef | theReadStream |
| CFWriteStreamRef | theWriteStream |
| CFRunLoopSourceRef | theSource4 |
| CFRunLoopSourceRef | theSource6 |
| CFRunLoopRef | theRunLoop |
| CFSocketContext | theContext |
| NSArray * | theRunLoopModes |
| NSTimer * | theConnectTimer |
| NSMutableArray * | theReadQueue |
| AsyncReadPacket * | theCurrentRead |
| NSTimer * | theReadTimer |
| NSMutableData * | partialReadBuffer |
| NSMutableArray * | theWriteQueue |
| AsyncWritePacket * | theCurrentWrite |
| NSTimer * | theWriteTimer |
| id | theDelegate |
| UInt16 | theFlags |
| long | theUserData |
| - (BOOL) acceptOnInterface: |
|
(NSString *) |
interface |
| port: |
|
(UInt16) |
port |
| error: |
|
(NSError **) |
errPtr |
|
|
| |
This method is the same as acceptOnPort:error: with the additional option of specifying which interface to listen on.
To accept on a certain interface, pass the address to accept on.
So, for example, if you were writing code for a server that has multiple IP addresses, you could specify which address you wanted to listen on. Or you could use it to specify that the socket should only accept connections over ethernet, and not other interfaces such as wifi. You may also use the special strings "localhost" or "loopback" to specify that the socket only accept connections from the local machine.
To accept connections on any interface pass nil, or simply use the acceptOnPort:error: method.
To accept on any interface, pass nil or an empty string. To accept only connections from localhost pass "localhost" or "loopback".
| - (BOOL) connectToAddress: |
|
(NSData *) |
remoteAddr |
| withTimeout: |
|
(NSTimeInterval) |
timeout |
| error: |
|
(NSError **) |
errPtr |
|
|
| |
This method is the same as connectToAddress:error: with an additional timeout option.
This method creates an initial CFSocket to the given address.
To not time out use a negative time interval, or simply use the connectToAddress:error: method.
The connection is then opened, and the corresponding CFReadStream and CFWriteStream will be created from the low-level sockets after the connection succeeds.
Thus the delegate will have access to the CFSocket and CFSocketNativeHandle (BSD socket) prior to connection, specifically in the onSocketWillConnect: method.
Note: The NSData parameter is expected to be a sockaddr structure. For example, an NSData object returned from NSNetservice addresses method. If you have an existing struct sockaddr you can convert it to an NSData object like so: struct sockaddr sa -> NSData *dsa = [NSData dataWithBytes:&remoteAddr length:remoteAddr.sa_len]; struct sockaddr *sa -> NSData *dsa = [NSData dataWithBytes:remoteAddr length:remoteAddr->sa_len];
| - (BOOL) connectToHost: |
|
(NSString *) |
hostname |
| onPort: |
|
(UInt16) |
port |
| withTimeout: |
|
(NSTimeInterval) |
timeout |
| error: |
|
(NSError **) |
errPtr |
|
|
| |
This method is the same as connectToHost:onPort:error: with an additional timeout option.
This method creates an initial CFReadStream and CFWriteStream to the given host on the given port.
To not time out use a negative time interval, or simply use the connectToHost:onPort:error: method.
The connection is then opened, and the corresponding CFSocket will be extracted after the connection succeeds.
Thus the delegate will have access to the CFReadStream and CFWriteStream prior to connection, specifically in the onSocketWillConnect: method.
| - (void) enablePreBuffering |
|
|
|
For handling readDataToData requests, data is necessarily read from the socket in small increments.
See the header file for a full explanation of pre-buffering.
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, 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.
This method exists in case pre-buffering needs to be disabled by default for some unforeseen reason. In that case, this method exists to allow one to easily enable pre-buffering when ready.
| - (BOOL) moveToRunLoop: |
|
(NSRunLoop *) |
runLoop |
|
When you create an AsyncSocket, it is added to the runloop of the current thread.
See the header file for a full explanation of this method.
So for manually created sockets, it is easiest to simply create the socket on the thread you intend to use it.
If a new socket is accepted, the delegate method onSocket:wantsRunLoopForNewSocket: is called to allow you to place the socket on a separate thread. This works best in conjunction with a thread pool design.
If, however, you need to move the socket to a separate thread at a later time, this method may be used to accomplish the task.
This method must be called from the thread/runloop the socket is currently running on.
Note: After calling this method, all further method calls to this object should be done from the given runloop. Also, all delegate calls will be sent on the given runloop.
| - (void) readDataToData: |
|
(NSData *) |
data |
| withTimeout: |
|
(NSTimeInterval) |
timeout |
| buffer: |
|
(NSMutableData *) |
buffer |
| bufferOffset: |
|
(NSUInteger) |
offset |
| maxLength: |
|
(NSUInteger) |
length |
| tag: |
|
(long) |
tag |
|
|
| |
Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
The bytes will be appended to the given byte buffer starting at the given offset. The given buffer will automatically be increased in size if needed. A maximum of length bytes will be read.
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 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. If the bufferOffset is greater than the length of the given buffer, the method will do nothing, and the delegate will not be called.
If you pass a buffer, you must not alter it in any way while AsyncSocket is using it. 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.
To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter. 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 |
| buffer: |
|
(NSMutableData *) |
buffer |
| bufferOffset: |
|
(NSUInteger) |
offset |
| tag: |
|
(long) |
tag |
|
|
| |
Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
The bytes will be appended to the given byte buffer starting at the given offset. The given buffer will automatically be increased in size if needed.
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 the bufferOffset is greater than the length of the given buffer, the method will do nothing, and the delegate will not be called.
If you pass a buffer, you must not alter it in any way while AsyncSocket is using it. 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.
To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter. 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: |
|
(NSUInteger) |
length |
| tag: |
|
(long) |
tag |
|
|
| |
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 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. 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.
To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter. 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 |
| tag: |
|
(long) |
tag |
|
|
| |
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 you pass nil or zero-length data as the "data" parameter, the method will do nothing, and the delegate will not be called.
To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter. 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) readDataToLength: |
|
(NSUInteger) |
length |
| withTimeout: |
|
(NSTimeInterval) |
timeout |
| buffer: |
|
(NSMutableData *) |
buffer |
| bufferOffset: |
|
(NSUInteger) |
offset |
| tag: |
|
(long) |
tag |
|
|
| |
Reads the given number of bytes.
The bytes will be appended to the given byte buffer starting at the given offset. The given buffer will automatically be increased in size if needed.
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 the length is 0, this method does nothing and the delegate is not called. If the bufferOffset is greater than the length of the given buffer, the method will do nothing, and the delegate will not be called.
If you pass a buffer, you must not alter it in any way while AsyncSocket is using it. 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) readDataWithTimeout: |
|
(NSTimeInterval) |
timeout |
| buffer: |
|
(NSMutableData *) |
buffer |
| bufferOffset: |
|
(NSUInteger) |
offset |
| maxLength: |
|
(NSUInteger) |
length |
| tag: |
|
(long) |
tag |
|
|
| |
Reads the first available bytes that become available on the socket.
The bytes will be appended to the given byte buffer starting at the given offset. The given buffer will automatically be increased in size if needed. A maximum of length bytes will be read.
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 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.
If you pass a buffer, you must not alter it in any way while AsyncSocket is using it. 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) readDataWithTimeout: |
|
(NSTimeInterval) |
timeout |
| buffer: |
|
(NSMutableData *) |
buffer |
| bufferOffset: |
|
(NSUInteger) |
offset |
| tag: |
|
(long) |
tag |
|
|
| |
Reads the first available bytes that become available on the socket.
The bytes will be appended to the given byte buffer starting at the given offset. The given buffer will automatically be increased in size if needed.
If the timeout value is negative, the read operation will not use a timeout. If the buffer if nil, the socket will create a buffer for you.
If the bufferOffset is greater than the length of the given buffer, the method will do nothing, and the delegate will not be called.
If you pass a buffer, you must not alter it in any way while AsyncSocket is using it. 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.
| - (BOOL) setRunLoopModes: |
|
(NSArray *) |
runLoopModes |
|
Allows you to configure which run loop modes the socket uses.
See the header file for a full explanation of this method.
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.
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.
| - (void) startTLS: |
|
(NSDictionary *) |
tlsSettings |
|
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, the default settings will be used.
The default settings will check to make sure the remote party's certificate is signed by a trusted 3rd party certificate agency (e.g. verisign) and that the certificate is not expired. However it will not verify the name on the certificate unless you give it a name to verify against via the kCFStreamSSLPeerName key. The security implications of this are important to understand. Imagine you are attempting to create a secure connection to MySecureServer.com, but your socket gets directed to MaliciousServer.com because of a hacked DNS server. If you simply use the default settings, and MaliciousServer.com has a valid certificate, the default settings will not detect any problems since the certificate is valid. To properly secure your connection in this particular scenario you should set the kCFStreamSSLPeerName property to "MySecureServer.com". If you do not know the peer name of the remote host in advance (for example, you're not sure if it will be "domain.com" or "www.domain.com"), then you can use the default settings to validate the certificate, and then use the X509Certificate class to verify the issuer after the socket has been secured. The X509Certificate class is part of the CocoaAsyncSocket open source project.
1.7.4
