DatagramSocket class

Applies to Windows and Windows Phone

Supports network communication using a UDP datagram socket.

Syntax


public ref class DatagramSocket sealed : IClosable

Attributes

[DualApiPartition()]
[MarshalingBehavior(Agile)]
[Threading(Both)]
[Version(0x06020000)]

Members

The DatagramSocket class has these types of members:

Constructors

The DatagramSocket class has these constructors.

ConstructorDescription
DatagramSocket Creates a new DatagramSocket object.

 

Events

The DatagramSocket class has these events.

EventDescription
MessageReceived An event that indicates that a message was received on the DatagramSocket object.

 

Methods

The DatagramSocket class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.

MethodDescription
BindEndpointAsync Starts a bind operation on a DatagramSocket to a local hostname and a local service name.
BindServiceNameAsync(String) Starts a bind operation on a DatagramSocket to a local service name.
BindServiceNameAsync(String, NetworkAdapter) Starts a bind operation on a DatagramSocket to a local service name and specific network interface.
Close [C++, JavaScript]Closes the DatagramSocket object and aborts any pending operation on the DatagramSocket.
ConnectAsync(EndpointPair) Starts a connect operation on a DatagramSocket to a remote network destination specified as an EndpointPair object.
ConnectAsync(HostName, String) Starts a connect operation on a DatagramSocket to a remote destination specified by a remote hostname and a remote service name.
Dispose [C#, VB]Performs tasks associated with freeing, releasing, or resetting unmanaged resources on the DatagramSocket object and aborts any pending operation on the DatagramSocket.
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.
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.
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.
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.
JoinMulticastGroup Joins a DatagramSocket object to a multicast group.

 

Properties

The DatagramSocket class has these properties.

PropertyAccess typeDescription

Control

Read-onlyGets socket control data on a DatagramSocket object.

Information

Read-onlyGets socket information on the local and remote hostnames and local and remote service names for the DatagramSocket object.

OutputStream

Read-onlyGets the output stream to write to the remote host.

 

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

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 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:ServerMediaFoundation

After 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.

Requirements

Minimum supported client

Windows 8 [Windows Store apps, desktop apps]

Minimum supported server

Windows Server 2012 [Windows Store apps, desktop apps]

Minimum supported phone

Windows Phone 8

Namespace

Windows.Networking.Sockets
Windows::Networking::Sockets [C++]

Metadata

Windows.winmd

DLL

Windows.Networking.dll

Capabilities

internetClient
privateNetworkClientServer
ID_CAP_NETWORKING [Windows Phone]

See also

Other resources
Connecting with sockets (HTML)
Connecting with sockets (XAML)
Handling exceptions in network apps
How to connect with a datagram socket (HTML)
How to connect with a datagram socket (XAML)
How to use advanced socket controls (HTML)
How to use advanced socket controls (XAML)
Troubleshoot and debug network connections
Reference
DatagramSocketControl
DatagramSocketInformation
DatagramSocketMessageReceivedEventArgs
IClosable
Object
SetSocketMediaStreamingMode
Samples
DatagramSocket sample

 

 

Show:
© 2014 Microsoft