AsyncSocket.h解讀

本來想看一下AsyncSocket的源碼，但是發現每次讀英文注釋也是很麻煩的，不如直接把它翻譯一下。而且在邊看邊翻譯的過程中，會一直在想作者為什么會這么寫，順便還可以學習一下高手編程的良好習慣 和思路。

#import <Foundation/Foundation.h>

@class AsyncSocket;//async異步的 synchro同步
@class AsyncReadPacket;
@class AsyncWritePacket;

//extern來說可以理解為擴展吧是這樣的是從一個類擴展到另一個類中的
extern NSString *const AsyncSocketException;//Exception:意外
extern NSString *const AsyncSocketErrorDomin;//errorDomin :錯誤域名

enum AsyncSocketError//socket錯誤
{
    AsynsocketCFSocketError = kCFSocketError,// kCFSocketError is from CFSocketError enum;
    AsyncSocketNoError = 0,//never used
    AsyncSocketCanceledError,//onSocketWillConnect :return NO
    AsyncSocketReadTimmeoutError,
    AsyncSocketWritrTimeoutError
};
typedef enum AsyncSocketError AsyncSocketError;//typedef

@interface NSObject (AsyncSocketDelegate)//類目,雖然看上去像是代理方法，但是作者把它們寫成了NSObject類的擴展方法 因此實際編程中包含該.h文件的所有類都可以直接使用這些方法


/**
 * In the event of an error, the socket is closed.
 * You may call "unreadData" during this call-back to get the last bit of data off the socket.
 * When connecting, this delegate method may be called
 * before"onSocket:didAcceptNewSocket:" or "onSocket:didConnectToHost:".
 **/
//發生錯誤 socket將要斷開連接
-(void) onSocket:(AsyncSocket *)sock willDisconnectWithError:(NSError *)err;

/**
 * Called when a socket accepts a connection.  Another socket is spawned to handle it. The new socket will have
 * the same delegate and will call "onSocket:didConnectToHost:port:".
 **/
//在socket斷開連接時將被執行（不管有沒有發生錯誤）。如果你想在一個socket斷開連接后release它，do so here。在“onSocket：willDisconnectWithError中那樣做是不安全的
-(void)onSocketDidDisconnect:(AsyncSocket *)socket;

/**
 * Called when a socket accepts a connection.  Another socket is spawned to handle it. The new socket will have
 * the same delegate and will call "onSocket:didConnectToHost:port:".
 **/
//called when 一個socket接受了一個連接（connection），會產生另一個新的socket去處理這個連接（好像是服務器中用的那個，sock是監聽（listen）socket，接受到連接后會產生新的socket去處理連接）。新產生的socket將存在相同的代理，而且會call "onSocket:didConnectToHost:port:".
-(void)onSocket:(AsyncSocket *)sock didAcceptNewSocket:(AsyncSocket *)newSocket;

/**
 * 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.
 **/
//omitted：省略，遺漏
//called when一個新socket被產生去處理一個連接。這個方法將會返回這個新socket和它的代理將要操作的線程（thread）的運行回路（runloop）
-(NSRunLoop *)onSocket:(AsyncSocket *)sock wantsRunLoopForNewSocket:(AsyncSocket *)newSocket;

/**
 * Called when a socket is about to connect. This method should return YES to continue, or NO to abort. 
 * If aborted, will result in AsyncSocketCanceledError.
 *
 * If the connectToHost:onPort:error: method was called, the delegate will be able to access and configure the
 * CFReadStream and CFWriteStream as desired prior to connection.
 *
 * If the connectToAddress:error: method was called, the delegate will be able to access and configure the
 * CFSocket and CFSocketNativeHandle (BSD socket) as desired prior to connection. You will be able to access and
 * configure the CFReadStream and CFWriteStream in the onSocket:didConnectToHost:port: method.
 **/
//abort:使流產，使中止 prior：優先的，在。。。之前 configure：配置，設定
//be about to :是指將要做某事，或是發生某事，是指可以預見的，並且確定要發生的
//在一個socket將要連接時被調用。要繼續連接，則讓該方法返回YES，要中止連接，則讓該方法返回NO。如果中止（返回NO）將會導致AsyncSocketCanceledError。
//如果connectToHost:onPort:error: 方法在這之前被調用過，這個代理方法可以進入到之前想要進行的連接，並配置CFReadStream和CFWriteStream
-(BOOL)onSocketWillConnect:(AsyncSocket *)socket;

/**
 * Called when a socket connects and is ready for reading and writing.
 * The host parameter will be an IP address, not a DNS name.
 **/
//called when 一個socket已經連接，並且已經准備讀寫。host參數是IP地址，而不是DNS域名
- (void)onSocket:(AsyncSocket *)sock didConnectToHost:(NSString *)host port:(UInt16)port;

/**
 * Called when a socket has completed reading the requested data into memory.
 * Not called if there is an error.
 **/
//當一個socket已經把數據讀入內存中時被調用。如果發生錯誤則不被調用
- (void)onSocket:(AsyncSocket *)sock didReadData:(NSData *)data withTag:(long)tag;

/**
 * Called when a socket has read in data, but has not yet completed the read.
 * This would occur if using readToData: or readToLength: methods.
 * It may be used to for things such as updating progress bars.
 **/
//當一個socket已經讀入數據但是還沒有讀完的時候被調用。在使用readToData: 或者 readToLength:方法的時候可能會產生這種情況。它在某些情況下可以被使用：比如說更新進度條
- (void)onSocket:(AsyncSocket *)sock didReadPartialDataOfLength:(CFIndex)partialLength tag:(long)tag;

