Windows.Networking.Sockets Namespace

Reference

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

Provides sockets and WebSockets classes to use for network communications and classes for real-time network notifications received in the background for UWP apps.

Classes

ControlChannelTrigger	Enables real time notifications to be received in the background for objects that establish a TCP connection and wish to be notified of incoming traffic. Call BackgroundExecutionManager.RequestAccessAsync before using ControlChannelTrigger. Note This class is not supported on Windows Phone.
DatagramSocket	Supports network communication using a UDP datagram socket. For a code example, see Sockets.
DatagramSocketControl	Provides socket control data on a DatagramSocket object.
DatagramSocketInformation	Provides socket information on a DatagramSocket object.
DatagramSocketMessageReceivedEventArgs	Provides data for a MessageReceived event on a DatagramSocket.
MessageWebSocket	Supports network communication that allows reading and writing whole messages using a WebSocket.
MessageWebSocketControl	Provides socket control data on a MessageWebSocket.
MessageWebSocketInformation	Provides socket information on a MessageWebSocket.
MessageWebSocketMessageReceivedEventArgs	Provides data for a message received event on a MessageWebSocket.
ServerMessageWebSocket	Supports network communication that allows reading and writing whole messages using a WebSocket object owned by a web server. You can't register for an arbitrary WebSocket connection; instead, an instance of ServerMessageWebSocket is created by system code such as the Windows Device Portal (WDP).
ServerMessageWebSocketControl	Provides socket control data on a ServerMessageWebSocket.
ServerMessageWebSocketInformation	Provides socket information on a ServerMessageWebSocket.
ServerStreamWebSocket	Supports network communication that allows reading and writing streams using a WebSocket object owned by a web server. You can't register for an arbitrary WebSocket connection; instead, an instance of ServerStreamWebSocket is created by system code such as the Windows Device Portal (WDP).
ServerStreamWebSocketInformation	Provides socket information on a ServerStreamWebSocket object.
SocketActivityContext	The context associated with a socket while transferring ownership of the socket between an app and the socket brokering service.
SocketActivityInformation	Provides information on the transferred socket from the Socket Broker.
SocketActivityTriggerDetails	A object instantiated by the background broker infrastructure and used by an app to retrieve details when a SocketActivityTrigger occurs.
SocketError	Provides socket error status for operations on a DatagramSocket, StreamSocket, or StreamSocketListener.
StreamSocket	Supports network communication using a stream socket over TCP or Bluetooth RFCOMM in UWP apps.
StreamSocketControl	Provides socket control data on a StreamSocket object.
StreamSocketInformation	Provides socket information on a StreamSocket object.
StreamSocketListener	Supports listening for an incoming network connection using a TCP stream socket or Bluetooth RFCOMM.
StreamSocketListenerConnectionReceivedEventArgs	Provides data for a ConnectionReceived event on a StreamSocketListener object.
StreamSocketListenerControl	Provides socket control data on a StreamSocketListener object.
StreamSocketListenerInformation	Provides socket information on a StreamSocketListener object.
StreamWebSocket	Supports network communication that allows reading and writing streams using a WebSocket.
StreamWebSocketControl	Provides socket control data on a StreamWebSocket object.
StreamWebSocketInformation	Provides socket information on a StreamWebSocket object.
WebSocketClosedEventArgs	Provides data for a closed event on a MessageWebSocket, StreamWebSocket, or IWebSocket object.
WebSocketError	Provides socket error status on a MessageWebSocket or StreamWebSocket object.
WebSocketKeepAlive	Provides the ability to send a WebSocket protocol keep-alive on a connected WebSocket.
WebSocketServerCustomValidationRequestedEventArgs	Provides data for a ServerCustomValidationRequested event on a WebSocket. This event occurs when a new, secure connection to a WebSocket is being made, and gives your code the opportunity to perform custom validation of the server certificates before the connection has been established.

Structs

BandwidthStatistics	Represents bandwidth information for network data transfer using a StreamSocket, StreamWebSocket, or MessageWebSocket object.
RoundTripTimeStatistics	Represents round trip time information for a StreamSocket object.

Interfaces

IControlChannelTriggerEventDetails	An object instantiated by the background broker infrastructure that is used to differentiate control channel triggers. Note This interface is not supported on Windows Phone.
IControlChannelTriggerResetEventDetails	An object instantiated by the background broker infrastructure for a ControlChannelReset event to indicate that a ControlChannelTrigger was reset. Note This interface is not supported on Windows Phone.
IWebSocket	Provides access to network communication that allows reading and writing using a WebSocket.
IWebSocketControl	Provides socket control data on an IWebSocket object.
IWebSocketControl2	Provides socket control data on an IWebSocket object. This interface extends the IWebSocketControl interface with an additional property.
IWebSocketInformation	Provides socket information on an IWebSocket object.
IWebSocketInformation2	Provides socket information on an IWebSocket object. This interface extends IWebSocketInformation with additional properties.

