Share via


Windows.Networking.Sockets Namespace

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.

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.

See also