AsyncSocket文档

AsyncSocket是一个TCP / IP套接字的网络库，旨在有效地处理分组数据。该库有两个文件，​​一个公共可可类。

该图书馆是公共领域，最初是由达斯汀沃斯，和现在Deusty和可可社区维护。

对于支持，请访问谷歌CocoaAsyncSocket代码页的http://code.google.com/p/cocoaasyncsocket/

内容

  1. 介绍
  2. 套接字基础知识
  3. 使用AsyncSocket
  4. AsyncSocket参考
  5. API更改
  6. API指数

关于AsyncSocket

可可API提供了一些网络类，适合下载和上传图像和文件。这些类支持HTML，FTP等协议，但不能与特定应用的协议中使用。如果没有支持特定应用协议的低层次的套接字类，开发者必须自定义代码网络使用BSD或碳的功能与解决方案相结合 NSFileHandle， NSInputStream和 NSOutputStream。这些函数和类不为TCP / IP网络在一个真正的可可应用进行优化，并且可能难以集成。

AsyncSocket提供易于集成的“发射后不管”的网络，可以很容易为你的应用程序支持网络。其特点包括：

关于本文档

本文假设读者已经有网络的广大市民的理解，以及可可和Objective-C编程的开发人员的理解。

套接字基础知识

在联网的说法，一台计算机是一主机为多个插座。甲插座是通信信道的一端称为一个网络连接 ; 另一端是另一插座。从自己的观点来看，任何插座是本地套接字，和插座在连接的另一端是远程套接字。

要建立连接，两个插座之一，连接插座，必须与其他插座，侦听套接字，并监听套接字必须接受的连接。联系监听套接字，在连接插座必须知道它的套接字地址。每个插座有一个套接字地址。的地址由两部分组成：主机地址和端口号。主机地址是计算机的IP地址，端口号唯一地标识承载的计算机上的每个插座。

一台计算机可以有多个主机地址。这将有一个地址对为每一种可能的连接方法（例如，以太网卡，调制解调器，AirPort卡，VPN连接）和一对用于连接到其自身（称为“本地主机”）。每对中的一个地址是IPv4地址，如“192.168.3.1”，而另一个是IPv6地址，如“为fe80 :: 230：65ff：FE29：aa9d”

一个地址，如“www.google.com”对应于一个主机地址，但它不是一个主机地址本身。它是一个DNS地址或DNS名称，这是由一个转换为主机地址的DNS查找操作。一个网址，如“http://www.google.com:80”同样不是一个主机地址。URL可以包括一个DNS名，主机地址，端口号和其他信息。

在不同的主机上，甚至在同一主机上运行的应用程序，可以使用套接字与彼此通信。看它的另一种方式，每个插座提供通信服务给它的客户端应用程序。应用程序发送和接收的数据和从彼此，他们可以解释和在采取行动。该数据是由字节，布置成所谓的基团包和发送，并根据所接收的协议随后两个应用程序。

的协议建立每个数据包的结构，在何种情况下任何特定分组应该被发送，和规则来处理异常情况。它还规定了每个客户端应用程序的角色。在一个客户-服务器体系结构，有些应用程序（在服务器）提供使用的其他应用程序（服务客户端）。在一个对等体的对等体系结构，有些应用程序（在对等体）作为在同一时间的客户端和服务器。

插槽的限制

在某些方面，一个插座就像一个文件。两者都包含有开始和结束的数据。既可以写入或读出。但在其他方面，他们不同，这些差异驱动协议的设计。

首先，虽然一个文件是通常用于读出或写入，一个插座是交互式的。应用程序必须能够打断，并提醒对方，改变对方的行为。因为这个原因，数据被分成数据包，和这种划分留下一个开口，用于中断。

其次，虽然一个文件具有已知大小，插座不具有大小。一个应用程序不能知道多少数据留在当前包中，除非协议本身指定此。因此，所有的数据包包括隐式或显式的大小的信息或标记，以指示当数据包结束。

第三，虽然一个文件是可靠的，一个插座是不可靠的。当从插座读取，数据到达块中，每个块之间可能的大的延迟，并且没有办法知道一个特定的延迟是否是因为由于意外断开高流量或。因此，应用程序被迫把长的延迟，如果它是一个断线，并且协议规定超时和重试的消息来规范这一点。

该AsyncSocket库的目的​​是使这些协议的考虑容易对付。

数据包结构

网络通信协议采用某些共同所有的协议的基本要素。这些都是：

“ 解析包 “介绍如何使用AsyncSocket方法来读取这些不同的元素。

使用AsyncSocket

该AsyncSocket库由一个类，也称为AsyncSocket。的一个实例AsyncSocket表示一个插座，它可以是一个侦听套接字或一个连接插座。一个实例，也可以断开，在这种情况下，它并不代表一个有效的插座。在本文档中，术语“插座”和“实例AsyncSocket “用于几乎互换。

