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.
The Windows.Networking.Sockets namespace has these types of members:
|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. 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.|
|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 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.|
The Windows.Networking.Sockets namespace has these enumerations.
|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.|
|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.|
The Windows.Networking.Sockets namespace defines these interfaces.
|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.|
The Windows.Networking.Sockets namespace has these structures.
|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.|
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.
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.
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.
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.
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.
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.
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.
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.
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.
- 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
- Windows.Networking Namespace
- Windows.Networking.Connectivity Namespace
- Bluetooth Rfcomm Chat sample
- DatagramSocket sample
- Connecting with WebSockets sample
- ControlChannelTrigger StreamWebSocket sample
- ControlChannelTrigger TCP socket sample
- Proximity sample
- StreamSocket sample