StreamSocketListener
StreamSocketListener
StreamSocketListener
StreamSocketListener
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// You can use this class in JavaScript.
- Attributes
| 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:
- 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: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() StreamSocketListener()
Creates a new StreamSocketListener object.
public : StreamSocketListener()public StreamSocketListener()Public Sub New()// You can use this method in JavaScript.
| 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 Control
Gets socket control data on a StreamSocketListener object.
public : StreamSocketListenerControl Control { get; }public StreamSocketListenerControl Control { get; }Public ReadOnly Property Control As StreamSocketListenerControl// You can use this property in JavaScript.
- Value
- StreamSocketListenerControl StreamSocketListenerControl StreamSocketListenerControl StreamSocketListenerControl
Socket control data on a StreamSocketListener object.
| 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:
- QualityOfService - The quality of service to be set on a StreamSocket object created when a connection is received by the StreamSocketListener object.
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 Information
Gets socket information for the StreamSocketListener object.
public : StreamSocketListenerInformation Information { get; }public StreamSocketListenerInformation Information { get; }Public ReadOnly Property Information As StreamSocketListenerInformation// You can use this property in JavaScript.
- Value
- StreamSocketListenerInformation StreamSocketListenerInformation StreamSocketListenerInformation StreamSocketListenerInformation
Socket information for the StreamSocketListener object.
| 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) 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// You can use this method in JavaScript.
The local hostname or IP address on which to bind the StreamSocketListener object.
- localServiceName
- PlatForm::String String String String
The local service name or TCP port on which to bind the StreamSocketListener object.
An asynchronous bind operation on a StreamSocketListener object.
| 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.
BindServiceNameAsync(String) 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// You can use this method in JavaScript.
- localServiceName
- PlatForm::String String String 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.
The asynchronous bind operation on a StreamSocketListener object.
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
-
BindEndpointAsync(HostName, String)BindEndpointAsync(HostName, String)BindEndpointAsync(HostName, String)BindEndpointAsync(HostName, String)BindServiceNameAsync(String, SocketProtectionLevel)BindServiceNameAsync(String, SocketProtectionLevel)BindServiceNameAsync(String, SocketProtectionLevel)BindServiceNameAsync(String, SocketProtectionLevel)
BindServiceNameAsync(String, SocketProtectionLevel) 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// You can use this method in JavaScript.
- localServiceName
- PlatForm::String String String 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 SocketProtectionLevel
The protection level for encryption to set on any bound sockets.
The asynchronous bind operation on a StreamSocketListener object.
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.
BindServiceNameAsync(String, SocketProtectionLevel, NetworkAdapter) 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// You can use this method in JavaScript.
- localServiceName
- PlatForm::String String String 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 SocketProtectionLevel
The protection level for encryption to set on any bound sockets.
The network adapter on which to bind the StreamSocketListener object.
The asynchronous bind operation on a StreamSocketListener object.
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.
CancelIOAsync() CancelIOAsync() CancelIOAsync() CancelIOAsync()
Cancels pending reads and writes over a StreamSocketListener object.
public : IAsyncAction CancelIOAsync()public IAsyncAction CancelIOAsync()Public Function CancelIOAsync() As IAsyncAction// You can use this method in JavaScript.
An asynchronous cancel operation on a StreamSocketListener object.
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() Close()
Closes the StreamSocketListener object.
public : void Close()This member is not implemented in C#This member is not implemented in VB.Net// You can use this method in JavaScript.
| 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() Dispose()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
This member is not implemented in C++void Dispose()Sub Disposevoid Dispose()
EnableTransferOwnership(Guid) 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// You can use this method in JavaScript.
- taskId
- PlatForm::Guid Guid Guid Guid
The IBackgroundTaskRegistration.TaskId of the background task that will be triggered by the socket broker when traffic arrives for this StreamSocketListener.
- See Also
EnableTransferOwnership(Guid, SocketActivityConnectedStandbyAction) 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// You can use this method in JavaScript.
- taskId
- PlatForm::Guid Guid Guid 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 SocketActivityConnectedStandbyAction
Specifies whether to enable or disable the activation of the background task when traffic arrives.
- See Also
TransferOwnership(String) 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// You can use this method in JavaScript.
- socketId
- PlatForm::String String String 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.
- See Also
TransferOwnership(String, SocketActivityContext) 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// You can use this method in JavaScript.
- socketId
- PlatForm::String String String 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.
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.
- See Also
Events
ConnectionReceived ConnectionReceived ConnectionReceived ConnectionReceived
An event that indicates that a connection was received on the StreamSocketListener object.
public : event TypedEventHandler ConnectionReceived<StreamSocketListener, StreamSocketListenerConnectionReceivedEventArgs>public event TypedEventHandler ConnectionReceived<StreamSocketListener, StreamSocketListenerConnectionReceivedEventArgs>Public Event ConnectionReceived<StreamSocketListener, StreamSocketListenerConnectionReceivedEventArgs>// You can use this event in JavaScript.
| 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
- Connecting with sockets
- Connecting with sockets
- Handling exceptions in network apps
- How to connect with a stream socket
- How to connect with a stream socket
- How to specify device capabilities for Bluetooth
- How to use advanced socket controls
- How to use advanced socket controls
- Troubleshoot and debug network connections
- StreamSocketListenerControl StreamSocketListenerControl StreamSocketListenerControl StreamSocketListenerControl
- StreamSocketListenerInformation StreamSocketListenerInformation StreamSocketListenerInformation StreamSocketListenerInformation
- Bluetooth Rfcomm Chat sample
- ControlChannelTrigger StreamSocket sample
- Proximity sample
- StreamSocket sample
- StreamSocket sample (Windows 10)