要使用AsyncSocket类项目，新增AsyncSocket.m和/System/Library/Frameworks/CoreServices.framework到项目，并导入AsyncSocket.h到每个需要它的文件。

此版本AsyncSocket的需要Mac OS X 10.4或更高版本。如果你必须支持Mac OS X 10.3，您可以使用AsyncSocket版本3.13。

插座所有权

在客户端 - 服务器体系结构中，应用程序充当客户端通常采用一个连接插座与服务器进行通信，和一个应用程序充当服务器通常采用一个侦听套接字接受来自客户端和几个连接插座连接与连接到通信客户端。在一个对等架构，应用程序通常采用一个监听套接字和若干连接插座，就好像它是一台服务器。

每个插座应该由管理连接控制器类。此类应负责：

连接插座的集合应该由管理连接阵列控制器。这个类应该负责创建，并根据需要摧毁单个连接控制器。每个管理连接控制器应该保持通报其状态的连接阵列控制器。

如果应用程序有一个侦听套接字，应该拥有和连接阵列控制器进行管理。当监听套接字接受连接，连接阵列控制器应建立负责管理新连接的新连接器。

委托方法

的一个实例AsyncSocket在完成某些操作或遇到某些错误将消息发送到它的委托对象。的所有实例AsyncSocket应该有一个代表响应这些消息正确。的委托对象应该是插座的连接器或连接阵列控制器。

的委托对象应按照插座的目的实现以下委托方法（见“ 参考AsyncSocket “下面的具体描述）：

你很少会需要改变一个插座的委托，但在需要时，要小心。如果一个套接字完成任何读或写在旧的委托发起的行动，新的代表将被通知，不老的委托。您可以检查待处理的读取或发送写操作-canSafelySetDelegate：套接字。请参阅“ 阅读与写作 “下面的未决读或写操作的讨论。

的几个实例AsyncSocket可以安全地共享一个委托对象。每个实例传递本身，因为它发出的任何委托消息的第一个参数。这样区分的委托对象AsyncSocket实例。

接受，连接和断开

要启动到远程套接字在给定的套接字地址的连接，发送-connectToHost：onPort：错误：到插座，传递主机地址和端口作为参数。主机地址可以是IP地址或DNS名称，包括“本地主机”。DNS名称不包含端口号。

要建立一个监听套接字给定端口，发送-acceptOnPort：错误：套接字。套接字将侦听所有可用的主机地址。要建立一个套接字侦听只有一个地址，发送-acceptOnAddress：端口：错误：。有选择地向特定线程直接传入的连接，实现-onSocket：wantsRunLoopForNewSocket：在插座的委托。

要改变套接字的底层的性能CFReadStream或CFWriteStream对象（例如，为了支持SSL连接）实施-onSocketWillConnect：在插座的委托。

干净断开插座，送-disconnectAfterWriting套接字。此方法将断开连接之前完成所有写操作。要立即断开，送-disconnect。在两种情况下，插座将发送-onSocketDidDisconnect：给委托后它完成断开。

如果远程干净插座从本地插座断开，本地套接字将发送-onSocket：willDisconnectWithError：到委托。该消息的错误论点将是零（请参阅“ 错误处理 “下）。本地套接字将发送-onSocketDidDisconnect：到委托。

阅读和写作

AsyncSocket处理读取和写入操作本身。您可以指定你想要的操作，并AsyncSocket拿它出来尽快并发送消息给委托时，操作完成。

AsyncSocket支持三个读出操作（“读与长度”，“读至数据”，和“读任意”）和一个写操作（“写数据”）。

调用读取或写入方法如果可能的话会立即执行请求的操作。但是，如果该操作不能立即完成，它将被放置在一个读或写队列。AsyncSocket将继续在后台顺序执行排队的操作。

要检查当前执行的“读来长”或“写数据”操作的进度，您可以发送-progressOfReadReturningTag：bytesDone：总：或-progressOfWriteReturningTag：bytesDone：总：套接字。这些方法返回0.0和1.0之间的十进制数，而你也可以得到读取或写入的总字节数。

该读写操作支持可选的超时。超时值是几秒钟的十进制数，例如1.5。超时值指定的操作可以采取一次开始多久。排队的操作不会开始运行的时间，直到它开始执行。AsyncSocket如果你发送一个负的超时参数将使用系统定义的超时值。

如果一个操作耗尽的时间完成之前，插座将断开。如果你的协议支持，从拖延已久的传输恢复机制，可以通过提供自己的“软”超时NSTimer的对象，而不是或除了AsyncSocket自己的超时系统。

当一个操作已在规定时间内完成，套接字将消息发送到其委托（无论是-onSocket：didReadData：withTag：或-onSocket：didWriteDataWithTag： ）。的委托对象应作出适当反应，发出另一次读或写邮件到插座是必要的。

