AsyncSocket.h解读

本来想看一下AsyncSocket的源码，但是发现每次读英文注释也是很麻烦的，不如直接把它翻译一下。而且在边看边翻译的过程中，会一直在想作者为什么会这么写，顺便还可以学习一下高手编程的良好习惯 和思路。

  1 #import <Foundation/Foundation.h>

  2 

  3 @class AsyncSocket;//async异步的 synchro同步

  4 @class AsyncReadPacket;

  5 @class AsyncWritePacket;

  6 

  7 //extern来说可以理解为扩展吧是这样的是从一个类扩展到另一个类中的

  8 extern NSString *const AsyncSocketException;//Exception:意外

  9 extern NSString *const AsyncSocketErrorDomin;//errorDomin :错误域名

 10 

 11 enum AsyncSocketError//socket错误

 12 {

 13     AsynsocketCFSocketError = kCFSocketError,// kCFSocketError is from CFSocketError enum;

 14     AsyncSocketNoError = 0,//never used

 15     AsyncSocketCanceledError,//onSocketWillConnect :return NO

 16     AsyncSocketReadTimmeoutError,

 17     AsyncSocketWritrTimeoutError

 18 };

 19 typedef enum AsyncSocketError AsyncSocketError;//typedef

 20 

 21 @interface NSObject (AsyncSocketDelegate)//类目,虽然看上去像是代理方法，但是作者把它们写成了NSObject类的扩展方法 因此实际编程中包含该.h文件的所有类都可以直接使用这些方法

 22 

 23 

 24 /**

 25  * In the event of an error, the socket is closed.

 26  * You may call "unreadData" during this call-back to get the last bit of data off the socket.

 27  * When connecting, this delegate method may be called

 28  * before"onSocket:didAcceptNewSocket:" or "onSocket:didConnectToHost:".

 29  **/

 30 //发生错误 socket将要断开连接

 31 -(void) onSocket:(AsyncSocket *)sock willDisconnectWithError:(NSError *)err;

 32 

 33 /**

 34  * Called when a socket accepts a connection.  Another socket is spawned to handle it. The new socket will have

 35  * the same delegate and will call "onSocket:didConnectToHost:port:".

 36  **/

 37 //在socket断开连接时将被执行（不管有没有发生错误）。如果你想在一个socket断开连接后release它，do so here。在“onSocket：willDisconnectWithError中那样做是不安全的

 38 -(void)onSocketDidDisconnect:(AsyncSocket *)socket;

 39 

 40 /**

 41  * Called when a socket accepts a connection.  Another socket is spawned to handle it. The new socket will have

 42  * the same delegate and will call "onSocket:didConnectToHost:port:".

 43  **/

 44 //called when 一个socket接受了一个连接（connection），会产生另一个新的socket去处理这个连接（好像是服务器中用的那个，sock是监听（listen）socket，接受到连接后会产生新的socket去处理连接）。新产生的socket将存在相同的代理，而且会call "onSocket:didConnectToHost:port:".

 45 -(void)onSocket:(AsyncSocket *)sock didAcceptNewSocket:(AsyncSocket *)newSocket;

 46 

 47 /**

 48  * Called when a new socket is spawned to handle a connection.  This method should return the run-loop of the

 49  * thread on which the new socket and its delegate should operate. If omitted, [NSRunLoop currentRunLoop] is used.

 50  **/

 51 //omitted：省略，遗漏

 52 //called when一个新socket被产生去处理一个连接。这个方法将会返回这个新socket和它的代理将要操作的线程（thread）的运行回路（runloop）

 53 -(NSRunLoop *)onSocket:(AsyncSocket *)sock wantsRunLoopForNewSocket:(AsyncSocket *)newSocket;

 54 

 55 /**

 56  * Called when a socket is about to connect. This method should return YES to continue, or NO to abort. 

 57  * If aborted, will result in AsyncSocketCanceledError.

 58  *

 59  * If the connectToHost:onPort:error: method was called, the delegate will be able to access and configure the

 60  * CFReadStream and CFWriteStream as desired prior to connection.

 61  *

 62  * If the connectToAddress:error: method was called, the delegate will be able to access and configure the

 63  * CFSocket and CFSocketNativeHandle (BSD socket) as desired prior to connection. You will be able to access and

 64  * configure the CFReadStream and CFWriteStream in the onSocket:didConnectToHost:port: method.

 65  **/

 66 //abort:使流产，使中止 prior：优先的，在。。。之前 configure：配置，设定

 67 //be about to :是指将要做某事，或是发生某事，是指可以预见的，并且确定要发生的

 68 //在一个socket将要连接时被调用。要继续连接，则让该方法返回YES，要中止连接，则让该方法返回NO。如果中止（返回NO）将会导致AsyncSocketCanceledError。

 69 //如果connectToHost:onPort:error: 方法在这之前被调用过，这个代理方法可以进入到之前想要进行的连接，并配置CFReadStream和CFWriteStream

 70 -(BOOL)onSocketWillConnect:(AsyncSocket *)socket;

 71 

 72 /**

 73  * Called when a socket connects and is ready for reading and writing.

 74  * The host parameter will be an IP address, not a DNS name.

 75  **/

 76 //called when 一个socket已经连接，并且已经准备读写。host参数是IP地址，而不是DNS域名

 77 - (void)onSocket:(AsyncSocket *)sock didConnectToHost:(NSString *)host port:(UInt16)port;

 78 

 79 /**

 80  * Called when a socket has completed reading the requested data into memory.

 81  * Not called if there is an error.

 82  **/

 83 //当一个socket已经把数据读入内存中时被调用。如果发生错误则不被调用

 84 - (void)onSocket:(AsyncSocket *)sock didReadData:(NSData *)data withTag:(long)tag;

 85 

 86 /**

 87  * Called when a socket has read in data, but has not yet completed the read.

 88  * This would occur if using readToData: or readToLength: methods.

 89  * It may be used to for things such as updating progress bars.

 90  **/

 91 //当一个socket已经读入数据但是还没有读完的时候被调用。在使用readToData: 或者 readToLength:方法的时候可能会产生这种情况。它在某些情况下可以被使用：比如说更新进度条

 92 - (void)onSocket:(AsyncSocket *)sock didReadPartialDataOfLength:(CFIndex)partialLength tag:(long)tag;

 93 

 94 /**

 95  * Called when a socket has completed writing the requested data. Not called if there is an error.

 96  **/

 97 //当一个socket完全写完数据时被调用。发生错误则不调用。

 98 - (void)onSocket:(AsyncSocket *)sock didWriteDataWithTag:(long)tag;

 99 @end

