StreamSocketListener StreamSocketListener StreamSocketListener StreamSocketListener Class

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

Syntax

Declaration

public sealed class StreamSocketListenerpublic sealed class StreamSocketListenerPublic NotInheritable Class StreamSocketListenerpublic sealed class StreamSocketListener

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(Int32) 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(String, SocketProtectionLevel, NetworkAdapter) 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 summary

Creates a new StreamSocketListener object.

Properties summary

Gets socket control data on a StreamSocketListener object.

Gets socket information for the StreamSocketListener object.

Methods summary

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

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

Starts a bind operation on a StreamSocketListener to a local service name with a specified SocketProtectionLevel to set on any bound sockets.

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.

Cancels pending reads and writes over a StreamSocketListener object.

Closes the StreamSocketListener object.

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.

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.

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.

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 summary

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

Constructors

  • StreamSocketListener()
    StreamSocketListener()
    StreamSocketListener()
    StreamSocketListener()

    Creates a new StreamSocketListener object.

    public StreamSocketListener()public New()Public Sub New()public StreamSocketListener()

Properties

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, String localServiceName)public IAsyncAction BindEndpointAsync(HostName localHostName, String localServiceName)Public Function BindEndpointAsync(localHostName As HostName, localServiceName As String) As IAsyncActionpublic IAsyncAction BindEndpointAsync(HostName localHostName, String localServiceName)

    Parameters

    Returns

    Remarks

    The BindEndpointAsync(HostName, String) 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(HostName, String) 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(String localServiceName)public IAsyncAction BindServiceNameAsync(String localServiceName)Public Function BindServiceNameAsync(localServiceName As String) As IAsyncActionpublic IAsyncAction BindServiceNameAsync(String localServiceName)

    Parameters

    • localServiceName
      System.String
      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

    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.

  • 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(String localServiceName, SocketProtectionLevel protectionLevel)public IAsyncAction BindServiceNameAsync(String localServiceName, SocketProtectionLevel protectionLevel)Public Function BindServiceNameAsync(localServiceName As String, protectionLevel As SocketProtectionLevel) As IAsyncActionpublic IAsyncAction BindServiceNameAsync(String localServiceName, SocketProtectionLevel protectionLevel)

    Parameters

    Returns

    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(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 IAsyncActionpublic IAsyncAction BindServiceNameAsync(String localServiceName, SocketProtectionLevel protectionLevel, NetworkAdapter adapter)

    Parameters

    Returns

    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 IAsyncActionpublic IAsyncAction CancelIOAsync()

    Returns

    Remarks

    Call CancelIOAsync() to cancel any pending reads or writes on this socket before you call TransferOwnership(String) 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()public void Close()Public Function Close() As voidpublic void Close()

    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.

  • 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(Guid taskId)public void EnableTransferOwnership(Guid taskId)Public Function EnableTransferOwnership(taskId As Guid) As voidpublic void EnableTransferOwnership(Guid taskId)

    Parameters

    • taskId
      System.Guid
      System.Guid
      System.Guid
      System.Guid

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

  • 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(Guid taskId, SocketActivityConnectedStandbyAction connectedStandbyAction)public void EnableTransferOwnership(Guid taskId, SocketActivityConnectedStandbyAction connectedStandbyAction)Public Function EnableTransferOwnership(taskId As Guid, connectedStandbyAction As SocketActivityConnectedStandbyAction) As voidpublic void EnableTransferOwnership(Guid taskId, SocketActivityConnectedStandbyAction connectedStandbyAction)

    Parameters

  • 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(String socketId)public void TransferOwnership(String socketId)Public Function TransferOwnership(socketId As String) As voidpublic void TransferOwnership(String socketId)

    Parameters

    • socketId
      System.String
      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.

  • 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(String socketId, SocketActivityContext data)public void TransferOwnership(String socketId, SocketActivityContext data)Public Function TransferOwnership(socketId As String, data As SocketActivityContext) As voidpublic void TransferOwnership(String socketId, SocketActivityContext data)

    Parameters

    • socketId
      System.String
      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

      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.

Events

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

Attributes

Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.DualApiPartitionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ThreadingAttribute

Details

Assembly

Windows.Networking.Sockets.dll