为了帮助恰当的委托对象响应，您可以提供一个标签值作为读取参数或写入消息。标记值可以是整数，指针或对象ID。标签值不被发送到远程套接字，和远程套接字不发送标记值到本地套接字。但是在完成该操作由本地套接字发送到其代表该消息包括最初提供的标记值。标记值可以用于“记住”其下操作开始的情况。标记值可以标记类型的操作，或指定的多操作处理的步骤。

解析包

解析一个数据包，或阅读数据流，一行文字或数据流头，考虑如何把它分解成一系列简单的读取操作。

这里有一些技巧，你可以用它来读取和解析协议的内容：

错误处理

如果一个插座遇到输入/输出错误，或如果一个读或写操作超时，AsyncSocket假定连接已被中断，必须要重新建立。套接字将继续断开本身。远程套接字将通常由它自己的客户端应用程序被断开。

在断开本地套接字，一个AsyncSocket实例将发送-onSocket：willDisconnectWithError：它的委托对象。此消息的第二个参数是一个NSError对象。该目的可以含有POSIX，Mac OS或者CFStream错误代码，由对象的指示-domain方法。它也可以含有AsyncSocket特异性错误代码。请参阅“ 错误 “的详细信息。

在其执行-onSocket：willDisconnectWithError：的方法，该委托对象可以通过发送检索所有未接收的数据（包括来自任何部分完成的读取操作的数据）-unreadData套接字。

委托对象后willDisconnectWithError：-onSocket方法返回时，套接字将被断开。然后，它将发送-onSocketDidDisconnect：到委托。

线程和运行循环

一个AsyncSocket实例必须在同一个运行循环一起使用。其运行循环活动发生在NSDefaultRunLoopMode模式。

一个AsyncSocket实例可以使用来自一个工作线程或主线程。然而，每个实例应仅由一个线程使用，因此，该实例不从错误的线程上下文中调用委托方法。

要创建一个连接或在特定线程监听套接字，只需创建套接字在该线程的上下文中。

监听套接字创建一个新的socket时，接受连接。为了确保这一新的插座在特定线程创建的，从监听套接字的返回线程的运行循环-onSocket：wantsRunLoopForNewSocket：委托方法。

定制AsyncSocket

AsyncSocket并不旨在是子类。然而，由于AsyncSocket是在公共领域，你可以改变它，就像你喜欢你自己的项目。源代码的编写是可以理解的。

AsyncSocket使用CFSocket，CFReadStream和CFWriteStream内部。您可以直接访问这些并设置任何属性或行为，您可能需要。该-onSocketWillConnect：委托方法旨在促进这一点。

AsyncSocket参考

请参阅“ API指数 “的消息，方法，类型和常量的字母顺序列表。

初始化和取消分配消息

AsyncSocket不提供自动释放方便初始化。

-init -initWithDelegate： -initWithDelegate：USERDATA： -dealloc

-init

此消息初始化接收器，无需设置委托。

句法

- （ID）的init

参数

无。

返回值

的一个实例AsyncSocket。

错误

无。

-initWithDelegate：

此消息初始化接收机，设置代表在同一​​时间。

句法

- （ID）initWithDelegate：（ID）代表

参数

代表

一个对象，将作为委托接收器。该代表应实施必要的AsyncSocketDelegate方法。

可能是零。

返回值

的一个实例AsyncSocket。

错误

无。

-initWithDelegate：USERDATA：

此消息初始化接收机，同时设定该委托和用户数据。此方法是AsyncSocket实例的指定初始化。

句法

- （ID）initWithDelegate：（ID）代表用户数据：（长）USERDATA

参数

代表

一个对象，将作为委托接收器。该代表应实施必要的AsyncSocketDelegate方法。

可能是零。

USERDATA

将与接收器相关联的值。它可以在以后通过检索一个-userData：消息。

返回值

的一个实例AsyncSocket。

错误

无。

-dealloc

此消息将释放接收器，如果需要的话断开。

句法

 - （无效）的dealloc

参数

无。

返回值

无。

错误

无。

用户数据信息

-userData -setUserData：

-userData

该消息返回接收器的当前用户数据，与接收器相关联的arbitary值。

句法

- （长）USERDATA

参数

无。

返回值

当前用户数据。

错误

无。

-setUserData：

此消息设置接收者的用户数据，与接收器相关联的arbitary值。

句法

- （无效）setUserData：（长）USERDATA

参数

USERDATA

将与接收器相关联的值。

返回值

无。

错误

无。

代表团消息

-delegate -setDelegate： -canSafelySetDelegate

-delegate

该消息返回接收当前的委托对象。

句法

- （ID）代表

参数

无。

返回值

目前委托对象，或零。

错误

无。

-setDelegate：

此消息集接收机的委托对象。该委托对象不保留。

句法

- （无效）setDelegate：（ID）代表

