DatagramSocket DatagramSocket DatagramSocket DatagramSocket Class

Supports network communication using a UDP datagram socket.

Syntax

Declaration

public sealed class DatagramSocketpublic sealed class DatagramSocketPublic NotInheritable Class DatagramSocketpublic sealed class DatagramSocket

Remarks

The DatagramSocket class supports network communication using a UDP datagram socket. The DatagramSocket object can be used for client apps that send UDP packets or for server apps that listen for incoming UDP data.

Several steps are needed to send or receive data using a DatagramSocket object. Your app first assigns the MessageReceived event to an event handler. To listen for incoming packets from a remote endpoint (a server scenario, for example), your app calls either the BindEndpointAsync(HostName, String) or BindServiceNameAsync(String, NetworkAdapter) method to bind the DatagramSocket to a local service name or UDP port. However when your app needs to communicate with a single remote endpoint (client scenario, for example), your app calls the ConnectAsync(HostName, String) method. The MessageReceived event handler must be set before any bind or connect operation, otherwise an error will occur.

The typical order of operations is as follows:

  1. Create the DatagramSocket.
  2. Use the Control property to retrieve a DatagramSocketControl object and set any advanced controls. This step is not normally needed by most apps.
  3. Assign the MessageReceived event to an event handler.
  4. To listen for incoming packets from any remote endpoint (server scenario, for example), call the BindEndpointAsync(HostName, String) or BindServiceNameAsync(String, NetworkAdapter) method to bind the DatagramSocket to a local service name or UDP port.
  5. To communicate with a single remote endpoint (client scenario, for example), call the ConnectAsync(HostName, String) method to bind the DatagramSocket to a specific remote endpoint.
  6. The MessageReceived event handler will be invoked whenever a message from the remote endpoint arrives. This class can also be used to join a multicast group and send UDP packets to the multicast group. For more information, see the JoinMulticastGroup(HostName) method.

Handling exceptions

You must write code to handle exceptions when you call asynchronous methods on the DatagramSocket 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 a convenient helper method and enumeration for handling errors when using sockets. 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 DatagramSocket with Wi-Fi Direct

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 GetDeviceSelector(WiFiDirectDeviceSelectorType) method gets the device identifier for a nearby WFD device. Once you have a reference to a nearby WFD device, you can call the 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.

Using DatagramSocket 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 DatagramSocket 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 DatagramSocket object.

Properties summary

Gets socket control data on a DatagramSocket object.

Gets socket information on the local and remote hostnames and local and remote service names for the DatagramSocket object.

Gets the output stream to write to the remote host.

Methods summary

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

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

Starts a bind operation on a DatagramSocket to a local service name and specific network interface.

Cancels pending reads and writes over a DatagramSocket object.

Closes the DatagramSocket object and aborts any pending operation on the DatagramSocket.

Starts a connect operation on a DatagramSocket to a remote network destination specified as an EndpointPair object.

Starts a connect operation on a DatagramSocket to a remote destination specified by a remote hostname and a remote service name.

Enables your app's background task to be triggered by the socket broker when traffic for this DatagramSocket arrives while the app is not active.

Enables your app's background task to be triggered by the socket broker when traffic for this DatagramSocket arrives while the system is in connected standby.

Gets a list of EndpointPair objects based on a remote hostname and remote service name that can be used to send datagrams to a remote network destination.

Gets a list of EndpointPair objects based on a remote hostname and remote service name and the sort order to be used.

Starts an operation to get an IOutputStream to a remote network destination specified by an EndpointPair object that can then be used to send network data.

Starts an operation to get an IOutputStream to a remote destination specified by a remote hostname and a remote service name that can then be used to send network data.

Joins a DatagramSocket object to a multicast group.

Transfers ownership of the DatagramSocket 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 DatagramSocket 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 DatagramSocket 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 message was received on the DatagramSocket object.

Constructors

  • DatagramSocket()
    DatagramSocket()
    DatagramSocket()
    DatagramSocket()

    Creates a new DatagramSocket object.

    public DatagramSocket()public New()Public Sub New()public DatagramSocket()

Properties

