Stream​Socket​Listener Stream​Socket​Listener Stream​Socket​Listener Class

Definition

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

public : sealed class StreamSocketListener : IClosable, IStreamSocketListener, IStreamSocketListener2, IStreamSocketListener3public sealed class StreamSocketListener : IDisposable, IStreamSocketListener, IStreamSocketListener2, IStreamSocketListener3Public NotInheritable Class StreamSocketListener Implements IDisposable, IStreamSocketListener, IStreamSocketListener2, IStreamSocketListener3
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
bluetooth.rfcomm ID_CAP_NETWORKING [Windows Phone] privateNetworkClientServer internetClientServer

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:

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:ServerMediaFoundationAfter 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() StreamSocketListener() StreamSocketListener()

Creates a new StreamSocketListener object.

public : StreamSocketListener()public StreamSocketListener()Public Sub New()
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
ID_CAP_NETWORKING [Windows Phone]

Properties

Control Control Control

Gets socket control data on a StreamSocketListener object.

public : StreamSocketListenerControl Control { get; }public StreamSocketListenerControl Control { get; }Public ReadOnly Property Control As StreamSocketListenerControl
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
ID_CAP_NETWORKING [Windows Phone]

Remarks

The Control property gets the StreamSocketListenerControl instance associated with a StreamSocketListener object.

A StreamSocketListenerControl object is automatically created with the parent StreamSocketListener object. The StreamSocketListenerControl instance can then be used to get or set control data used by the StreamSocketListener object. These properties on the StreamSocketControl instance include the following:

Any changes to the StreamSocketListenerControl property values must be set before the StreamSocketListener is bound. So changes to the QualityOfService property must be set before the BindServiceNameAsync or BindEndpointAsync method is called on the StreamSocketListener.

See Also

Information Information Information

Gets socket information for the StreamSocketListener object.

public : StreamSocketListenerInformation Information { get; }public StreamSocketListenerInformation Information { get; }Public ReadOnly Property Information As StreamSocketListenerInformation
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
ID_CAP_NETWORKING [Windows Phone]

Remarks

The Information property gets the StreamSocketListenerInformation instance associated with a StreamSocketListener object. The Information instance can then be used to get information used by the StreamSocketListener. The only information data supported is the LocalPort property which represents the local TCP port number bound to the StreamSocketListener object.

See Also

Methods

BindEndpointAsync(HostName, String) BindEndpointAsync(HostName, String) BindEndpointAsync(HostName, String)

Starts a bind operation on a StreamSocketListener to a local hostname and a local service name.

public : IAsyncAction BindEndpointAsync(HostName localHostName, PlatForm::String localServiceName)public IAsyncAction BindEndpointAsync(HostName localHostName, String localServiceName)Public Function BindEndpointAsync(localHostName As HostName, localServiceName As String) As IAsyncAction
Parameters
localHostName
HostName HostName HostName

The local hostname or IP address on which to bind the StreamSocketListener object.

localServiceName
System.String System.String System.String

The local service name or TCP port on which to bind the StreamSocketListener object.

Returns

An asynchronous bind operation on a StreamSocketListener object.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
ID_CAP_NETWORKING [Windows Phone] privateNetworkClientServer internetClientServer

Remarks

The BindEndpointAsync method binds a StreamSocketListener object to a specific hostname or IP address specified in the localHostName parameter and the local service name or TCP port specified in the localServiceName parameter. If the localHostName parameter is null, then the system will select the local IP address to bind to the StreamSocketListener object . If the localServiceName parameter contains an empty string, then the system will select the local TCP port to bind to the StreamSocketListener object.

The BindEndpointAsync method will fail if another app using TCP (another StreamSocketListener, for example) has already been bound to the local IP address and TCP port specified in the localHostName and localServiceName parameters.

See Also

BindServiceNameAsync(String) BindServiceNameAsync(String) BindServiceNameAsync(String)

Starts a bind operation on a StreamSocketListener to a local service name.

public : IAsyncAction BindServiceNameAsync(PlatForm::String localServiceName)public IAsyncAction BindServiceNameAsync(String localServiceName)Public Function BindServiceNameAsync(localServiceName As String) As IAsyncAction
Parameters
localServiceName
System.String System.String System.String

The local service name or TCP port on which to bind the StreamSocketListener object. For Bluetooth RFCOMM, this parameter is the Bluetooth Service ID.

Returns

The asynchronous bind operation on a StreamSocketListener object.

Attributes

Remarks

The BindServiceNameAsync(String) method binds to the local IP addresses of all network interfaces on the local computer and to the local service name or TCP port specified in the localServiceName parameter. If the localServiceName parameter is an empty string, then the system will select the local TCP port on which to bind.

For Bluetooth RFCOMM, this method binds to the Bluetooth Service ID specified in the localServiceName parameter on all Bluetooth interfaces. A Bluetooth Service ID must be supplied to bind for Bluetooth.