参数

代表

一类是将充当委托接收机的一个实例。要实施必要的AsyncSocketDelegate方法。

可能是零。

返回值

无。

错误

无。

如果委托对象发生变化，旧的委托对象将不再接收，这可能期望为未决读或写操作，它开始产生的任何消息。为了确保没有挂起读或写操作，委托对象可以调用-canSafelySetDelegate： 。

-canSafelySetDelegate

该消息可以被发送到确定一个新的委托对象是否需要被意识到挂起的读或写操作。

句法

- （BOOL）canSafelySetDelegate

参数

无。

返回值

YES，如果接收器有任何未决的读或写操作。

否，如果接收机没有挂起的读或写操作。

错误

无。

连接消息

-connectToHost:onPort:error: -acceptOnPort:error: -acceptOnAddress:port:error: -isConnected -disconnect -disconnectAfterWriting -connectedHost -connectedPort -localHost -localPort

-connectToHost：onPort：错误：

这个消息建立从接收呼出连接。

句法

- （BOOL）在connectToHost：（*的NSString）主机名onPort：（UINT16）端口错​​误：（NSError **）ERR

参数

主机名

DNS名称或IP地址与接收应该连接。IPv4和IPv6地址的支持。

港

到接收器应连接的端口号。

犯错

一个地址NSError对象的指针。在一个错误的情况下，指针将被设置为NSError描述错误的对象。

发送方可以通过零，如果它不希望检索任何NSError对象。

返回值

返回YES，如果连接成功。

这并不表示套接字准备好使用。该插座仅准备当-onSocket：didConnectToHost：端口：委托方法被调用。

错误

返回否和一个NSError在下列条件下对象：

  • 主机是不是一个有效的地址，或者没有这样的地址。
  • 插座无法创建，或者不能连接到该地址。

返回YES并调用-onSocket：willDisconnectWithError：在下列条件下：

  • 在读取和写入数据流无法连接或打开。

引发AsyncSocketException如果已经连接套接字或接受连接，如果没有委托已设置。

如果接收机返回是，它会继续建立连接。当成功建立连接，或者无法建立，接收机将发送一个适当的消息给它的委托对象。

读和写操作可以被排队之前的成功建立连接。他们将被执行后，连接完成。

-acceptOnPort：错误：

此消息确立了接收器监听套接字将接受传入的连接。

句法

- （BOOL）acceptOnPort：（UINT16）端口错​​误：（NSError **）ERR

参数

港

在该接收器应该接受连接的端口号。

犯错

一个地址NSError对象的指针。在一个错误的情况下，指针将被设置为NSError描述错误的对象。

发送方可以通过零，如果它不希望检索任何NSError对象。

返回值

返回YES如果接收机被成功接受在指定的端口连接。

错误

返回NO和NSError如果套接字不能被创建，或不能接受指定的端口上的连接对象。

引发AsyncSocketException如果已经连接套接字或接受连接，如果没有委托已设置。

该接收器建立与监听套接字SO_REUSEADDR选项集。

在从远程套接字的连接的情况下，接收器将创建一个新的AsyncSocket实例。新的实例将具有相同的委托对象的接收器，以及将尝试完成连接到远程套接字。

有新的实例的尝试的三种可能的结果。首先，尝试能成功。其次，尝试可能会失败，因为本地套接字无法创建。第三，尝试可能因为另一个问题失败。

如果成功的话，接收器会发送-onSocket：didAcceptNewSocket：和-onSocket：wantsRunLoopForNewSocket：它的委托对象。在这一点上的委托对象可以改变新实例的委托对象或分配一个运行循环。后委托方法返回，新的实例将发送-onSocket：didConnectToHost：端口：它的委托对象。

如果不成功，因为本地套接字无法创建，新的实例将被销毁默默地，并且接收器将继续接受连接。

如果不成功某些其他原因，接收器就会发出-onSocket：didAcceptNewSocket：和-onSocket：wantsRunLoopForNewSocket：它的委托对象。委托方法返回后，新的实例将发送-onSocket：willDisconnectWithError：其委托有关故障状况的详情。

-acceptOnAddress：端口：错误：

此消息确立了接收器监听套接字，将接受一个特定的主机地址和端口传入的连接。

句法

- （BOOL）acceptOnAddress：（*的NSString）端口地址hostaddr：（UINT16）端口错​​误：（NSError **）ERR

参数

正确提供hostaddr

主机地址在哪方应当接受连接。地址应该是IPv4或IPv6地址，如“192.168.3.1”或“为fe80 :: 230：65ff：FE29：aa9d”

如果为零或空字符串，效果是一样的-acceptOnPort：错误：消息。

港

在该接收器应该接受连接的端口号。

犯错

一个地址NSError对象的指针。在一个错误的情况下，指针将被设置为NSError描述错误的对象。