/**
 * Called when a socket has completed writing the requested data. Not called if there is an error.
 **/
//當一個socket完全寫完數據時被調用。發生錯誤則不調用。
- (void)onSocket:(AsyncSocket *)sock didWriteDataWithTag:(long)tag;
@end


@interface AsyncSocket : NSObject 
{
    CFSocketRef theSocket; //IPv4 accept or connect socket
    CFSocketRef theSocket6;//Ipv6 accept or connect socket
    CFReadStreamRef theReadStream;
    CFWriteStreamRef theWriteStream;
    
    CFRunLoopSourceRef theSource;//for theSocket
    CFRunLoopSourceRef theSource6;//for theSocket6
    CFRunLoopRef theRunLoop;
    CFSocketContext theContext;
    
    NSMutableArray *theReadqueue;
    AsyncReadPacket *theCurrentRead;
    NSTimer *theReadTimer;
    NSMutableData *partailReadBuffer;
    
    NSMutableArray *theWriteQueue;
    AsyncWritePacket *theCurrentWrite;
    NSTimer *theWriteTimer;
    
    id theDelegate;
    Byte theFlags;
    
    long theUserData;
}

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

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

/**
 * Use "canSafelySetDelegate" to see if there is any pending business (reads and writes) with the current delegate
 * before changing it.  It is, of course, safe to change the delegate before connecting or accepting connections.
 **/
//在改變代理之前使用canSafelySetDelegate方法來查看是否有當前代理還沒做完的事情（讀或者寫）。
//在連接或接受連接之前改變代理是安全的。
- (id)delegate;
- (BOOL)canSafelySetDelegate;
- (void)setDelegate:(id)delegate;

/*User data can be a long,or an id or void* cast to a long.  */
//cast to:投射
-(long)userData;
-(void)setUserData:(long)userData;

/*Don't use these to read or write. And don't close them,either!  */
-(CFSocketRef)getCFSocket;
-(CFReadStreamRef)getCFReadStream;
-(CFWriteStreamRef)getCFWriteStream;

/**
 * Once one of these methods is called, the AsyncSocket instance is locked in, and the rest can't be called without
 * disconnecting the socket first.  If the attempt times out or fails, these methods either return NO or
 * call "onSocket:willDisconnectWithError:" and "onSockedDidDisconnect:".
 **/
//
- (BOOL)acceptOnPort:(UInt16)port error:(NSError **)errPtr;
- (BOOL)acceptOnAddress:(NSString *)hostaddr port:(UInt16)port error:(NSError **)errPtr;
- (BOOL)connectToHost:(NSString *)hostname onPort:(UInt16)port error:(NSError **)errPtr;
- (BOOL)connectToAddress:(NSData *)remoteAddr error:(NSError **)errPtr;

-(void)disconnect;
-(void)disconnectAfterWriting;
-(BOOL)isConnected;
-(NSString *)connectedHost;
-(UInt16)connectedPort;
-(BOOL)isIPv4;
-(BOOL)isIPv6;

/**
 * The following methods won't block. To not time out, use a negative time interval.
 * If they time out, "onSocket:disconnectWithError:" is called. The tag is for your convenience.
 * You can use it as an array index, step number, state id, pointer, etc., just like the socket's user data.
 **/

//下面這些方法不會阻塞。如果想沒有timeout 使用一個負數time interval
//如果time out時間用光了，會調用"onSocket:disconnectWithError:"方法。tag只是為了方便，就像socket中的user data一樣。

/**
 * This will read a certain number of bytes into memory, and call the delegate method when those bytes have been read.
 * If there is an error, partially read data is lost.
 * If the length is 0, this method does nothing and the delegate is not called.
 **/
//這個方法會從內存中讀入特定數值的字節，讀完之后會調用代理方法
//如果發生錯誤，被部分讀入的數據會消失
//如果length為0，這個方法什么都不做，代理也不會被調用
-(void)readDataToLength:(CFIndex)length withTimeout:(NSTimeInterval)timeout tag:(long)tag;

/**
 * This reads bytes until (and including) the passed "data" parameter, which acts as a separator.
 * The bytes and the separator are returned by the delegate method.
 *
 * 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)readDataToData:(NSData *)data withTimeout:(NSTimeInterval)timeout tag:(long)tag;

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

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


/* 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.
 **/
//向調用方法的socket寫入數據
-(void)writeData:(NSData *)data withTimeout:(NSTimeInterval)timeout tag:(long)tag;

/**
 * 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.
 **/
//返回當前讀/寫的進度（0.0~1.0），沒有讀/寫時返回NaN，在tag，done，total非空時要寫上
//typedef signed long CFIndex;
-(float)progressOfReadReturningTag:(long *)tag bytesDone:(CFIndex *)done total:(CFIndex *)total;
-(float)progressOfWriteReturningTag:(long *)tag bytesDone:(CFIndex *)done total:(CFIndex *)total;

/**
 * In the event of an error, this method may be called during onSocket:willDisconnectWithError: to read
 * any data that's left on the socket.
 **/
//在發生錯誤的時候，這個方法可能在onSocket:willDisconnectWithError:中被調用，用來讀取留在socket中的數據
- (NSData *)unreadData;

+(NSData *)unreadData;//0x0D0A
+(NSData *)CRLFData;//0x0D
+(NSData *)LFData;//0x0A
+(NSData *)ZeroData;//0x00
@end