100 

101 

102 @interface AsyncSocket : NSObject 

103 {

104     CFSocketRef theSocket; //IPv4 accept or connect socket

105     CFSocketRef theSocket6;//Ipv6 accept or connect socket

106     CFReadStreamRef theReadStream;

107     CFWriteStreamRef theWriteStream;

108     

109     CFRunLoopSourceRef theSource;//for theSocket

110     CFRunLoopSourceRef theSource6;//for theSocket6

111     CFRunLoopRef theRunLoop;

112     CFSocketContext theContext;

113     

114     NSMutableArray *theReadqueue;

115     AsyncReadPacket *theCurrentRead;

116     NSTimer *theReadTimer;

117     NSMutableData *partailReadBuffer;

118     

119     NSMutableArray *theWriteQueue;

120     AsyncWritePacket *theCurrentWrite;

121     NSTimer *theWriteTimer;

122     

123     id theDelegate;

124     Byte theFlags;

125     

126     long theUserData;

127 }

128 

129 -(id)init;

130 -(id)initWithDelegate:(id)delegate;

131 -(id)initWithDelegate:(id)delegate userData:(long)userData;

132 

133 -(NSString *)description;//重定义%@打印出的string

134 

135 /**

136  * Use "canSafelySetDelegate" to see if there is any pending business (reads and writes) with the current delegate

137  * before changing it.  It is, of course, safe to change the delegate before connecting or accepting connections.

138  **/

139 //在改变代理之前使用canSafelySetDelegate方法来查看是否有当前代理还没做完的事情（读或者写）。

140 //在连接或接受连接之前改变代理是安全的。

141 - (id)delegate;

142 - (BOOL)canSafelySetDelegate;

143 - (void)setDelegate:(id)delegate;

144 

145 /*User data can be a long,or an id or void* cast to a long.  */

146 //cast to:投射

147 -(long)userData;

148 -(void)setUserData:(long)userData;

149 

150 /*Don't use these to read or write. And don't close them,either!  */

151 -(CFSocketRef)getCFSocket;

152 -(CFReadStreamRef)getCFReadStream;

153 -(CFWriteStreamRef)getCFWriteStream;

154 