发送方可以通过零，如果它不希望检索任何NSError对象。

返回值

返回YES如果接收机被成功接受在指定的端口连接。

错误

返回NO和NSError如果套接字不能被创建，或不能接受指定的地址或端口的连接对象。

引发AsyncSocketException如果已经连接套接字或接受连接，如果没有委托已设置。

见-acceptOnPort：错误：了解更多信息。

-isConnected

该消息可被发送，以确定接收机是否被连接以及能够读取和写入。

句法

- （BOOL）isConnected

参数

无。

返回值

是，如果该接收器连接，并能够发送和接收数据。

否，如果接收机没有连接，接受连接，或不能够发送和接收数据。

错误

无。

如果输入或输出流都达到EOF时，接收器返回否。如果输入或输出流是开放的，但在其他一些错误状态时，接收器返回YES。

如果接收器接收传入的连接，它总是返回NO。

-disconnect

此消息立即断开连接接收器。

句法

- （无效）断开

参数

无。

返回值

无。

错误

无。

如果接收器被接受传入的连接，它不会停止这样做。任何待读或写操作都将被丢弃。

此方法返回后，客户端应用程序可以发送-connectToHost：onPort：错误：，-acceptOnPort：错误：，或：-acceptOnAddress：端口：错误再次消息。

-disconnectAfterWriting

完成所有待定写操作之后，此消息将断开接收器。待处理读操作不会阻止接收机断开。

句法

- （无效）disconnectAfterWriting

参数

无。

返回值

无。

错误

无。

而挂起写操作完成，接收器会忽略任何进一步的读或写邮件。其他消息可以发送如常。

-connectedHost

该消息返回所连接的远程套接字作为一个字符串的IP地址。

句法

- （的NSString *）connectedHost

参数

无。

返回值

如果接收器连接，一个IP地址。

如果接收器未连接时，零。

错误

无。

-connectedPort

该消息返回连接的远程套接字的端口号。

句法

- （UINT16）connectedPort

参数

无。

返回值

如果接收器被连接，一个端口号。

如果接收器未连接时，0。

错误

无。

-localhost

该方法返回接收者作为一个字符串的本地IP地址。

句法

- （的NSString *）本地主机

参数

无。

返回值

如果接收器连接，一个IP地址。

如果接收器未连接时，零。

错误

无。

如果计算机有多个IP地址，一个在使用的接收器将被退回。如果计算机是在NAT之后，返回的IP地址将是一个局域网地址，而不是可用的局域网之外。

-localPort

此方法返回接收器的端口号。

句法

- （UINT16）本地端口

参数

无。

返回值

如果接收器被连接，一个端口号。

如果接收器未连接时，0。

错误

无。

如果计算机是在NAT之后，返回的端口号将是一个局域网地址，不准确局域网之外。

读取和写入信息

-readDataToLength:withTimeout:tag: -readDataToData:withTimeout:tag: -readDataWithTimeout:tag: -writeData:withTimeout:tag: -progressOfReadReturningTag:bytesDone:total: -progressOfWriteReturningTag:bytesDone:total:

-readDataToLength：withTimeout：标签：

此消息队列读操作。接收器将读取一定数量从插座字节。

句法

- （无效）readDataToLength：（CFIndex）长withTimeout：（NSTimeInterval）超时标签：（长）标签

参数

长度

字节接收方应该读数。

如果0，接收器不执行任何操作，并不会发送-onSocket：didReadData：withTag：其委托。

暂停

秒从读出操作开始时的数目，其中该操作必须完成。如果操作花费的时间超过此时间间隔，操作超时。

如果否定的，则读取操作不会超时。

标签

应用程序定义的整数或指针将被作为参数传递给-onSocket：didReadData：withTag：邮件发送到该委托。

返回值

接收器将发送-onSocket：didReadData：withTag：对委托对象时的读操作已经完成。接收到的数据将被传递作为消息的参数。

错误

接收器将发送-onSocket：willDisconnectWithError：下列情况下，委托对象：

  • 读操作超时。
  • 接收机从远程插座断开。
  • 发生其他I / O错误。

该-onSocket：willDisconnectWithError：方法可以检索部分通过发送接收数据的标签：-readDataWithTimeout套接字。

当字节已经成功接收，接收器就会发出-onSocket：didReadData：withTag：它的委托对象。

读操作将被立即如果可能进行。如果是，则接收机将从该方法返回之前发送消息。

-readDataToData：withTimeout：标签：

此消息队列读操作。接收器将读取的字节，直到（并包括）在传递的字节序列数据的说法。该序列作为一个分离器或分隔符。

句法

- （无效）readDataToData：（NSData的*）数据withTimeout：（NSTimeInterval）超时标签：（长）标签

参数

数据

一个序列是标记的读操作的结束字节。

如果为零或空，接收器不执行任何操作，并不会发送-onSocket：didReadData：withTag：其委托。

