Class UdpClient

Namespace

System.Net.Sockets

Assembly

System.Net.Sockets.UdpClient.dll

Provides User Datagram Protocol (UDP) network services. Can be used for both client and server roles.

public class UdpClient : IDisposable

Inheritance

object

UdpClient

Implements

IDisposable

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Extension Methods

LogDispatcher.GetCurrentClassLogger(object)

LogDispatcher.GetCurrentClassLogger(object)

LogDispatcher.GetCurrentClassLogger(object)

LogDispatcher.GetCurrentClassLogger(object)

LogDispatcher.GetCurrentClassLogger(object)

LogDispatcher.GetCurrentClassLogger(object)

LogDispatcher.GetCurrentClassLogger(object)

LogDispatcher.GetCurrentClassLogger(object)

LogDispatcher.GetCurrentClassLogger(object)

LogDispatcher.GetCurrentClassLogger(object)

Remarks

For the Receive methods if the buffer is smaller than the packet to receive it will be truncated to the buffer size without warning. Indeed "lwIP", the TCP/IP stack used commonly by RTOS, doesn't support the MSG_TRUNC socket option in calls to recvfrom to return the real length of the datagram when it is longer than the passed buffer opposite to common Un*x implementations.

UdpClient(string, int) and

Connect

methods establish a default remote host. Once established, you do not have to specify a remote host in each call to the

Send

methods. Additionally, once a remote host is established the datagram received from other hosts will be discarded.

Constructors

UdpClient()

Create a new UdpClient that is not bind to any local port at this time. Requires a call to connect to be bind locally on some udp port.

public UdpClient()

Exceptions

SocketException

Error on the underlying socket.

UdpClient(int)

Create a new UdpClient and bind it to the local port number provided on all IP addresses (Any)

public UdpClient(int port)

Parameters

port int

The local port number from which you intend to communicate.

Exceptions

ArgumentOutOfRangeException

The port parameter is not between 0 and 65535.

SocketException

Error on the underlying socket.

UdpClient(IPEndPoint)

Create a new UdpClient and bind it to the specified local endpoint.

public UdpClient(IPEndPoint localEP)

Parameters

localEP IPEndPoint

An IPEndPoint that represents the local endpoint to which bind the UDP connection.

Exceptions

ArgumentNullException

locelEP is null.

ArgumentException

localEP isn't an IPv4 Address

SocketException

Error on the underlying socket.

UdpClient(string, int)

Initializes a new instance of the UdpClient class and establishes a default remote host.

public UdpClient(string hostname, int port)

Parameters

hostname string

The name of the remote DNS host to which you intend to connect.

port int

The remote port number to which you intend to connect.

Remarks

This constructor initializes a new UdpClient and establishes a remote host using the hostname and port parameters.

Exceptions

ArgumentNullException

hostname is null

Properties

Active

Gets or sets a value indicating whether a default remote host has been established.

protected bool Active { get; }

Property Value

bool

Available

Amount of data received from the network that is available to read.

public int Available { get; }

Property Value

int

Exceptions

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

Client

Get underlying Socket

public Socket Client { get; }

Property Value

Socket

DontFragment

Allows fragmentation of IP datagram send through this UdpClient. This controls the IP DF flag.

public bool DontFragment { get; set; }

Property Value

bool

Exceptions

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

EnableBroadcast

Specify if the UdpClient can send broadcast packet.

public bool EnableBroadcast { get; set; }

Property Value

bool

Exceptions

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

ExclusiveAddressUse

Specify if the UdpClient allows only one client per port.

public bool ExclusiveAddressUse { get; set; }

Property Value

bool

Exceptions

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

MulticastLoopback

Specify if multicast packets delivered to the sending application.

public bool MulticastLoopback { get; set; }

Property Value

bool

Exceptions

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

Ttl

Time To Live (TTL) value of the IP packets sent through the UdpClient

public short Ttl { get; set; }

Property Value

short

Exceptions

ArgumentOutOfRangeException

TTl must be a value between 0 and 255

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

Methods

Close()

Close the connection.

public void Close()

Connect(IPAddress, int)

Establishes a default remote host using the specified IP address and port number.

public void Connect(IPAddress addr, int port)

Parameters

addr IPAddress

The IPAddress of the remote host to which you intend to send data.

port int

The port number to which you intend send data.

Exceptions

ArgumentOutOfRangeException

port is not between 0 and 65535

ArgumentNullException

addr is null

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

Connect(IPEndPoint)

Establishes a default remote host using the specified IP address and port number.

public void Connect(IPEndPoint endPoint)

Parameters

endPoint IPEndPoint

An IPEndPoint that specifies the network endpoint to which you intend to send data.

Exceptions

ArgumentNullException

endPoint is null

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

Connect(string, int)

Establishes a default remote host using the specified IP address and port number.

public void Connect(string hostname, int port)

Parameters

hostname string

port int

Remarks

The Connect method establishes a default remote host using the values specified in the port and hostname parameters. Once established, you do not have to specify a remote host in each call to the Send(byte[]) method.

Exceptions

ArgumentOutOfRangeException

port is not between 0 and 65535

ArgumentNullException

hostname is null

ArgumentException

hostname is not resolvable to an IPv4 address

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

DropMulticastGroup(IPAddress)

Leaves a multicast group address

public void DropMulticastGroup(IPAddress multicastAddr)

Parameters

multicastAddr IPAddress

IPAddress of the multicast group to leave.

Exceptions

ArgumentNullException

multicastAddr is null.

