StreamSocketListener Class

Reference

Definition

Namespace:: Windows.Networking.Sockets

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

Supports listening for an incoming network connection using a TCP stream socket or Bluetooth RFCOMM.

public ref class StreamSocketListener 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 StreamSocketListener 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 StreamSocketListener 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 StreamSocketListener : 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 StreamSocketListener : System.IDisposable

function StreamSocketListener()

Public NotInheritable Class StreamSocketListener
Implements IDisposable

Inheritance: Object Platform::Object IInspectable StreamSocketListener

Attributes: ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implements: IClosable IDisposable

Windows requirements

Device family	Windows 10 (introduced in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v1.0)
App capabilities	bluetooth.rfcomm ID_CAP_NETWORKING [Windows Phone] internetClientServer privateNetworkClientServer

Remarks

The StreamSocketListener class supports listening for an incoming network connection using a stream socket and accepting the connection.

The typical order of operations is as follows:

Create the StreamSocketListener.
Use the Control property to retrieve a StreamSocketListenerControl object and set the socket quality of service required.
Assign the ConnectionReceived event to an event handler.
Call the BindServiceNameAsync or BindEndpointAsync method to bind to a local TCP port number or service name. For Bluetooth RFCOMM, the local service name parameter is the Bluetooth Service ID.
When a connection is received, use the StreamSocketListenerConnectionReceivedEventArgs object to retrieve the Socket property with the StreamSocket object created.
Use the StreamSocket object to send and receive data.
Call the Close method to stop listening for and accepting incoming network connections and release all unmanaged resources associated with the StreamSocketListener object. Any StreamSocket objects created when a connection is received are unaffected and can continue to be used as needed.

The SocketProtectionLevel enumeration allows a server to control protocol negotiation with clients when using the StreamSocketListener object to listen and bind to sockets over Bluetooth. When the StreamSocketListener object is used over Bluetooth, the supported SocketProtectionLevel values are PlainSocket, BluetoothEncryptionAllowNullAuthentication, or BluetoothEncryptionWithAuthentication. When the StreamSocketListener object is used to listen and bind to sockets not using Bluetooth, the only supported SocketProtectionLevel value is PlainSocket.

To use StreamSocketListener with Bluetooth, the bluetooth.rfcomm device capability must be set in the app manifest. For more information, see How to specify device capabilities for Bluetooth.

Handling exceptions

You must write code to handle exceptions when you call asynchronous methods on the StreamSocketListener class. 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 features that simplify handling errors when using sockets. The GetStatus method on the SocketError class can convert the HRESULT from an exception to a SocketErrorStatus enumeration value. 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 StreamSocketListener with Bluetooth

Your app can use StreamSocketListener to listen for network connections over Bluetooth RFCOMM. Network connections over Bluetooth use a Bluetooth Service ID as the endpoint for connections, not an IP port or a service name. To listen for Bluetooth, your app would call one of the BindServiceNameAsync methods on StreamSocketListener with the localServiceName parameter set to a Bluetooth Service ID.

To use StreamSocketListener and 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 StreamSocketListener 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 use StreamSocketListener and related socket 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.

Constructors

StreamSocketListener()

Creates a new StreamSocketListener object.

Properties

Control	Gets socket control data on a StreamSocketListener object.
Information	Gets socket information for the StreamSocketListener object.

Methods

BindEndpointAsync(HostName, String)	Starts a bind operation on a StreamSocketListener to a local hostname and a local service name.
BindServiceNameAsync(String, SocketProtectionLevel, NetworkAdapter)	Starts a socket bind operation on a StreamSocketListener to a local service name on a specified network adapter with a specified SocketProtectionLevel to set on any bound sockets.
BindServiceNameAsync(String, SocketProtectionLevel)	Starts a bind operation on a StreamSocketListener to a local service name with a specified SocketProtectionLevel to set on any bound sockets.
BindServiceNameAsync(String)	Starts a bind operation on a StreamSocketListener to a local service name.
CancelIOAsync()	Cancels pending reads and writes over a StreamSocketListener object.
Close()	Closes the StreamSocketListener object.
Dispose()	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
EnableTransferOwnership(Guid, SocketActivityConnectedStandbyAction)	Enables your app's background task to be triggered by the socket broker when traffic for this StreamSocketListener arrives while the system is in connected standby.
EnableTransferOwnership(Guid)	Enables your app's background task to be triggered by the socket broker when traffic for this StreamSocketListener arrives while the app is not active.
TransferOwnership(String, SocketActivityContext)	Transfers ownership of the StreamSocketListener to the socket brokering service, which monitors socket activity and notifies the app through a background task if there is any activity.
TransferOwnership(String)	Transfers ownership of the StreamSocketListener to the socket brokering service, which monitors socket activity and notifies the app through a background task if there is any activity.

Events

ConnectionReceived

An event that indicates that a connection was received on the StreamSocketListener object.

Applies to

Share via