暂停

秒从读出操作开始时的数目，其中该操作必须完成。如果操作花费的时间超过此时间间隔，操作超时。

如果否定的，则读取操作不会超时。

标签

应用程序定义的整数或指针将被作为参数传递给-onSocket：didReadData：withTag：邮件发送到该委托。

返回值

接收器将发送-onSocket：didReadData：withTag：对委托对象时的读操作已经完成。接收到的数据将被传递作为消息的参数。这将包括分隔符。

错误

接收器将发送-onSocket：willDisconnectWithError：下列情况下，委托对象：

  • 读操作超时。
  • 接收机从远程插座断开。
  • 发生其他I / O错误。

该-onSocket：willDisconnectWithError：方法可以检索部分通过发送接收数据的标签：-readDataWithTimeout套接字。

当字节已经成功接收，接收器就会发出-onSocket：didReadData：withTag：它的委托对象，通过所有接收的字节数作为参数，包括分隔序列。

读操作将被立即如果可能进行。如果是，则接收机将从该方法返回之前发送消息。

注意，此方法不是字符集感知。如果一个字符应该发生要被编码到相匹配的定界序列字节序列，读取操作可以过早地结束。

-readDataWithTimeout：标签：

此消息队列读操作。接收器将检索第一个可用的字节。

句法

- （无效）readDataWithTimeout：（NSTimeInterval）超时标签：（长）标签

参数

暂停

秒从读出操作开始时的数目，其中该操作必须完成。如果操作花费的时间超过此时间间隔，操作超时。

如果否定的，则读取操作不会超时。

标签

应用程序定义的整数或指针将被作为参数传递给-onSocket：didReadData：withTag：邮件发送到该委托。

返回值

接收器将发送-onSocket：didReadData：withTag：其委托对象时，读操作已经完成。接收到的数据，如果有的话，将被作为参数传递。

错误

会发生错误在这些条件下：

  • 读操作超时。
  • 接收机从远程插座断开。
  • 发生其他I / O错误。

当字节已经成功取回，接收器将发送-onSocket：didReadData：withTag： 它的委托对象，通过所有接收的字节数作为参数。

-writeData：withTimeout：标签：

此消息队列写操作。接收器将写入一个NSData的对象插座。

句法

- （无效）writeData：（NSData的*）数据withTimeout：（NSTimeInterval）超时标签：（长）标签

参数

数据

应写入到远程套接字的数据。

如果为零，接收器不执行任何操作，并不会发送-onSocket：didWriteDataWithTag：其委托。

暂停

秒从写操作的开始的数，其中该操作必须完成。如果操作花费的时间超过此时间间隔，操作超时。

如果否定的，则写操作不会超时。

标签

应用程序定义的整数或指针将被作为参数传递给-onSocket：didWriteDataWithTag：邮件发送到该委托。

返回值

无。接收器将发送-onSocket：didWriteDataWithTag：对委托对象时的写操作已经完成。

错误

接收器将发送-onSocket：willDisconnectWithError：下列情况下，委托对象：

  • 写操作超时。
  • 接收机从远程插座断开。
  • 发生其他I / O错误。

当字节已经成功发送，接收器就会发出-onSocket：didWriteData：withTag：它的委托对象。

写操作将立即如果可能进行。如果是，则接收机将从该方法返回之前发送消息。

-progressOfReadReturningTag：bytesDone：总：

该消息可以被发送到确定当前的读操作的进度。

句法

- （浮点）progressOfReadReturningTag：（长*）标记bytesDone：（CFIndex *）完成总：（CFIndex *）总

参数

标签

一个变量的地址。当此方法返回时，变量将包含当前的读操作的标签。如果没有当前的读操作，该变量将不会被改变。

发送者可以通过空，如果它不希望检索标签。

做完

一个变量的地址。当此方法返回，变量将包含当前的读操作已读的字节数。如果没有当前的读操作，该变量将不会被改变。

发送方可以通过空，如果它不希望检索读的字节数。

总

一个变量的地址。当此方法返回，变量将包含当前的读操作期望读取的字节的总数。这个值是唯一有意义的，如果当前的读操作是一个“读与长度”操作。如果没有当前的读操作，该变量将不会被改变。

发送方可以通过空，如果它不希望检索所读取的字节的总数。

返回值

十进制值。

  • 为NaN表明存在当前正在执行没有读操作。使用isnan（）函数来测试这种返回值。
  • 0.0表示没有字节被读取的份额。
  • 1.0表示所有字节已被读出的总和，或字节的总数必须读取是不知道的。

错误

无。

-progressOfWriteReturningTag：bytesDone：总：

该消息可以被发送到确定当前的写操作的进度。

句法

- （浮点）progressOfWriteReturningTag（长*）标记bytesDone：（CFIndex *）完成总：（CFIndex *）总

参数

标签

