DatagramSocket DatagramSocket DatagramSocket DatagramSocket Class

Supports network communication using a UDP datagram socket.

Syntax

Declaration

public sealed class DatagramSocketpublic sealed class DatagramSocketPublic NotInheritable 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(Windows.Networking.HostName,System.String) or BindServiceNameAsync(System.String,Windows.Networking.Connectivity.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(Windows.Networking.HostName,System.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(Windows.Networking.HostName,System.String) or BindServiceNameAsync(System.String,Windows.Networking.Connectivity.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(Windows.Networking.HostName,System.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(Windows.Networking.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(Windows.Devices.WiFiDirect.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 DatagramSocket()Public Function DatagramSocket() As

Properties

Methods

Events

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Capabilities

internetClient
privateNetworkClientServer
ID_CAP_NETWORKING [Windows Phone]

Attributes

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

Details

Assembly

Windows.Networking.Sockets.dll