155 /**

156  * Once one of these methods is called, the AsyncSocket instance is locked in, and the rest can't be called without

157  * disconnecting the socket first.  If the attempt times out or fails, these methods either return NO or

158  * call "onSocket:willDisconnectWithError:" and "onSockedDidDisconnect:".

159  **/

160 //

161 - (BOOL)acceptOnPort:(UInt16)port error:(NSError **)errPtr;

162 - (BOOL)acceptOnAddress:(NSString *)hostaddr port:(UInt16)port error:(NSError **)errPtr;

163 - (BOOL)connectToHost:(NSString *)hostname onPort:(UInt16)port error:(NSError **)errPtr;

164 - (BOOL)connectToAddress:(NSData *)remoteAddr error:(NSError **)errPtr;

165 

166 -(void)disconnect;

167 -(void)disconnectAfterWriting;

168 -(BOOL)isConnected;

169 -(NSString *)connectedHost;

170 -(UInt16)connectedPort;

171 -(BOOL)isIPv4;

172 -(BOOL)isIPv6;

173 

174 /**

175  * The following methods won't block. To not time out, use a negative time interval.

176  * If they time out, "onSocket:disconnectWithError:" is called. The tag is for your convenience.

177  * You can use it as an array index, step number, state id, pointer, etc., just like the socket's user data.

178  **/

179 

180 //下面这些方法不会阻塞。如果想没有timeout 使用一个负数time interval

181 //如果time out时间用光了，会调用"onSocket:disconnectWithError:"方法。tag只是为了方便，就像socket中的user data一样。

182 

183 /**

184  * This will read a certain number of bytes into memory, and call the delegate method when those bytes have been read.

185  * If there is an error, partially read data is lost.

186  * If the length is 0, this method does nothing and the delegate is not called.

187  **/

188 //这个方法会从内存中读入特定数值的字节，读完之后会调用代理方法

189 //如果发生错误，被部分读入的数据会消失

190 //如果length为0，这个方法什么都不做，代理也不会被调用

191 -(void)readDataToLength:(CFIndex)length withTimeout:(NSTimeInterval)timeout tag:(long)tag;

192 

193 /**

194  * This reads bytes until (and including) the passed "data" parameter, which acts as a separator.

195  * The bytes and the separator are returned by the delegate method.

196  *

197  * If you pass nil or zero-length data as the "data" parameter,

198  * the method will do nothing, and the delegate will not be called.

199  *

200  * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.

201  * Note that this method is not character-set aware, so if a separator can occur naturally as part of the encoding for

202  * a character, the read will prematurely end.

203  **/

204 

205 -(void)readDataToData:(NSData *)data withTimeout:(NSTimeInterval)timeout tag:(long)tag;

206 

207 /**

208  * Reads the first available bytes that become available on the socket.

209  **/

210 

211 -(void)readDataWithTimeout:(NSTimeInterval)timeout tag:(long)tag;

212 

213 

214 /* Writes data to the socket, and calls the delegate when finished.

215  *

216  * If you pass in nil or zero-length data, this method does nothing and the delegate will not be called.

217  **/

218 //向调用方法的socket写入数据

219 -(void)writeData:(NSData *)data withTimeout:(NSTimeInterval)timeout tag:(long)tag;

220 

221 /**

222  * Returns progress of current read or write, from 0.0 to 1.0, or NaN if no read/write (use isnan() to check).

223  * "tag", "done" and "total" will be filled in if they aren't NULL.

224  **/

225 //返回当前读/写的进度（0.0~1.0），没有读/写时返回NaN，在tag，done，total非空时要写上

226 //typedef signed long CFIndex;

227 -(float)progressOfReadReturningTag:(long *)tag bytesDone:(CFIndex *)done total:(CFIndex *)total;

228 -(float)progressOfWriteReturningTag:(long *)tag bytesDone:(CFIndex *)done total:(CFIndex *)total;

229 

230 /**

231  * In the event of an error, this method may be called during onSocket:willDisconnectWithError: to read

232  * any data that's left on the socket.

233  **/

234 //在发生错误的时候，这个方法可能在onSocket:willDisconnectWithError:中被调用，用来读取留在socket中的数据

235 - (NSData *)unreadData;

236 

237 +(NSData *)unreadData;//0x0D0A

238 +(NSData *)CRLFData;//0x0D

239 +(NSData *)LFData;//0x0A

240 +(NSData *)ZeroData;//0x00

241 @end