一个变量的地址。当此方法返回时，变量将包含当前的读操作的标签。如果没有当前的读操作，该变量将不会被改变。

发送者可以通过空，如果它不希望检索标签。

做完

一个变量的地址。当此方法返回，变量将包含已发送的字节数。如果没有当前的读操作，该变量将不会被改变。

发送方可以通过空，如果它不希望检索发送的字节的数目。

总

一个变量的地址。当此方法返回，变量将包含的字节的当前写操作被发送的总数。如果没有当前的读操作，该变量将不会被改变。

发送方可以通过空，如果它不希望检索所发送的字节总数。

返回值

十进制值。

  • 为NaN表明存在当前正在执行不写入操作。使用isnan（）函数来测试这种返回值。
  • 0.0表示没有字节已发送总量。
  • 1.0表示所有字节已发送总量的。

错误

无。

定界符消息

这些消息的结果是可以传递的常用分隔符数据的一个论点-readDataToData：withTimeout：标签：消息。

+ CRLFData + CRData + LFDATA + ZeroData

+ CRLFData

此方法返回CRLF字节序列，行分隔符为DOS和Windows。

句法

+（NSData的*）CRLFData

参数

无。

返回值

的一个实例的NSData含有字节0D0A。

错误

无。

+ CRData

此方法返回CR字节序列，Mac OS X的前行分隔的Macintosh操作系统

句法

+（NSData的*）CRData

参数

无。

返回值

的一个实例的NSData包含该字节0D。

错误

无。

+ LFDATA

此方法返回的LF字节序列，行分隔符为大多数Unix操作系统和Mac OS X.

句法

+（NSData的*）LFDATA

参数

无。

返回值

的一个实例的NSData包含该字节0A。

错误

无。

+ ZeroData

该方法返回一个零字节，分隔符为C字符串。

句法

+（NSData的*）ZeroData

参数

无。

返回值

的一个实例的NSData包含该字节00。

错误

无。

调试和自定义消息

-description -getCFSocket -getCFReadStream -getCFWriteStream

-description

该消息返回适用于调试目的接收机的描述。

句法

- （的NSString *）的说明

参数

无。

返回值

描述了接收器和其地位的字符串。

错误

无。

返回的描述不具有任何新行字符，并包括：

-getCFSocket

该消息返回内部CFSocket使用由接收器的实例是，使访问底层Unix套接字。

句法

- （CFSocketRef）getCFSocket

参数

无。

返回值

接收器的CFSocket参考号码，或NULL如果没有连接或接受连接。

错误

无。

不要关闭，读取或写入底层套接字。

-getCFReadStream

此方法返回内部CFReadStream使用由接收器的实例是，使访问底层碳流。

句法

- （CFReadStreamRef）getCFReadStream

参数

无。

返回值

接收器的CFReadStream参考号码，或NULL如果没有连接或接受连接。

错误

无。

不要关闭，读取或写入底层流。

-getCFWriteStream

此方法返回内部CFWriteStream正在使用的接收机实例，从而可以访问底层的碳流。

句法

- （CFWriteStreamRef）getCFWriteStream

参数

无。

返回值

接收器的CFWriteStream参考号码，或NULL如果没有连接或接受连接。

错误

无。

不要关闭，读取或写入底层流。

AsyncSocketDelegate方法

委托对象可以实现这些方法来应对AsyncSocket消息。

-onSocket:willDisconnectWithError: -onSocketDidDisconnect: -onSocket:didAcceptNewSocket: -onSocket:wantsRunLoopForNewSocket: -onSocketWillConnect: -onSocket:didConnectToHost:port: -onSocket:didReadData:withTag: -onSocket:didWriteDataWithTag:

-onSocket：willDisconnectWithError：

在出现错误的情况下，该插座被断开。插座断开连接之前发送此消息。

原型

- （无效）onSocket：（AsyncSocket *）袜子willDisconnectWithError：（NSError *）ERR

参数

袜子

发送AsyncSocket实例。

犯错

的错误造成的插座断开连接。

如果为零，则没有错误。这通常意味着套接字被干净地由远程客户端应用程序关闭。

条件

此消息被发送：

  • 如果有一个连接，超时，或者其他I / O错误。
  • 如果远程插座干净断开。
  • 前本地套接字被断开。

此消息的主要目的是给接收机有机会从连接检索任何剩余的缓存数据。该接收器可以做到这一点通过发送-readDataWithTimeout：标签：给发件人。

-onSocketDidDisconnect：

插座发送此消息被称为后它已断开。

原型

- （无效）onSocketDidDisconnect：（AsyncSocket *）袜

参数

袜子

发送AsyncSocket实例。

条件

发件人断开以任何理由后，此消息被发送。

接收器可以安全地释放寄件人在此方法。

-onSocket：didAcceptNewSocket：

插座将此消息发送到接收器提供了机会，以节省一个新的socket的适当位置。

