StreamSocket 类

参考

定义

命名空间:: Windows.Networking.Sockets

重要

一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

编辑

支持在 UWP 应用中通过 TCP 或蓝牙 RFCOMM 使用流套接字进行网络通信。

public ref class StreamSocket sealed : IClosable

/// [Windows.Foundation.Metadata.Activatable(65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class StreamSocket final : IClosable

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class StreamSocket final : IClosable

[Windows.Foundation.Metadata.Activatable(65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class StreamSocket : System.IDisposable

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class StreamSocket : System.IDisposable

function StreamSocket()

Public NotInheritable Class StreamSocket
Implements IDisposable

继承: Object Platform::Object IInspectable StreamSocket

属性: ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

实现: IClosable IDisposable

Windows 要求

设备系列	Windows 10 (在 10.0.10240.0 中引入)
API contract	Windows.Foundation.UniversalApiContract (在 v1.0 中引入)
应用功能	bluetooth.rfcomm ID_CAP_NETWORKING [Windows Phone] internetClient privateNetworkClientServer

示例

使用此类的示例应用程序包括蓝牙 RFCOMM 聊天示例、DatagramSocket 示例 (Windows 10) 、套接字活动触发器流套接字示例、StreamSocket 示例 (Windows 10) 和 Wi-Fi Direct 示例。

注解

StreamSocket 类支持在 UWP 应用中通过 TCP 或蓝牙 RFCOMM 使用流套接字的网络通信。

对于客户端应用，使用 StreamSocket 的最常见操作序列如下：

创建 StreamSocket。
使用 Control 属性获取 StreamSocketControl 对象，并在调用 ConnectAsync 方法之一之前在 StreamSocketControl 对象上设置任何属性。
调用 ConnectAsync 方法之一以建立与远程终结点的连接。对于蓝牙，远程服务名称是蓝牙服务 ID。如果立即需要 TCP 的 SSL/TLS 连接或蓝牙加密级别，则可以使用某些 ConnectAsync 方法进行指定。如果在发送和接收 TCP 套接字的某些初始数据后需要 SSL/TLS 连接，则可以稍后调用 UpgradeToSslAsync 方法来升级连接以使用 SSL。
获取 OutputStream 属性以将数据写入远程主机。
获取 InputStream 属性以从远程主机读取数据。
根据需要读取和写入数据。
调用 Close 方法可断开套接字的连接，中止所有挂起的操作，并释放与 StreamSocket 对象关联的所有非托管资源。

注意

Close 方法由用 JavaScript 编写的 UWP 应用使用。对于使用 C# 和 VB.NET 中的 .NET Framework 4.5 编写的应用，Close 方法在 StreamSocket 上公开为方法。对于用 C++ 编写的应用，在对象上使用删除关键字 (keyword) 时，将调用 Close 方法。

(调用 Close 方法) 显式关闭 StreamSocket 对象可确保在套接字上不存在挂起的读取或写入操作时正常断开连接。所有挂起的读取操作将自动中止，StreamSocket 会等待任何正在进行的 I/O 完成，然后再断开连接。如果在正在进行的 I/O 完成后套接字上没有未读数据保留，则保证正常断开连接 (FIN) 。否则，会发生非正常断开连接 (RST) 。

当活动 (仍然连接) StreamSocket 对象超出范围时，可能会导致中止 (非正常) 断开连接，这可能会导致以前发送的数据在远程对等方读取数据之前被丢弃。强烈建议在超出范围之前，对 StreamSocket 对象调用 Close (JavaScript 中的 Close 方法、C# 和 VB.NET 中的方法或 C) ++ 中的 delete 运算符。

每当取消读取或写入操作时，I/O 操作都会以“错误”状态完成，并且关联的 StreamSocket 对象会立即断开连接，如果套接字上保留任何未读或未发送的数据，则会导致 (RST) 断开连接。

如果以下情况 (RST) ，将始终发生异常断开连接：例如，应用) 崩溃 (发生异常终止;或网络堆栈检测到异常连接失败， (例如 TCP 重新传输超时) 。

StreamSocket 对象还与 StreamSocketListener 对象结合使用，以侦听服务器应用或对等应用中通过 TCP 或蓝牙 RFCOMM 的传入连接。 StreamSocketListener 对象收到 TCP 或蓝牙 RFCOMM 连接请求时，ConnectionReceived 事件的 Socket 属性将返回 StreamSocket 对象。有关详细信息，请参阅 StreamSocketListener。

对代理的支持

在 UWP 应用中，当需要代理来完成连接时，StreamSocket 类支持连接到远程终结点。这种对代理的支持是自动的，对应用是透明的。 StreamSocket 可以通过对代理进行身份验证以及不需要身份验证的其他代理建立连接。仅当 Internet Explorer 或使用 Windows.Web.Http 命名空间中的 HttpClient 类的应用以前已成功使用代理进行身份验证，并且以前用于身份验证的凭据仍然有效时，才对代理进行身份验证。如果使用 Internet Explorer 以外的 Web 浏览器向代理提供身份验证凭据，则对代理进行身份验证的支持不起作用。如果在 ConnectAsync 方法上指定了本地主机地址或特定网络适配器，则不支持通过代理进行连接。

在 UWP 应用中，StreamSocket 对象上的 ConnectAsync 方法尝试在名称解析前后发现代理和当前代理配置，以帮助加快建立连接的速度。如果为终结点而不是服务名称指定了端口，则会在内部启动代理发现和名称解析。如果代理发现在名称解析之前完成，并且 ProxyConfiguration 对象上的 CanConnectDirectly 属性为 false，则将尝试代理连接。名称解析完成后，使用解析的终结点地址再次启动代理发现，以确定当前的代理配置。如果 CanConnectDirectly 在名称解析后指示应用可以直接连接到远程终结点，则将尝试直接连接到终结点的套接字连接。如果名称解析后 CanConnectDirectly为 false ，则将尝试与终结点直接建立套接字连接，并通过代理尝试并行套接字连接。要成功的第一个连接由 StreamSocket 使用，另一个连接被取消。

在某些情况下， CanConnectDirectly 返回 false，但这并不意味着你不能直接访问资源。可以将本地网络配置为支持代理和网络地址转换， (NAT) 。用于向 Web 浏览器或 HttpClient 提供代理信息的 WPAD 脚本告知 Windows 它应使用代理。当远程终结点不希望代理连接 (HTTP CONNECT 请求（例如) ）时，这可能会导致问题。应用可以在 NetworkInformation 对象上使用 GetProxyConfigurationAsync 方法，传递 uri 参数的远程终结点和端口来检索代理信息，以帮助确定何时怀疑这种情况。避免在服务器只能处理直接连接时发送代理连接请求的一种方法是使用 ConnectAsync (HostName、String、SocketProtectionLevel、NetworkAdapter) 方法，因为在选择特定网络适配器时，与代理相关的逻辑将被禁用。

在 Windows Phone 8.x 应用中，StreamSocket 不提供对代理的自动支持，因为 Windows Phone 不支持 ProxyConfiguration 类。

处理异常

在 StreamSocket 类上调用异步方法时，必须编写代码来处理异常。异常可能由参数验证错误、名称解析失败和网络错误引起。网络错误 (连接丢失、连接故障和服务器故障（例如，随时可能发生) ）的异常。这些错误将引发异常。如果应用未处理，异常可能会导致整个应用被运行时终止。

Windows.Networking.Sockets 命名空间具有简化使用套接字时处理错误的功能。 SocketError 类上的 GetStatus 方法可以将 HRESULT 从异常转换为 SocketErrorStatus 枚举值。这有助于在应用中分别处理特定网络异常。应用还可以使用参数验证错误异常中的 HRESULT 来了解有关导致异常的错误的更多详细信息。

有关可能的异常以及如何处理异常的详细信息，请参阅处理网络应用中的异常。

将 StreamSocket 与邻近感应、Wi-Fi Direct 和蓝牙配合使用

应用可以将 StreamSocket 用于近距离设备之间的网络连接。 Windows.Networking.Proximity 命名空间中的类支持使用 StreamSocket 与使用蓝牙或 Wi-Fi Direct 的附近设备的网络连接。 Windows.Networking.Proximity 命名空间中的 PeerFinder 和相关类可让你的应用在附近的设备上发现应用的另一个实例。 PeerFinder.FindAllPeersAsync 方法浏览在无线范围内运行同一应用的对等计算机。 PeerFinder.ConnectAsync 方法返回连接的 StreamSocket，你的应用可以使用该 StreamSocket 与附近的对等应用一起传输网络数据。有关详细信息，请参阅支持邻近感应和点击、 Windows.Networking.Proximity、 PeerFinder 和邻近感应示例。

你的应用还可以将 StreamSocket 用于使用 Wi-Fi Direct 的设备与 Windows.Devices.WiFiDirect 命名空间中的类之间的网络连接。 WiFiDirectDevice 类可用于定位具有支持 Wi-Fi Direct (WFD) 设备的其他设备。 WiFiDirectDevice.GetDeviceSelector 方法获取附近 WFD 设备的设备标识符。引用附近的 WFD 设备后，可以调用 WiFiDirectDevice.GetConnectionEndpointPairs 方法来获取 EndpointPair 对象。然后， StreamSocket 类上的 ConnectAsync (EndpointPair) 或 ConnectAsync (EndpointPair，SocketProtectionLevel) 方法可用于建立套接字连接。有关详细信息，请参阅 Windows.Devices.WiFiDirect 和 WiFiDirectDevice。

蓝牙使用蓝牙服务 ID 作为 StreamSocket 连接的终结点，而不是主机名或 IP 地址。若要将 StreamSocket 与蓝牙配合使用，必须在应用清单中设置 bluetooth.rfcomm 设备功能。有关详细信息，请参阅 Windows.Devices.Bluetooth.Rfcomm 命名空间、如何为蓝牙指定设备功能和蓝牙 Rfcomm 聊天示例。

在 Windows Server 2012 上使用 StreamSocket

在 Windows Server 2012 和 Windows Server 2012 R2 上，实现 Windows.Networking.Sockets 命名空间中大多数类的 Windows.Networking.dll 将无法加载，除非启用了媒体基础功能。因此，如果禁用 Media Foundation 功能，则使用 Windows.Networking.Sockets 命名空间中的 StreamSocket 和相关套接字类的应用将失败。 Windows Server 2012或Windows Server 2012 R2 安装时禁用了媒体基础功能。

可以使用服务器管理器或在命令提示符或脚本中输入以下文本，在 Windows Server 2012 或 Windows Server 2012 R2 上启用 Media Foundation 功能：

dism /online /enable-feature /featurename:ServerMediaFoundation 启用 Media Foundation 功能后，系统会提示用户重启。重启计算机后， Windows.Networking.Sockets 命名空间中套接字和 WebSocket 的类将按预期工作。

使用 StreamSocket 解析 DNS 服务记录

应用可以与属于 SRV 记录的目标 DNS 地址通信。例如，Contoso 域中的可扩展消息传递和状态协议 (XMPP) 服务对应于 _xmpp-client._tcp.contoso.com。该服务名称对应于服务器 DNS 名称，例如 xmpp-client01.contoso.com。

若要连接到该服务的服务器的 DNS 地址，请在 StreamSocket 实例上使用以下方法调用：

using Windows.Networking.Sockets;

StreamSocket socket = new StreamSocket();
socket.ConnectAsync(new HostName("contoso.com"), "xmpp-client");

该协议被推断为 StreamSocket 实例的 TCP。方法处理下划线字符。

可以将 DNS 配置为具有 SRV 层次结构。 DNS SRV 资源记录可以采用以下形式： _xmpp-client._service01._tcp.contoso.com。对于此示例，对 StreamSocket 实例使用以下方法调用：

socket.ConnectAsync(new HostName("contoso.com"), "xmpp-client._service01");

这些代码片段使用 ConnectAsync。 GetEndpointPairsAsync 方法支持类似的用法来连接到服务。

版本历史记录

Windows 版本	SDK 版本	增值
1607	14393	GetEndpointPairsAsync (HostName，String)
1607	14393	GetEndpointPairsAsync (HostName，String，HostNameSortOptions)

构造函数

StreamSocket()

创建新的 StreamSocket 对象。

属性

Control	获取 StreamSocket 对象上的套接字控件数据。
Information	获取 StreamSocket 对象上的套接字信息。
InputStream	获取要从 StreamSocket 对象上的远程目标读取的输入流。
OutputStream	获取要写入 StreamSocket 对象上的远程主机的输出流。

方法

CancelIOAsync()	取消对 StreamSocket 对象的挂起读取和写入。
Close()	关闭 StreamSocket 对象。
ConnectAsync(EndpointPair)	对 StreamSocket 对象启动异步操作，以连接到指定为 EndpointPair 对象的远程网络目标。
ConnectAsync(EndpointPair, SocketProtectionLevel)	对 StreamSocket 对象启动异步操作，以连接到指定为 EndpointPair 对象和 SocketProtectionLevel 枚举的远程网络目标。此方法不可从 JavaScript 调用。
ConnectAsync(HostName, String)	对 StreamSocket 对象启动异步操作，以连接到由远程主机名和远程服务名称指定的远程网络目标。
ConnectAsync(HostName, String, SocketProtectionLevel)	对 StreamSocket 对象启动异步操作，以连接到由远程主机名、远程服务名称和 SocketProtectionLevel 指定的远程目标。
ConnectAsync(HostName, String, SocketProtectionLevel, NetworkAdapter)	对指定本地网络适配器上的 StreamSocket 对象启动异步操作，以连接到由远程主机名、远程服务名称和 SocketProtectionLevel 指定的远程目标。
Dispose()	执行与释放或重置非托管资源关联的应用程序定义的任务。
EnableTransferOwnership(Guid)	使你的应用的后台任务在应用处于非活动状态时，此 StreamSocket 的流量到达时由套接字代理触发。
EnableTransferOwnership(Guid, SocketActivityConnectedStandbyAction)	启用或禁用当系统处于连接待机状态时，此 StreamSocket 的流量到达时，由套接字代理触发应用的后台任务的功能。
GetEndpointPairsAsync(HostName, String)	获取基于远程主机名和远程服务名称的 EndpointPair 对象的列表，这些名称可用于将 TCP 数据包发送到远程网络目标。
GetEndpointPairsAsync(HostName, String, HostNameSortOptions)	根据远程主机名、远程服务名称以及要使用的排序顺序获取 EndpointPair 对象的列表。
TransferOwnership(String)	将 StreamSocket 的所有权转让给套接字代理服务，该服务监视套接字活动，并在有任何活动时通过后台任务通知应用。
TransferOwnership(String, SocketActivityContext)	将 StreamSocket 的所有权转让给套接字代理服务，该服务监视套接字活动，并在有任何活动时通过后台任务通知应用。为套接字指定新的 SocketActivityContext 。
TransferOwnership(String, SocketActivityContext, TimeSpan)	将 StreamSocket 的所有权转让给套接字代理服务，该服务监视套接字活动，并在有任何活动时通过后台任务通知应用。指定新的 SocketActivityContext 和套接字的保持活动时间。
UpgradeToSslAsync(SocketProtectionLevel, HostName)	启动异步操作，将连接的套接字升级为在 StreamSocket 对象上使用 SSL。

适用于

通过