The BindServiceNameAsync(String) method will fail if another app (another StreamSocketListener, for example) has already been bound to the local TCP port or Bluetooth Service ID specified in the localServiceName parameter.

See Also

BindServiceNameAsync(String, SocketProtectionLevel) BindServiceNameAsync(String, SocketProtectionLevel) 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.

public : IAsyncAction BindServiceNameAsync(PlatForm::String localServiceName, SocketProtectionLevel protectionLevel)public IAsyncAction BindServiceNameAsync(String localServiceName, SocketProtectionLevel protectionLevel)Public Function BindServiceNameAsync(localServiceName As String, protectionLevel As SocketProtectionLevel) As IAsyncAction
Parameters
localServiceName
System.String System.String System.String

The local service name or TCP port on which to bind the StreamSocketListener object. For Bluetooth RFCOMM, this parameter is the Bluetooth Service ID.

protectionLevel
SocketProtectionLevel SocketProtectionLevel SocketProtectionLevel

The protection level for encryption to set on any bound sockets.

Returns

The asynchronous bind operation on a StreamSocketListener object.

Attributes

Remarks

The BindServiceNameAsync(String, SocketProtectionLevel) method binds to the local IP addresses of all network interfaces on the local computer and to the local service name or TCP port specified in the localServiceName parameter. For Bluetooth RFCOMM, this method binds to the Bluetooth Service ID specified in the localServiceName parameter on all Bluetooth interfaces. This method sets the protection level for encryption on any bound sockets to the protectionLevel parameter.

If the localServiceName parameter is an empty string, then the system will select the local TCP port on which to bind. A Bluetooth Service ID must be supplied to bind for Bluetooth.

The BindServiceNameAsync(String, SocketProtectionLevel) method will fail if another app (another StreamSocketListener, for example) has already been bound to the local TCP port or Bluetooth Service ID specified in the localServiceName parameter.

The protectionLevel parameter must be set to PlainSocket for all sockets except those used over Bluetooth. When the socket is to be used over Bluetooth, the protectionLevel parameter can be set to PlainSocket, BluetoothEncryptionAllowNullAuthentication, or BluetoothEncryptionWithAuthentication. For more information, see the SocketProtectionLevel enumeration.

See Also

BindServiceNameAsync(String, SocketProtectionLevel, NetworkAdapter) BindServiceNameAsync(String, SocketProtectionLevel, NetworkAdapter) 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.

public : IAsyncAction BindServiceNameAsync(PlatForm::String localServiceName, SocketProtectionLevel protectionLevel, NetworkAdapter adapter)public IAsyncAction BindServiceNameAsync(String localServiceName, SocketProtectionLevel protectionLevel, NetworkAdapter adapter)Public Function BindServiceNameAsync(localServiceName As String, protectionLevel As SocketProtectionLevel, adapter As NetworkAdapter) As IAsyncAction
Parameters
localServiceName
System.String System.String System.String

The local service name or TCP port on which to bind the StreamSocketListener object. For Bluetooth RFCOMM, this parameter is the Bluetooth Service ID.

protectionLevel
SocketProtectionLevel SocketProtectionLevel SocketProtectionLevel

The protection level for encryption to set on any bound sockets.

adapter
NetworkAdapter NetworkAdapter NetworkAdapter

The network adapter on which to bind the StreamSocketListener object.

Returns

The asynchronous bind operation on a StreamSocketListener object.

Attributes

Remarks

The BindServiceNameAsync(String, SocketProtectionLevel, NetworkAdapter) method binds to the local service name or TCP port specified in the localServiceName parameter on the network adapter specified in the adapter parameter on the local computer. For Bluetooth RFCOMM, this method binds to the Bluetooth Service ID specified in the localServiceName parameter if the adapter parameter is null. A Bluetooth Service ID must be supplied to bind for Bluetooth. If a network adapter is specified in the adapter parameter and the localServiceName parameter contains a Bluetooth Service ID, then this method will fail.

This method sets the protection level for encryption on any bound sockets to the protectionLevel parameter.

If the localServiceName parameter is an empty string, then the system will select the local TCP port on which to bind. If the adapter parameter is null for a TCP socket bind, an error will occur.

The name resolution mechanism used by the BindServiceNameAsync(String, SocketProtectionLevel, NetworkAdapter) method is limited to the specified interface for the domain name system (DNS) namespace.

The BindServiceNameAsync(String, SocketProtectionLevel, NetworkAdapter) method will fail if another app (another StreamSocketListener, for example) has already been bound to the local TCP port specified in the localServiceName parameter on the network adapter specified in the adapter parameter. For Bluetooth, this method will fail if another app (another StreamSocketListener, for example) has already been bound to the Bluetooth Service ID specified in the localServiceName parameter.

Using the specified network adapter is on a best-effort basis. A system with adapters configured in weak-host or forwarding modes may use an adapter other than the specified adapter.