原型

- （无效）onSocket：（AsyncSocket *）袜子didAcceptNewSocket：（AsyncSocket *）newSocket

参数

袜子

发送AsyncSocket实例。这个实例将接受连接。

newSocket

的新实例AsyncSocket。

条件

发件人接受传入连接，并创建一个新的实例之后，此方法被发送AsyncSocket来处理它。

当这个消息被发送，newSocket未完全连接到远程套接字。

接收机应该分配和保留newSocket，并且还可以设置一个更合适的委托。

-onSocket：wantsRunLoopF​​orNewSocket：

插座发送此消息，以确定哪些线程和运行循环的新的socket及其委托的方法应该进行操作。默认为当前运行循环。

原型

- （NSRunLoop *）onSocket：（AsyncSocket *）袜子wantsRunLoopF​​orNewSocket：（AsyncSocket *）newSocket

参数

袜子

发送AsyncSocket实例。这个实例将接受连接。

newSocket

的一个实例AsyncSocket。

返回值

实例NSRunLoop与目标线程关联。

条件

发件人接受传入连接，并发送所述后本方法发送didAcceptNewSocket：-onSocket消息。

当这个消息被发送，newSocket未完全连接到远程套接字。

接收机应返回的实例NSRunLoop与目标线程相关联。从所有代表消息newSocket将在该线程到运行循环的上下文中被发送，所有定时器将运行在该运行循环，而将出现在该线程的所有处理。

如果接收机不实现此方法中，发送者将使用当前线程和运行循环。

-onSocketWillConnect：

套接字发送此消息时，它是将要连接到远程套接字。

原型

- （BOOL）onSocketWillConnect：（AsyncSocket *）袜

争论

袜子

发件人。

返回值

是如果套接字应继续连接到远程套接字。这是默认如果此方法不是由接收器来实现。

NO取消连接。

条件

发送者尝试连接到之前这个消息发送：

此消息主要是为了给接收器中的机会来配置内部的属性CFReadStream或CFWriteStream实例。接收机应该返回YES或NO，指示发送者是否应继续连接。

如果接收器返回NO，连接尝试发起-connectToHost：onPort：错误：，该方法将返回NO其发送者，以及一个AsyncSocketCanceledError错误对象。

如果接收机返回否，且连接尝试通过远程套接字发起的，将报告任何错误。

-onSocket：didConnectToHost：端口：

插座发送此消息它是连接并准备读取或写入时。

原型

- （无效）onSocket：（AsyncSocket *）袜子didConnectToHost：（*的NSString）主机端口：（UINT16）端口

参数

袜子

发件人。

主持人

远程套接字的IPv4或IPv6地址。

这可能不同于发送到发送者的IP地址或DNS名称主机的参数-connectToHost：onPort：错误：。

港

远程套接字的端口。

条件

此消息发出后发送已成功连接到：

接收机可以选择断开发件人，或排队的读或写操作。

从这个方法的接收机返回后，插座将执行任何先前排队的读或写操作。

-onSocket：didReadData：withTag：

发送端发送此消息时，它成功完成读操作。它可以被调用read方法返回，或更高版本之前发送该消息。

原型

- （无效）onSocket：（AsyncSocket *）袜子didReadData：（NSData的*）数据withTag：（长）标签

参数

袜子

发件人。

数据

所接收的数据。

标签

该标签在读取邮件传递的参数。

条件

这个消息被发送后发送方已经成功地接收到请求的数据。

如果读操作失败，发送者会发送一个-onSocket：willDisconnectWithError：消息代替。

接收机应该处理的数据和队列读或根据需要写入操作或断开。

-onSocket：didWriteDataWithTag：

发送端发送此消息时，一个写操作已成功完成。它可能会发送此消息之前，调用write方法返回，或更高版本。

原型

- （无效）onSocket：（AsyncSocket *）袜子didWriteDataWithTag：（长）标签

参数

袜子

发件人。

标签

该标签中写入信息传递的参数。

条件

此消息发出后发送方发送成功所提供的数据。

如果一个写操作是不成功的，发送者会发送一个-onSocket：willDisconnectWithError：消息代替。

接收方应排队读或根据需要写操作或断开。

错误

AsyncSocketException

实例AsyncSocket引发此异常时，它收到一个-acceptOnPort：错误：，-acceptOnAddress：端口：错误：或-connectToHost：onPort：错误：消息，并且：

AsyncSocketErrorDomain

这NSError域包括以下AsyncSocketError代码：

您可以提供在这些代码本地化错误消息AsyncSocket.strings串在主包文件，用作键“AsyncSocketNoError，” 等默认提供英文字符串。

API更改

因为AsyncSocket 4.2的变化：

因为AsyncSocket 4.0的变化：

因为AsyncSocket 3.13的变化：

API指数

作者：达斯汀沃斯