Methods

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

    Starts a bind operation on a DatagramSocket 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 the DatagramSocket to the local hostname or IP address specified in the localHostName parameter and the local service name or UDP port number address specified in the localServiceName parameter. If the localHostName parameter is null, the system will select the local IP address on which to bind. If the localServiceName parameter is an empty string, the system will select the local UDP port on which to bind.

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

    Binding is essential for receiving data from any remote endpoint on a DatagramSocket, and is commonly done after a socket is created and the MessageReceived event has been set. The BindServiceNameAsync(String, NetworkAdapter) or BindEndpointAsync(HostName, String) method is used to bind a DatagramSocket to a local service name or UDP port. The ConnectAsync(EndpointPair) methods will also result in a bind operation if the socket isn't already bound. Writing to a stream returned by one of the GetOutputStreamAsync(HostName, String) methods will also result in a bind operation.

    The BindServiceNameAsync(String, NetworkAdapter) and BindEndpointAsync(HostName, String) methods are not needed in the following cases:

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

    Starts a bind operation on a DatagramSocket 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 UDP port on which to bind the DatagramSocket object.

    Returns

    Remarks

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

    The BindServiceNameAsync(String, NetworkAdapter) method will fail if another app using UDP (another DatagramSocket, for example) has already been bound to the local UDP port specified in the localServiceName parameter.

    Binding is essential for receiving data from any remote endpoint on a DatagramSocket, and is commonly done after a socket is created and the MessageReceived event has been set. The BindServiceNameAsync(String, NetworkAdapter) or BindEndpointAsync(HostName, String) method is used to bind a DatagramSocket to a local service name or UDP port. The ConnectAsync(EndpointPair) methods will also result in a bind operation. Writing to a stream returned by one of the GetOutputStreamAsync(HostName, String) methods will also result in a bind operation if the socket isn't already bound.

    The BindServiceNameAsync(String, NetworkAdapter) and BindEndpointAsync(HostName, String) methods are not needed in the following cases:

  • BindServiceNameAsync(String, NetworkAdapter)
    BindServiceNameAsync(String, NetworkAdapter)
    BindServiceNameAsync(String, NetworkAdapter)
    BindServiceNameAsync(String, NetworkAdapter)

    Starts a bind operation on a DatagramSocket to a local service name and specific network interface.

    public IAsyncAction BindServiceNameAsync(String localServiceName, NetworkAdapter adapter)public IAsyncAction BindServiceNameAsync(String localServiceName, NetworkAdapter adapter)Public Function BindServiceNameAsync(localServiceName As String, adapter As NetworkAdapter) As IAsyncActionpublic IAsyncAction BindServiceNameAsync(String localServiceName, NetworkAdapter adapter)

    Parameters

    Returns

    Remarks

    The BindServiceNameAsync(String, NetworkAdapter) method binds to a network interface specified in the adapter parameter and the local service name or UDP port specified in the localServiceName parameter on the local computer. If the localServiceName parameter is an empty string, the system will select the local UDP port on which to bind. If the adapter parameter is null, an error will occur.

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

    The BindServiceNameAsync(String, NetworkAdapter) method will fail if another app using UDP (another DatagramSocket, for example) has already been bound to the local UDP port specified in the localServiceName parameter on the same network interface.

    Binding is essential for receiving data from any remote endpoint on a DatagramSocket, and is commonly done after a socket is created and the MessageReceived event has been set. The BindServiceNameAsync(String, NetworkAdapter) or BindEndpointAsync(HostName, String) method is used to bind a DatagramSocket to a local service name or UDP port. The ConnectAsync(EndpointPair) methods will also result in a bind operation, but can't be limited to a specific network adapter. Writing to a stream returned by one of the GetOutputStreamAsync(HostName, String) methods will also result in a bind operation if the socket isn't already bound, but can't be limited to a specific network adapter.

    The BindServiceNameAsync(String, NetworkAdapter) and BindEndpointAsync(HostName, String) methods are not needed in the following cases:

    If the BindServiceNameAsync(String, NetworkAdapter) method is used, the bind operation will limit incoming and outgoing multicast and unicast packets to the specified adapter.

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

  • CancelIOAsync()
    CancelIOAsync()
    CancelIOAsync()
    CancelIOAsync()

    Cancels pending reads and writes over a DatagramSocket 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.

    CancelIOAsync() does not guarantee that all read/write completion handlers have finished executing before it signals completion. It does, however, guarantee that all I/O operations will have reached a terminal state (either Completed or Error) by the time it signals completion. If your app needs to wait for all pending I/O operation handlers to finish executing, you must implement your own app-level sychronization logic. The Socket Activity Stream Socket sample demonstrates one way to do this for StreamSocket. The technique is similar for DatagramSocket.

    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 DatagramSocket object and aborts any pending operation on the DatagramSocket.

    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 DatagramSocket object.

    Calling the Close() method on the DatagramSocket will also unregister the MessageReceived event.

    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 Dispose method on the DatagramSocket. For apps written in C++, the Close() method will be called when using the delete keyword on the object.

  • ConnectAsync(EndpointPair)
    ConnectAsync(EndpointPair)
    ConnectAsync(EndpointPair)
    ConnectAsync(EndpointPair)

    Starts a connect operation on a DatagramSocket to a remote network destination specified as an EndpointPair object.

    public IAsyncAction ConnectAsync(EndpointPair endpointPair)public IAsyncAction ConnectAsync(EndpointPair endpointPair)Public Function ConnectAsync(endpointPair As EndpointPair) As IAsyncActionpublic IAsyncAction ConnectAsync(EndpointPair endpointPair)

    Parameters

    Returns

    Remarks

    This ConnectAsync(EndpointPair) method on a DatagramSocket is used to define the local and remote endpoint where datagrams will be sent when using the OutputStream property. This method also restricts remote IP addresses of packets that will be accepted to the remote hostname in the endpointPair parameter. Only incoming packets that match the remote endpoint in the endpointPair parameter will trigger the MessageReceived event on the DatagramSocket.

    The app can later send network data to the remote network destination by calling the WriteAsync(IBuffer) method on the OutputStream property of the DatagramSocket or by passing the OutputStream to a DataWriter object and calling methods of the DataWriter object.

    The RemoteHostName property of the EndpointPair passed in the endpointPair parameter can contain either the hostname or IP address of the remote destination. The RemoteServiceName property of the EndpointPair passed in the endpointPair parameter can contain either the service name or a UDP port of the remote destination. If the RemoteHostName property contains a hostname, then the ConnectAsync(EndpointPair) method will resolve the remote hostname to an IP address. If the RemoteServiceName property of the EndpointPair contains a service name, then the ConnectAsync(EndpointPair) method will resolve the remote service name to a UDP port number.

    The service name strings that are recognized by default are those service names listed in the %windir%\System32\drivers\etc\services file on the local computer. Any other service name value results in a name service query to domain name system (DNS) servers for DNS SRV records.

    The RemoteHostName and RemoteServiceName properties must be provided. If the RemoteHostName is null or if the RemoteServiceName is null or an empty string, an error will occur.

    If the EndpointPair object passed in the endpointPair parameter contains a null LocalHostName property, then the system will supply the local IP address that will be used. If the EndpointPair object passed in the endpointPair parameter contains an empty LocalServiceName property, then the system will supply the local UDP port that will be used.

    There are two ways of using a DatagramSocket to send UDP datagrams to a remote network destination:

    The GetOutputStreamAsync(HostName, String) methods allow an app to send UDP datagrams using a DatagramSocket object to multiple network destinations. Each time the GetOutputStreamAsync(HostName, String) method is called, the app can set different values for the remoteHostName and remoteServiceName parameters.

    To receive data from a single remote endpoint on the DatagramSocket object, an app must assign the MessageReceived event to an event handler and then call the ConnectAsync(EndpointPair) method with the endpointPair parameter set to the remote endpoint information. The MessageReceived event handler must be set before any bind or connect operation, otherwise an error will occur.

    The typical order of operations is as follows:

    The BindServiceNameAsync(String, NetworkAdapter) method can be used to specify a network adapter before calling the ConnectAsync(EndpointPair) method. The specified adapter is used for the bind operation. If after calling BindServiceNameAsync(String, NetworkAdapter) method and the endpointPair parameter passed to ConnectAsync(EndpointPair) specifies a LocalHostName, the ConnectAsync(EndpointPair) method will fail.

    The ConnectAsync(EndpointPair) method only works for unicast IP addresses. When trying to call the ConnectAsync(EndpointPair) method with a multicast IP address in the remote IP address set in the endpointPair parameter, the asynchronous operation will complete with an error. When passing the error to the GetStatus(Int32) method, the value returned will be SocketErrorStatus.

  • ConnectAsync(HostName, String)
    ConnectAsync(HostName, String)
    ConnectAsync(HostName, String)
    ConnectAsync(HostName, String)

    Starts a connect operation on a DatagramSocket to a remote destination specified by a remote hostname and a remote service name.

    public IAsyncAction ConnectAsync(HostName remoteHostName, String remoteServiceName)public IAsyncAction ConnectAsync(HostName remoteHostName, String remoteServiceName)Public Function ConnectAsync(remoteHostName As HostName, remoteServiceName As String) As IAsyncActionpublic IAsyncAction ConnectAsync(HostName remoteHostName, String remoteServiceName)

    Parameters

    • remoteHostName

      The hostname or IP address of the remote network destination.

    • remoteServiceName
      System.String
      System.String
      System.String
      System.String

      The service name or UDP port of the remote network destination.

    Returns

    Remarks

    The ConnectAsync(HostName, String) method on a DatagramSocket is used to define the remote hostname or remote IP address and the remote service name or UDP port number where datagrams will be sent when using the OutputStream property. This method also restricts the remote IP addresses of packets that will be accepted to the remoteHostName parameter. Only incoming packets that match the remoteHostName parameter will trigger the MessageReceived event on the DatagramSocket.

    The app can later send network data to the remote network destination by calling the WriteAsync(IBuffer) method on the OutputStream property of the DatagramSocket or by passing the OutputStream to a DataWriter object and calling methods of the DataWriter object.

    The remoteHostName parameter can contain either the hostname or IP address of the remote destination. The remoteServiceName parameter can contain either the service name or an UDP port of the remote destination. If the remoteHostName parameter contains a hostname, then the ConnectAsync(HostName, String) method will resolve the remote hostname to an IP address. If the remoteServiceName parameter contains a service name, then the ConnectAsync(HostName, String) method will resolve the remote service name to a UDP port number.

    The service name strings that are recognized by default by the remoteServiceName parameter are those service names listed in the %windir%\System32\drivers\etc\services file on the local computer. Any other service name value results in a name service query to domain name system (DNS) servers for DNS SRV records.

    The remoteHostName and remoteServiceName parameters must be provided. If the remoteHostName is null or the remoteServiceName is null or an empty string, an error will occur.

    There are two ways of using a DatagramSocket to send UDP datagrams to a remote network destination:

    The GetOutputStreamAsync(HostName, String) methods allow an app to send UDP datagrams using a DatagramSocket object to multiple network destinations. Each time the GetOutputStreamAsync(HostName, String) method is called, the app can set different values for the remoteHostName and remoteServiceName parameters.

    To receive data from a single endpoint on the DatagramSocket object, an app must assign the MessageReceived event to an event handler and then call the ConnectAsync(HostName, String) method with the remoteHostName and remoteServiceName parameters set to the remote endpoint information. The MessageReceived event handler must be set before any bind or connect operation, otherwise an error will occur.

    The typical order of operations is as follows:

    1. Create the DatagramSocket.
    2. Use the Control property on the DatagramSocket to retrieve a DatagramSocketControl object and set any advanced controls. This step is not normally needed by most apps.
    3. Assign the MessageReceived event to an event handler.
    4. Call the ConnectAsync(HostName, String) method to connect to the remote endpoint.
    5. Use the OutputStream property on the DatagramSocket with a DataWriter object to send messages to the remote endpoint.
    6. The MessageReceived event handler will be invoked whenever a message from the remote endpoint arrives. The GetOutputStreamAsync(HostName, String) methods also differ from the ConnectAsync(EndpointPair) method when an app uses the BindEndpointAsync(HostName, String) or BindServiceNameAsync(String, NetworkAdapter) method to bind to a local service name or UDP port. With the GetOutputStreamAsync(HostName, String) methods, the app will receive packets from any remote destination sent to the local service name or UDP port. With the ConnectAsync(EndpointPair) methods, the app will only receive packets from the remote destination passed as parameters to the ConnectAsync(EndpointPair) methods.

    The ConnectAsync(HostName, String) method only works for unicast IP addresses. When trying to call the ConnectAsync(HostName, String) method with a multicast IP address for the remoteHostName parameter, the asynchronous operation will complete with an error. When passing the error to the GetStatus(Int32) method, the value returned will be SocketErrorStatus.

  • 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 DatagramSocket 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 DatagramSocket.

  • 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 DatagramSocket 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

  • GetEndpointPairsAsync(HostName, String)
    GetEndpointPairsAsync(HostName, String)
    GetEndpointPairsAsync(HostName, String)
    GetEndpointPairsAsync(HostName, String)

    Gets a list of EndpointPair objects based on a remote hostname and remote service name that can be used to send datagrams to a remote network destination.

    public static IAsyncOperation<IVectorView<EndpointPair>> GetEndpointPairsAsync(HostName remoteHostName, String remoteServiceName)public static IAsyncOperation<IVectorView<EndpointPair>> GetEndpointPairsAsync(HostName remoteHostName, String remoteServiceName)Public Static Function GetEndpointPairsAsync(remoteHostName As HostName, remoteServiceName As String) As IAsyncOperation( Of IVectorViewEndpointPair )public static IAsyncOperation<IVectorView<EndpointPair>> GetEndpointPairsAsync(HostName remoteHostName, String remoteServiceName)

    Parameters

    • remoteHostName

      The remote hostname or IP address.

    • remoteServiceName
      System.String
      System.String
      System.String
      System.String

      The remote service name or UDP port.

    Returns

    Remarks

    The GetEndpointPairsAsync(HostName, String) method gets a list of possible EndpointPair objects that can be used by a DatagramSocket to send datagrams to a remote network destination. The returned list is sorted so that the address pairs that are best suited for communication between two peers occur earlier in the list.

    A DatagramSocket can use the list returned by the GetEndpointPairsAsync(HostName, String) method to try and bind or connect to each EndpointPair object until a connection can be made. An EndpointPair object from the list would be used with the ConnectAsync(EndpointPair) methods

  • GetEndpointPairsAsync(HostName, String, HostNameSortOptions)
    GetEndpointPairsAsync(HostName, String, HostNameSortOptions)
    GetEndpointPairsAsync(HostName, String, HostNameSortOptions)
    GetEndpointPairsAsync(HostName, String, HostNameSortOptions)

    Gets a list of EndpointPair objects based on a remote hostname and remote service name and the sort order to be used.

    public static IAsyncOperation<IVectorView<EndpointPair>> GetEndpointPairsAsync(HostName remoteHostName, String remoteServiceName, HostNameSortOptions sortOptions)public static IAsyncOperation<IVectorView<EndpointPair>> GetEndpointPairsAsync(HostName remoteHostName, String remoteServiceName, HostNameSortOptions sortOptions)Public Static Function GetEndpointPairsAsync(remoteHostName As HostName, remoteServiceName As String, sortOptions As HostNameSortOptions) As IAsyncOperation( Of IVectorViewEndpointPair )public static IAsyncOperation<IVectorView<EndpointPair>> GetEndpointPairsAsync(HostName remoteHostName, String remoteServiceName, HostNameSortOptions sortOptions)

    Parameters

    Returns

    Remarks

    The GetEndpointPairsAsync(HostName, String, HostNameSortOptions) method gets a list of possible EndpointPair objects that can be used by a DatagramSocket to connect to a remote network destination. The returned list is sorted based on the sortOptions parameter.

    A DatagramSocket can use the list returned by the GetEndpointPairsAsync(HostName, String, HostNameSortOptions) method to try and bind or connect to each EndpointPair object until a remote destination can be reached. An EndpointPair object from the list would be used with the ConnectAsync(EndpointPair) method.

  • GetOutputStreamAsync(EndpointPair)
    GetOutputStreamAsync(EndpointPair)
    GetOutputStreamAsync(EndpointPair)
    GetOutputStreamAsync(EndpointPair)

    Starts an operation to get an IOutputStream to a remote network destination specified by an EndpointPair object that can then be used to send network data.

    public IAsyncOperation<IOutputStream> GetOutputStreamAsync(EndpointPair endpointPair)public IAsyncOperation<IOutputStream> GetOutputStreamAsync(EndpointPair endpointPair)Public Function GetOutputStreamAsync(endpointPair As EndpointPair) As IAsyncOperation( Of IOutputStream )public IAsyncOperation<IOutputStream> GetOutputStreamAsync(EndpointPair endpointPair)

    Parameters

    • endpointPair

      An endpoint pair that represents the local hostname or local IP address, the local service name or local UDP port, the remote hostname or remote IP address, and the remote service name or remote UDP port.

    Returns

    Remarks

    The GetOutputStreamAsync(EndpointPair) method on a DatagramSocket is used to start an operation to get an IOutputStream to a remote network destination specified by an EndpointPair object. The IOutputStream can then be used to send data to the remote destination.

    The GetOutputStreamAsync(EndpointPair) method will return an IOutputStream when it completes successfully. Writing to that stream will send datagrams to the remote host and service name specified. The IOutputStream will always send to the remote hostname and remote service name specified in the ConnectAsync(HostName, String) method.

    The RemoteHostName property of the EndpointPair passed in the endpointPair parameter can contain either the hostname or IP address of the remote destination. The RemoteServiceName property of the EndpointPair passed in the endpointPair parameter can contain either the service name or a UDP port of the remote destination. If the RemoteHostName property contains a hostname, then the GetOutputStreamAsync(EndpointPair) method results in name resolution of the remote hostname. If the RemoteServiceName property contains a service name, then the GetOutputStreamAsync(EndpointPair) method results in resolution of the remote service name to a UDP port.

    The RemoteHostName and RemoteServiceName properties must be provided on the EndpointPair object passed in the endpointPair parameter. If the RemoteHostName is null or the RemoteServiceName is null or an empty string, an error will occur.

    If the EndpointPair object passed in the endpointPair parameter contains a null LocalHostName property, then the system will supply the local IP address that will be used. If the EndpointPair object passed in the endpointPair parameter contains an empty string for the LocalServiceName property, then the system will supply the local UDP port that will be used.

    There are two ways of using a DatagramSocket to send UDP datagrams to a remote network destination:

    The GetOutputStreamAsync(HostName, String) methods allow an app to send UDP datagrams using a DatagramSocket object to multiple network destinations. Each time the GetOutputStreamAsync(EndpointPair) method is called, the app can set different values for the RemoteHostName and RemoteServiceName members in the endpointPair parameter.

    To receive data from any remote endpoint on the DatagramSocket object, an app must assign the MessageReceived event to an event handler and then call either BindEndpointAsync(HostName, String) or BindServiceNameAsync(String, NetworkAdapter) method to bind the DatagramSocket to a local service name or UDP port before calling the GetOutputStreamAsync(EndpointPair) method. The MessageReceived event handler must be set before any bind or connect operation, otherwise an error will occur.

    The typical order of operations is as follows:

    1. Create the DatagramSocket.
    2. Use the Control property to retrieve a DatagramSocketControl object and set any advanced controls. This step is not normally needed by most apps.
    3. Assign the MessageReceived event to an event handler.
    4. Call the GetOutputStreamAsync(EndpointPair) method to get the OutputStream to send data to the remote endpoint. The GetOutputStreamAsync(EndpointPair) method will also bind the DatagramSocket to a local service name or UDP port and a local hostname or IP address using the endpointPair parameter.
    5. The MessageReceived event handler will be invoked whenever a message from the remote endpoint arrives. The GetOutputStreamAsync(HostName, String) methods also differ from the ConnectAsync(EndpointPair) methods when an app uses the BindEndpointAsync(HostName, String) or BindServiceNameAsync(String, NetworkAdapter) method to bind a local service name or UDP port. With the GetOutputStreamAsync(HostName, String) methods, the app will receive packets from any remote destination sent to the local service name or UDP port. With the ConnectAsync(EndpointPair) methods, the app will only receive packets from the remote destination passed as parameters to the ConnectAsync(EndpointPair) methods.

    The BindServiceNameAsync(String, NetworkAdapter) method can be used to specify a network adapter before calling the GetOutputStreamAsync(EndpointPair) method. The specified adapter is used for the bind operation. If after calling BindServiceNameAsync(String, NetworkAdapter) and the endpointPair parameter passed to GetOutputStreamAsync(EndpointPair) specifies a LocalHostName, the GetOutputStreamAsync(EndpointPair) method will fail.

  • GetOutputStreamAsync(HostName, String)
    GetOutputStreamAsync(HostName, String)
    GetOutputStreamAsync(HostName, String)
    GetOutputStreamAsync(HostName, String)

    Starts an operation to get an IOutputStream to a remote destination specified by a remote hostname and a remote service name that can then be used to send network data.

    public IAsyncOperation<IOutputStream> GetOutputStreamAsync(HostName remoteHostName, String remoteServiceName)public IAsyncOperation<IOutputStream> GetOutputStreamAsync(HostName remoteHostName, String remoteServiceName)Public Function GetOutputStreamAsync(remoteHostName As HostName, remoteServiceName As String) As IAsyncOperation( Of IOutputStream )public IAsyncOperation<IOutputStream> GetOutputStreamAsync(HostName remoteHostName, String remoteServiceName)

    Parameters

    • remoteHostName

      The remote hostname or remote IP address.

    • remoteServiceName
      System.String
      System.String
      System.String
      System.String

      The remote service name or remote UDP port.

    Returns

    Remarks

    The GetOutputStreamAsync(HostName, String) method on a DatagramSocket is used to start an operation to get an IOutputStream to a remote network destination specified by a remote hostname and a remote service name. The IOutputStream can then be used to send data to the remote destination.

    The GetOutputStreamAsync(HostName, String) method will return an IOutputStream when it completes successfully. Writing to that stream will send datagrams to the remote host and service name specified. The IOutputStream will always send to the remote hostname and remote service name specified in the ConnectAsync(HostName, String) method.

    The remoteHostName parameter can contain either the hostname or IP address of the remote destination. The remoteServiceName parameter can contain either the service name or a UDP port of the remote destination. If the remoteHostName parameter contains a hostname, then the GetOutputStreamAsync(HostName, String) method results in name resolution of the remote hostname. If the remoteServiceName parameter contains a service name, then the GetOutputStreamAsync(HostName, String) method results in resolution of the remote service name to a UDP port.

    The remoteHostName and remoteServiceName parameters must be provided. If the remoteHostName parameter is null or the remoteServiceName parameter is null or an empty string, an error will occur.

    There are two ways of using a DatagramSocket to send UDP datagrams to a remote network destination:

    The GetOutputStreamAsync(HostName, String) methods allow an app to send UDP datagrams using a DatagramSocket object to multiple network destinations. Each time the GetOutputStreamAsync(HostName, String) method is called, the app can set different values for the remoteHostName and remoteServiceName parameters.

    The ConnectAsync(EndpointPair) methods allow an app to send UDP datagrams using a DatagramSocket object to a single network destination.

    To receive data from any remote endpoint on the DatagramSocket object, an app must assign the MessageReceived event to an event handler and then call either BindEndpointAsync(HostName, String) or BindServiceNameAsync(String, NetworkAdapter) method to bind the DatagramSocket to a local service name or UDP port before calling the GetOutputStreamAsync(HostName, String) method. The MessageReceived event handler must be set before any bind or connect operation, otherwise an error will occur.

    The typical order of operations is as follows:

    1. Create the DatagramSocket.
    2. Use the Control property to retrieve a DatagramSocketControl object and set any advanced controls. This step is not normally needed by most apps.
    3. Assign the MessageReceived event to an event handler.
    4. Bind the DatagramSocket to a local service name or UDP port.
    5. The MessageReceived event handler will be invoked whenever a message from the remote endpoint arrives.
    6. Call the GetOutputStreamAsync(HostName, String) method to get the OutputStream to send data to the remote endpoint. You can use the information contained in the DatagramSocketMessageReceivedEventArgs from the MessageReceived event handler to establish an OutputStream with the remote endpoint that authored a specific incoming message. The GetOutputStreamAsync(HostName, String) methods also differ from the ConnectAsync(EndpointPair) method when an app uses the BindEndpointAsync(HostName, String) or BindServiceNameAsync(String, NetworkAdapter) method to bind to a local service name or UDP port. With the GetOutputStreamAsync(HostName, String) methods, the app will receive packets from any remote destination sent to the local service name or UDP port. With the ConnectAsync(EndpointPair) methods, the app will only receive packets from the remote destination passed as parameters to the ConnectAsync(EndpointPair) methods.
  • JoinMulticastGroup(HostName)
    JoinMulticastGroup(HostName)
    JoinMulticastGroup(HostName)
    JoinMulticastGroup(HostName)

    Joins a DatagramSocket object to a multicast group.

    public void JoinMulticastGroup(HostName host)public void JoinMulticastGroup(HostName host)Public Function JoinMulticastGroup(host As HostName) As voidpublic void JoinMulticastGroup(HostName host)

    Parameters

    Remarks

    To receive multicast packets on the DatagramSocket object, an app must assign the MessageReceived event to an event handler, bind to a local service name or UDP port and a local hostname or IP address using the BindEndpointAsync(HostName, String) or BindServiceNameAsync(String, NetworkAdapter) method, and then call the JoinMulticastGroup(HostName) method to join the multicast group.

    If a network adapter was specified to the BindServiceNameAsync(String, NetworkAdapter) method, only groups on networks present on the specified adapter will be joined.

    An app receiving multicast packets may also need to deal with network adapter changes. If network connectivity changes and the local computer or device is assigned a different IP address, the app needs to rejoin the multicast group.

  • TransferOwnership(String)
    TransferOwnership(String)
    TransferOwnership(String)
    TransferOwnership(String)

    Transfers ownership of the DatagramSocket 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.

    Remarks

    Your app should call this method to transfer ownership of the DatagramSocket to the socket brokering service when the app is about to be suspended, or at the end of a background task. Your app should not access the DatagramSocket object after calling this method, except when responding to notifications from the socket brokering service.

  • TransferOwnership(String, SocketActivityContext)
    TransferOwnership(String, SocketActivityContext)
    TransferOwnership(String, SocketActivityContext)
    TransferOwnership(String, SocketActivityContext)

    Transfers ownership of the DatagramSocket 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.

    Remarks

    Your app should call this method to transfer ownership of the DatagramSocket to the socket brokering service when the app is about to be suspended, or at the end of a background task. Your app should not access the DatagramSocket object after calling this method, except when responding to notifications from the socket brokering service.

  • TransferOwnership(String, SocketActivityContext, TimeSpan)
    TransferOwnership(String, SocketActivityContext, TimeSpan)
    TransferOwnership(String, SocketActivityContext, TimeSpan)
    TransferOwnership(String, SocketActivityContext, TimeSpan)

    Transfers ownership of the DatagramSocket 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, TimeSpan keepAliveTime)public void TransferOwnership(String socketId, SocketActivityContext data, TimeSpan keepAliveTime)Public Function TransferOwnership(socketId As String, data As SocketActivityContext, keepAliveTime As TimeSpan) As voidpublic void TransferOwnership(String socketId, SocketActivityContext data, TimeSpan keepAliveTime)

    Parameters

    Remarks

    Your app should call this method to transfer ownership of the DatagramSocket to the socket brokering service when the app is about to be suspended, or at the end of a background task. Your app should not access the DatagramSocket object after calling this method, except when responding to notifications from the socket brokering service.

Events

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Capabilities

ID_CAP_NETWORKING [Windows Phone]
privateNetworkClientServer
internetClient

Attributes

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

Details

Assembly

Windows.Networking.Sockets.dll