Skip to main content
Windows.Networking.Sockets namespace

Applies to Windows and Windows Phone

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

Members

The Windows.Networking.Sockets namespace has these types of members:

Classes

The Windows.Networking.Sockets namespace has these classes.

ClassDescription
ControlChannelTrigger Enables real time notifications to be received in the background for class elements in the Windows.Networking.Sockets namespace and other networking transports. This class is not supported on Windows Phone.
DatagramSocket Supports network communication using a UDP datagram socket.
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.
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 Windows Store app.
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.

 

Enumerations

The Windows.Networking.Sockets namespace has these enumerations.

EnumerationDescription
ControlChannelTriggerResetReason The reason why a ControlChannelTrigger was reset. This enumeration is not supported on Windows Phone.
ControlChannelTriggerResourceType The resource type used by a control channel trigger. 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. This enumeration is not supported on Windows Phone.
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.

 

Interfaces

The Windows.Networking.Sockets namespace defines these interfaces.

InterfaceDescription
IControlChannelTriggerEventDetails An object instantiated by the background broker infrastructure that is used to differentiate control channel triggers. 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. 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.
IWebSocketInformation Provides socket information on an IWebSocket object.

 

Structures

The Windows.Networking.Sockets namespace has these structures.

StructureDescription
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.

 

Remarks

The Windows.Networking.Sockets namespace provides classes and interfaces for networking that use sockets and WebSockets. The primary classes include:

  • 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.
  • StreamWebSocket - A stream-based WebSocket to read and write streams for network communications.

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 also has a class for network control channel triggers to use for background networking. 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.

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 Windows Store 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.

Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8

Namespace

Windows.Networking.Sockets
Windows::Networking::Sockets [C++]

Metadata

Windows.winmd

DLL

Windows.Networking.dll;
Windows.Networking.Sockets.Pushenabledapplication.dll

Capabilities

ID_CAP_NETWORKING [Windows Phone]

See also

Other resources
Adding support for networking
Connecting to network services
Connecting to a WebSocket service
Handling exceptions in network apps
How to configure network isolation capabilities
How to set background connectivity options
How to specify device capabilities for Bluetooth
Supporting proximity and tapping
Troubleshooting and debugging network connections
Reference
PeerFinder
SetSocketMediaStreamingMode
WiFiDirectDevice
Windows.Devices.Bluetooth.Rfcomm
Windows.Devices.WiFiDirect
Windows.Networking Namespace
Windows.Networking.Connectivity Namespace
Windows.Networking.Proximity
Samples
Bluetooth Rfcomm Chat sample
DatagramSocket sample
Connecting with WebSockets sample
ControlChannelTrigger StreamWebSocket sample
ControlChannelTrigger TCP socket sample
Proximity sample
StreamSocket sample