The protectionLevel parameter must be set to PlainSocket for all sockets except those used over Bluetooth. When the socket is to be used over Bluetooth, the protectionLevel parameter can be set to PlainSocket, BluetoothEncryptionAllowNullAuthentication, or BluetoothEncryptionWithAuthentication. For more information, see the SocketProtectionLevel enumeration.

See Also

CancelIOAsync() CancelIOAsync() CancelIOAsync()

Cancels pending reads and writes over a StreamSocketListener object.

public : IAsyncAction CancelIOAsync()public IAsyncAction CancelIOAsync()Public Function CancelIOAsync() As IAsyncAction
Returns

An asynchronous cancel operation on a StreamSocketListener object.

Attributes

Remarks

Call CancelIOAsync to cancel any pending reads or writes on this socket before you call TransferOwnership when your app is about to be suspended.

Note

CancelIOAsync cancels pending writes and reads in the Windows Runtime, but if there is a write buffer pending in networking drivers, it flushes the write.

Close() Close() Close()

Closes the StreamSocketListener object.

public : void Close()This member is not implemented in C#This member is not implemented in VB.Net
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
ID_CAP_NETWORKING [Windows Phone]

Remarks

The Close method aborts any pending operations and releases all unmanaged resources associated with the StreamSocketListener object.

The Close method is used by Windows app using JavaScript. For apps written using the .NET Framework 4.5 in C# and VB.NET, the Close method is exposed as the method on the StreamSocketListener object. For apps written in C++, the Close method will be called when using the delete keyword on the object.

Dispose() Dispose() Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

This member is not implemented in C++void Dispose()Sub Dispose
Attributes

EnableTransferOwnership(Guid) EnableTransferOwnership(Guid) 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.

public : void EnableTransferOwnership(PlatForm::Guid taskId)public void EnableTransferOwnership(Guid taskId)Public Function EnableTransferOwnership(taskId As Guid) As void
Parameters
taskId
System.Guid System.Guid System.Guid

The IBackgroundTaskRegistration.TaskId of the background task that will be triggered by the socket broker when traffic arrives for this StreamSocketListener.

Attributes
See Also

EnableTransferOwnership(Guid, SocketActivityConnectedStandbyAction) EnableTransferOwnership(Guid, SocketActivityConnectedStandbyAction) 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.

public : void EnableTransferOwnership(PlatForm::Guid taskId, SocketActivityConnectedStandbyAction connectedStandbyAction)public void EnableTransferOwnership(Guid taskId, SocketActivityConnectedStandbyAction connectedStandbyAction)Public Function EnableTransferOwnership(taskId As Guid, connectedStandbyAction As SocketActivityConnectedStandbyAction) As void
Parameters
taskId
System.Guid System.Guid System.Guid

The IBackgroundTaskRegistration.TaskId of the background task that will be triggered by the socket broker when traffic arrives for this StreamSocketListener.

connectedStandbyAction
SocketActivityConnectedStandbyAction SocketActivityConnectedStandbyAction SocketActivityConnectedStandbyAction

Specifies whether to enable or disable the activation of the background task when traffic arrives.

Attributes
See Also

TransferOwnership(String) TransferOwnership(String) 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.

public : void TransferOwnership(PlatForm::String socketId)public void TransferOwnership(String socketId)Public Function TransferOwnership(socketId As String) As void
Parameters
socketId
System.String System.String System.String

A string the app uses to identify the transferred socket. The string should identify this socket uniquely within the app. When activity occurs on this socket, this string will be provided to the app to identify the socket.

Attributes
See Also

TransferOwnership(String, SocketActivityContext) TransferOwnership(String, SocketActivityContext) 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.

public : void TransferOwnership(PlatForm::String socketId, SocketActivityContext data)public void TransferOwnership(String socketId, SocketActivityContext data)Public Function TransferOwnership(socketId As String, data As SocketActivityContext) As void
Parameters
socketId
System.String System.String System.String

A string the app uses to identify the transferred socket. The string should identify this socket uniquely within the app. When activity occurs on this socket, this string will be provided to the app to identify the socket.

data
SocketActivityContext SocketActivityContext SocketActivityContext

Use the SocketActivityContext to pass context information through the socket broker. When your app is notified by the broker of activity, this SocketActivityContext will be provided to your app to help establish the context in which you should handle the notification.

Attributes
See Also

Events

ConnectionReceived ConnectionReceived ConnectionReceived

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

public : event TypedEventHandler ConnectionReceivedpublic event TypedEventHandler ConnectionReceivedPublic Event ConnectionReceived
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
ID_CAP_NETWORKING [Windows Phone]

Remarks

To listen for a connection on the StreamSocketListener object, an app must assign the ConnectionReceived event to an event handler and then call either the BindEndpointAsync or BindServiceNameAsync method to bind the StreamSocketListener to a local service name or TCP port on which to listen. To listen for Bluetooth RFCOMM, the bind is to the Bluetooth Service ID.

See Also

See Also