NSStream

     流是位数据通过通信路径的连续传送序列。它是单向的，从一个应用程序的角度，流可以是输入流（读操作流）或者输出流（写操作流），除了基于文件的流之外，其余的都是non-seekable的。一旦流数据被提供或者被使用，数据就不能够从流中获取到。

     Cocoa包括三种与流有关的类：NSStream，NSInputStream，NSOutputStream. NSStream是抽象类，它定义了流对象的基本接口和属性。NSInputStream和NSOutputStream是NSStream的子类，它们实现了输入流和输出流的基本操作。你可以为存储在内存中，向文件或者C buffer写的流数据创建NSOutputStream对象；可以为从NSData对象和文件中读取的流数据创建NSInputStream对象；也可以在网络套接字的两端创建NSInputStream和NSOutputStream对象，通过流对象，你可以不用一次性将所有的流数据加载到内存中。下图是就输入流和输出流对象的源和目的地为依据对输入流和输出流的分类：

        

    NSStream及其子类进行的是比较底层的开发，对于某些特殊的需求如果有顶层的Cocoa API更加适合的话（比如NSURL，NSFileHandle），那么就用顶层的API进行编程。

    流对象有许多属性，大多数属性都和网络安全及其配置有关，也就是SSL和SOCKS代理信息。另外有两个重要的属性，一个是NSStreamDataWrittenToMemoryStreamKey，对于一个输出流它可以用来获取到写入内存中的数据。另一个是NSStreamFileCurrentOffsetKey，对于一个基于文件的流，可以用它操作读或者写的位置。

    每个流对象都有一个与其相关联的delegate，如果其delegate没有显示的设置，那么这个流对象自身成为其delegate（对于自定义子类的话这是一个很有用的约定）。流对象调用它唯一的delegate方法stream:handleEvent:来处理所有与stream-related事件。对于传入参数中的events事件，它指示了什么时候输入流中有数据可供读入，什么时候输出流中有空间可供数据写入。对于这两个事件中的NSStreamEventHasBytesAvailable事件，delegate向该stream发送read:maxLength:消息从流中读取数据，对于NSStreamHasSpaceAvailable事件，delegate向该stream发送write:maxlength:向流中写入数据。

    NSStream是建立在Core Foundation的CFStream层之上的。这层紧密的关系意味着NSStream的具体子类-NSInputStream和NSOutputStream与Core Foundation中的CFReadStream和CFWriteStream是一一对应的。尽管Cocoa和Core Foundation的stream APIs有很大的相似性，但是它们的实现却不尽相同，Cocoa stream类使用delegate模式来实现异步操作（比如将其布置在run loop之上），而Core Foundation使用客户端的回调。Core Foundation的stream类型设置的是client（在Core Foundation中叫做context），NSStream中设置的delegate，这是两个不同的概念，不应该把设置delegate和设置context搞混淆。

    相比CFStream而言，NSStream有更强的可扩展性，你可以生成NSStream，NSInputStream，NSOutputStream的子类来自定义其属性和方法。For example, you could create an input stream that maintains statistics on the bytes it reads; or you could make a NSStream subclass whose instances can seek through their stream, putting back bytes that have been read. NSStream has its own set of required overrides, as do NSInputStream and NSOutputStream.

 

 NSInputStream

原文：Reading From Input Streams

ios cocoa 编程，从NSInputStream中读入数据包括几个步骤：

1.从数据源创建和初始化一个NSInputStream实例

2.将输入流对象配置到一个run loop，open the stream

3. 通过流对象的delegate函数处理事件

4. 当所有数据读完，进行流对象的内存处理

 

一，使用流对象的准备工作

在使用NSInputStream对象之前你必须有流的数据源，数据源的类型可以是文件，NSData对象，或者一个网络套接字。

NSInputStream的初始化函数和工厂方法可以从NSData和文件创建和初始化一个NSInputStream的实例。下面的例子是从文件创建一个NSInputStream的实例：

 - (void)setUpStreamForFile:(NSString *)path {
     // iStream is NSInputStream instance variable
     iStream = [[NSInputStream alloc] initWithFileAtPath:path];
     [iStream setDelegate:self];
     [iStream scheduleInRunLoop:[NSRunLoop currentRunLoop]
         forMode:NSDefaultRunLoopMode];
     [iStream open];
 }