ArgumentException

multicastAddr isn't an IPv4 address.

SocketException

Error on the underlying socket.

JoinMulticastGroup(IPAddress)

Adds the UdpClient to a multicast group.

public void JoinMulticastGroup(IPAddress multicastAddr)

Parameters

multicastAddr IPAddress

IPAddress of the multicast group to join.

Exceptions

ArgumentNullException

multicastAddr is null.

ArgumentException

multicastAddr isn't an IPv4 address.

SocketException

Error on the underlying socket.

JoinMulticastGroup(IPAddress, IPAddress)

Adds the UdpClient to a multicast group.

public void JoinMulticastGroup(IPAddress multicastAddr, IPAddress localAddress)

Parameters

multicastAddr IPAddress

IPAddress of the multicast group to join.

localAddress IPAddress

Local IPAddress for joining the group.

Exceptions

ArgumentNullException

localAddress or multicastAddr is null.

ArgumentException

localAddress or multicastAddr isn't an IPv4 address.

SocketException

Error on the underlying socket.

Receive(byte[], int, int, ref IPEndPoint)

Receive an UDP datagram that was sent by a remote host and store it in buffer.

public int Receive(byte[] buffer, int offset, int size, ref IPEndPoint remoteEP)

Parameters

buffer byte[]

A byte array to store the datagram data.

offset int

Offset where the datagram received must be stored in buffer.

size int

Maximum size of the datagram to receive.

remoteEP IPEndPoint

An IPEndPoint that represents the remote host from which the data was sent.

Returns

int

Length of the datagram received. Will be equal to the size of buffer if the datagram size was equal or bigger than the buffer size.

Remarks

If size is smaller than the packet to receive it will be truncated to a length of size without warning. Indeed "lwIP", the TCP/IP stack used commonly by RTOS, doesn't support the MSG_TRUNC socket option in calls to recvfrom to return the real length of the datagram when it is longer than the passed buffer opposite to common Un*x implementations.

Exceptions

ArgumentNullException

buffer is null

ArgumentException

buffer length is too short compared to offset and size

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

Receive(byte[], ref IPEndPoint)

Receive an UDP datagram that was sent by a remote host and store it in buffer.

public int Receive(byte[] buffer, ref IPEndPoint remoteEP)

Parameters

buffer byte[]

A byte array to store the datagram data

remoteEP IPEndPoint

An IPEndPoint that represents the remote host from which the data was sent.

Returns

int

Length of the datagram received. Will be equal to the size of buffer if the datagram size was equal or bigger than the buffer size.

Remarks

If the buffer is smaller than the packet to receive it will be truncated to the buffer size without warning. Indeed "lwIP", the TCP/IP stack used commonly by RTOS, doesn't support the MSG_TRUNC socket option in calls to recvfrom to return the real length of the datagram when it is longer than the passed buffer opposite to common Un*x implementations.

Exceptions

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

Send(byte[])

Send an UDP datagram to the connected host.

public int Send(byte[] dgram)

Parameters

dgram byte[]

ByteArray containing the datagram to send

Returns

int

Number of byte sent

Exceptions

ArgumentNullException

dgram is null

InvalidOperationException

The UdpClient is not connected.

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

Send(byte[], int, int)

Send an UDP datagram to the connected host.

public int Send(byte[] dgram, int offset, int size)

Parameters

dgram byte[]

ByteArray containing the datagram to send.

offset int

Offset where the datagram start in dgram.

size int

Length of the datagram.

Returns

int

Number of byte sent

Exceptions

ArgumentNullException

dgram is null.

ArgumentException

dgram length is too short compared to offset and size.

InvalidOperationException

The UdpClient is not connected.

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

Send(byte[], int, int, IPEndPoint)

Sends a UDP datagram to the specified remote host.

public int Send(byte[] dgram, int offset, int size, IPEndPoint endPoint)

Parameters

dgram byte[]

ByteArray containing the datagram to send.

offset int

Offset where the datagram start in dgram.

size int

Length of the datagram.

endPoint IPEndPoint

Remote endpoint to send the datagram to. Must be

null

if the UdpClient is connected to a remote endpoint.

Returns

int

Number of byte sent

Exceptions

ArgumentNullException

dgram is null

ArgumentException

dgram length is too short compared to offset and size

InvalidOperationException

A remote endPoint is specified but the UdpClient is already connected. Or remote endPoint is null but UdpClient is not connected.

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

Send(byte[], IPEndPoint)

Sends a UDP datagram to the specified remote host.

public int Send(byte[] dgram, IPEndPoint endPoint)

Parameters

dgram byte[]

ByteArray containing the datagram to send

endPoint IPEndPoint

Remote endpoint to send the datagram to. Must be

null

if the UdpClient is connected to a remote endpoint.

Returns

int

Number of byte sent

Exceptions

ArgumentNullException

dgram is null.

InvalidOperationException

A remote endPoint is specified but the UdpClient is already connected. Or remote endPoint is null but UdpClient is not connected.

ObjectDisposedException

UdpClient is already disposed.

SocketException

Error on the underlying socket.

SetMulticastInterface(IPAddress)

Define the local address (and thus interface) used to send multicast packets from this UdpClient This is only recommended on multi-homed systems

public void SetMulticastInterface(IPAddress localAddress)

Parameters

localAddress IPAddress

IP address of the interface used to send multicast packets

Exceptions

ArgumentNullException

localAddress is null.

ArgumentException

localAddress isn't an IPv4 address.

SocketException

Error on the underlying socket.