Enums

ControlChannelTriggerResetReason	The reason why a ControlChannelTrigger was reset. Note This enumeration is not supported on Windows Phone.
ControlChannelTriggerResourceType	The resource type used by a control channel trigger. Note This enumeration is not supported on Windows Phone.
ControlChannelTriggerStatus	Specifies if the system was able to complete configuration of a ControlChannelTrigger object for use by class elements in the Windows.Networking.Sockets and related namespaces. Note This enumeration is not supported on Windows Phone.
MessageWebSocketReceiveMode	Describes the kind of message that the client will accept.
SocketActivityConnectedStandbyAction	Indicates whether an app that uses the socket brokering service can receive packets when the system goes to connected stand by.
SocketActivityKind	Describes the kind of socket object being transferred to or from the socket broker.
SocketActivityTriggerReason	The reason why a SocketActivityTrigger occurred.
SocketErrorStatus	Specifies status values for a socket operation.
SocketMessageType	Specifies the type of a message for a MessageWebSocket object.
SocketProtectionLevel	Specifies the level of encryption to use on a StreamSocket object.
SocketQualityOfService	Specifies the quality of service for a DatagramSocket or StreamSocket object.
SocketSslErrorSeverity	The category of error that occurs on an SSL connection.

Remarks

The Windows.Networking.Sockets namespace provides classes and interfaces for networking that use sockets and WebSockets. Here are the primary classes.

DatagramSocket. A UDP datagram socket to use for network communication.
StreamSocket. A stream socket to use for incoming or outgoing network communication over TCP or over Bluetooth connections that use RFCOMM.
StreamSocketListener. A stream socket listener to listen for incoming TCP network connections or incoming Bluetooth connections that use RFCOMM.
MessageWebSocket. A message-based WebSocket to read and write whole messages for network communication. See WebSockets.
StreamWebSocket. A stream-based WebSocket to read and write streams for network communications. See WebSockets.

These primary classes also have a number of related information and control classes in the Windows.Networking.Sockets namespace.

Handling exceptions

You must write code to handle exceptions when you call asynchronous methods in the Windows.Networking.Sockets namespace. Exceptions can result from parameter validation errors, name resolutions failures, and network errors. Exceptions from network errors (loss of connectivity, connection failures, and server failures, for example) can happen at any time. These errors result in exceptions being thrown. If not handled by your app, an exception can cause your entire app to be terminated by the runtime.

The Windows.Networking.Sockets namespace has convenient helper methods and enumerations for handling errors when using sockets and WebSockets. This can be useful for handling specific network exceptions differently in your app. An app can also use the HRESULT from the exception on parameter validation errors to learn more detailed information on the error that caused the exception.

For more information on possible exceptions and how to handle exceptions, see Handling exceptions in network apps.

Using StreamSocket with Proximity, Wi-Fi Direct, and Bluetooth

Your app can use a StreamSocket for network connections between devices that are within close range. Classes in the Windows.Networking.Proximity namespace support network connections with a StreamSocket to nearby devices that use Bluetooth or Wi-Fi Direct. The PeerFinder and related classes in the Windows.Networking.Proximity namespace let your app discover another instance of your app on a nearby device. The PeerFinder.FindAllPeersAsync method browses for peer computers that are running the same app within wireless range. The PeerFinder.ConnectAsync method returns a connected StreamSocket that your app can use to transfer network data with the nearby peer app. For more information, see Supporting proximity and tapping, Windows.Networking.Proximity, PeerFinder, and the Proximity sample.

Your app can also use a StreamSocket for network connections between devices that use Wi-Fi Direct with classes in the Windows.Devices.WiFiDirect namespace. The WiFiDirectDevice class can be used to locate other devices that have a Wi-Fi Direct (WFD) capable device. The WiFiDirectDevice.GetDeviceSelector method gets the device identifier for a nearby WFD device. Once you have a reference to a nearby WFD device, you can call the WiFiDirectDevice.GetConnectionEndpointPairs method to get an EndpointPair object. The ConnectAsync(EndpointPair) or ConnectAsync(EndpointPair, SocketProtectionLevel) method on the StreamSocket class can then be used to establish a socket connection. For more information, see Windows.Devices.WiFiDirect and WiFiDirectDevice.

Bluetooth uses Bluetooth Service IDs as endpoints for StreamSocket connections, not hostnames or IP addresses. To use a StreamSocket with Bluetooth, the bluetooth.rfcomm device capability must be set in the app manifest. For more information, see the Windows.Devices.Bluetooth.Rfcomm namespace, How to specify device capabilities for Bluetooth, and the Bluetooth Rfcomm Chat sample.