上面的例子显示，当你创建对象之后你应该设置其delegate。当把NSInputStream对象配置到一个run loop，并且有与流相关的事件(例如流中有可读数据)发生时，该对象会收到stream:handleEvent:消息。

 

在你open stream之前，给流对象发送一个scheduleInRunLoop:forMode:消息，来将该对象配置到一个run loop接收stream events。这样，当流中没有数据可读时可以避免delegate阻塞。如果流是发生在另一个线程，你需要确认该流对象是配置在那个线程的run loop中。你不应该尝试从一个除了包含该流对象的run loop的线程的其他线程中对流进行操作。最后，对NSInputStream对象发送open消息开始对输入数据的流操作。

 

二，处理Stream Events

当你对一个流对象发送open消息之后，你可以查找到它的当前状态。通过下面的消息可以知道流对象中是否有数据可读，以及任何错误的属性:

 

• streamStatus

• hasBytesAvailable

• streamError

返回的状态是一个NSStreamStatus常量，它可以指示流对象是处于opening，reading，或者at the end of the stream等等。返回的错误是一个NSError对象，它封装了可能发生的所有错误信息。

 

重要的是，一旦 open 流对象，流对象会一直向其delegate发送stream:handleEvent: 消息直到到达了流对象的末尾。这些消息的参数中包含一个指示流事件类型的NSStreamEvent常量。对NSInputStream对象而言，最常用的事件类型是NSStreamEventOpenCompleted，NSStreamEventHasBytesAvailable，NSStreamEventEndEncountered。我们尤其感兴趣的应该是NSStreamEventHasBytesAvailable事件。下面的例子就是一个处理NSStreamEventHasBytesAvailable事件的好的方法：

 - (void)stream:(NSStream *)stream handleEvent:(NSStreamEvent)eventCode {

     switch(eventCode) {
         case NSStreamEventHasBytesAvailable:
         {
             if(!_data) {
                 _data = [[NSMutableData data] retain];
             }
             uint8_t buf[1024];
             unsigned int len = 0;
             len = [(NSInputStream *)stream read:buf maxLength:1024];
             if(len) {
                 [_data appendBytes:(const void *)buf length:len];
                 // bytesRead is an instance variable of type NSNumber.
                 [bytesRead setIntValue:[bytesRead intValue]+len];
             } else {
                 NSLog(@"no buffer!");
             }
             break;
         }
         // continued
 }

 

stream:handleEvent: 函数使用switch语句来判别NSStreamEvent常量，当这个常量是MSStreamEventHasBytesAvailable的时候，delegate函数会lazy create 一个NSMutableData对象_data来接收读取的数据。然后声明一个大小为1024的uint8_t类型数组buf，调用read:maxLength:函数从stream中读取指定大小的数据到buf中，如果读取成功，delegate将会将读取到的数据添加到NSMutableData对象_data中，并且更新总的读取到的数据bytesRead.

至于一次从stream中读取多大的数据，一般来说，使用一些常用的数据大小规格，比如说512Bytes，1kB，4kB(一个页面大小)。

 

三，处理stream object

当NSInputStream对象到达steam的末尾的时候，它会向stream:handleEvent:函数发送一个NSStreamEventEndEncountered事件类型常量，delegate函数应该做出与准备使用流对象相反的操作，也就是说，需要关闭流对象，从run loop中移除，最终释放流对象。如下面的代码所示：

 - (void)stream:(NSStream *)stream handleEvent:(NSStreamEvent)eventCode
 {
 switch(eventCode) {
 case NSStreamEventEndEncountered:
         {
             [stream close];
             [stream removeFromRunLoop:[NSRunLoop currentRunLoop]
                 forMode:NSDefaultRunLoopMode];
             [stream release];
             stream = nil; // stream is ivar, so reinit it
 break;
         }
 // continued ...
     }