Using DatagramSocket with Wi-Fi Direct

Your app can use a DatagramSocket for network data transfers between devices that use Wi-Fi Direct using classes in the Windows.Devices.WiFiDirect namespace. The WiFiDirectDevice class can be used to locate other devices that have a Wi-Fi Direct (WFD) capable device. The WiFiDirectDevice.GetDeviceSelector method gets the device identifier for a nearby WFD device. Once you have a reference to a nearby WFD device, you can call the WiFiDirectDevice.GetConnectionEndpointPairs method to get an EndpointPair object. Methods on the DatagramSocket class can be used to send and receive data to the EndpointPair object. For more information, see Windows.Devices.WiFiDirect and WiFiDirectDevice.

Using network triggers

The Windows.Networking.Sockets namespace offers two kinds of triggers that your app can use for background networking: ControlChannelTrigger and SocketActivityTrigger.

Control channel triggers

The ControlChannelTrigger lets your app receive network data packets and network keepalives when the app is in the background. This lets your app provide real-time status and network notifications for StreamSocket in the Windows.Networking.Sockets namespace and other network classes in related namespaces.

Network triggers are used by long-running network apps (for example, an email app) to minimize network and system resource usage. Network triggers let an app drop to a low-power mode for periods of time, keeping network connections intact but in a low-power state. You can set a keepalive interval to let the system know when the app should wake up. You can also set a trigger to be notified when a packet is received for the app. These notification features can help extend battery life when using long-running network apps on mobile devices.

For more information, see the ControlChannelTrigger class and How to set background connectivity options.

Socket activity triggers

The SocketActivityTrigger lets your app receive network data packets when it is not active (even if it is suspended or terminated), and even when it is not currently loaded in memory. It is provided particularly for apps that provide network services, where the app would register as a service provider through DNS-SD, and then become inactive. A SocketActivityTrigger would notify the app when a client connected to the service, so that the service could activate and provide requested services. SocketActivityTrigger can be used in other circumstances, too. Use it whenever you want to be able to activate your app in response to received network traffic.

If your app uses socket activity triggers, you must specify the pushNotifications capability in the app manifest.

Choosing a network trigger

There are some scenarios where either kind of trigger would be suitable. When you are choosing which kind of trigger to use in your app, consider the following advice.

If you are using IXMLHTTPRequest2, System.Net.Http.HttpClient or System.Net.Http.HttpClientHandler, you must use ControlChannelTrigger.
If you are using push-enabled StreamSockets, prefer SocketActivityTrigger. It allows the system to free up memory and reduce power requirements when the connection is not being actively used.
If you want to minimize the memory footprint of your app when it is not actively servicing network requests, prefer SocketActivityTrigger.
If you want your app to be able to receive data while the system is in Connected Standby mode, use SocketActivityTrigger.

Using sockets and WebSockets on Windows Server 2012

On Windows Server 2012 and Windows Server 2012 R2, the Windows.Networking.dll that implements most of the classes in the Windows.Networking.Sockets namespace will fail to load unless the Media Foundation feature is enabled. As a result, apps that uses sockets or WebSockets classes in the Windows.Networking.Sockets namespace will fail if the Media Foundation feature is disabled. Windows Server 2012 or Windows Server 2012 R2 installs with the Media Foundation feature disabled.

The Media Foundation feature can be enabled on Windows Server 2012 or Windows Server 2012 R2 using Server Manager or by entering the following text in a command prompt or a script:

dism /online /enable-feature /featurename:ServerMediaFoundation After the Media Foundation feature is enabled, the user is prompted to restart. Once the computer is restarted, classes for sockets and WebSockets in the Windows.Networking.Sockets namespace will work as expected.

Using sockets and WebSockets with network isolation

Network isolation in Windows 8 lets you fully control the security profile of a UWP app.

Network isolation lets you define the network access needed for each app by choosing the appropriate capabilities. An app without the appropriate capabilities set is prevented from using specific network types (Internet or Home/Work Network) and specific network requests (outbound client-initiated requests, or both inbound unsolicited requests and outbound client-initiated requests). The ability to enforce network isolation ensures that even if an app becomes compromised, the app can only use features (network types and network requests, for example) that the app was granted as capabilities. This significantly reduces the possible impact on other apps and on the operating system.

Windows 8 actively enforces network isolation. A call to a method or any access to a property in the Windows.Networking.Sockets namespace (or related namespaces that require network access) may fail if the appropriate network capability has not been enabled.

The network capabilities for an app are configured in the app manifest when the app is built. Network capabilities are usually added using Visual Studio when you develop your app. They may also be set manually in the app manifest file using a text editor.

For more detailed information on network isolation, see How to configure network isolation capabilities.

Jaa