DatagramSocket.ConnectAsync Method

Definition

Namespace:

Windows.Networking.Sockets

Overloads

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.

ConnectAsync(EndpointPair)

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

public:
 virtual IAsyncAction ^ ConnectAsync(EndpointPair ^ endpointPair) = ConnectAsync;

/// [Windows.Foundation.Metadata.Overload("ConnectWithEndpointPairAsync")]
IAsyncAction ConnectAsync(EndpointPair const& endpointPair);

[Windows.Foundation.Metadata.Overload("ConnectWithEndpointPairAsync")]
public IAsyncAction ConnectAsync(EndpointPair endpointPair);

function connectAsync(endpointPair)

Public Function ConnectAsync (endpointPair As EndpointPair) As IAsyncAction

Parameters

endpointPair

EndpointPair

An EndpointPair object that specifies local hostname or IP address, local service name or UDP port, the remote hostname or remote IP address, and the remote service name or remote UDP port for the remote network destination.

Returns

IAsyncAction

An asynchronous connect operation on a DatagramSocket object.

Attributes

OverloadAttribute

Windows requirements

App capabilities

ID_CAP_NETWORKING [Windows Phone] internetClientServer privateNetworkClientServer

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

• Using one of the GetOutputStreamAsync methods.
• After a successful call to the ConnectAsync method using the OutputStream property.

The GetOutputStreamAsync methods allow an app to send UDP datagrams using a DatagramSocket object to multiple network destinations. Each time the GetOutputStreamAsync 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:

• Create the DatagramSocket.
• 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.
• Assign the MessageReceived event to an event handler.
• Call the ConnectAsync method to connect to the remote endpoint.
• Use the OutputStream property on the DatagramSocket with a DataWriter object to send messages to the remote endpoint.
• The MessageReceived event handler will be invoked whenever a message from the remote endpoint arrives. The GetOutputStreamAsync methods also differ from the ConnectAsync method when an app uses the BindEndpointAsync or BindServiceNameAsync method to bind to a local service name or UDP port. With the GetOutputStreamAsync methods, the app will receive packets from any remote destination sent to the local service name or UDP port. With the ConnectAsync methods, the app will only receive packets from the remote destination passed as parameters to the ConnectAsync methods.

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 method only works for unicast IP addresses. When trying to call the ConnectAsync 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 SocketError.GetStatus method, the value returned will be SocketErrorStatus.HostNotFound.

Using ConnectAsync with a broadcast IP address such as 255.255.255.255 will connect, but will broadcast only through the first network adapter found. To broadcast on all available adapters, use GetOutputStreamAsync.

See also

• ConnectAsync(HostName, String)
• EndpointPair
• OutputStream
• DataWriter
• IOutputStream

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:
 virtual IAsyncAction ^ ConnectAsync(HostName ^ remoteHostName, Platform::String ^ remoteServiceName) = ConnectAsync;

/// [Windows.Foundation.Metadata.Overload("ConnectAsync")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncAction ConnectAsync(HostName const& remoteHostName, winrt::hstring const& remoteServiceName);

[Windows.Foundation.Metadata.Overload("ConnectAsync")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncAction ConnectAsync(HostName remoteHostName, string remoteServiceName);

function connectAsync(remoteHostName, remoteServiceName)

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

Parameters

remoteHostName

HostName

The hostname or IP address of the remote network destination.

remoteServiceName

String

Platform::String

winrt::hstring

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

Returns

IAsyncAction

An asynchronous connect operation on a DatagramSocket object.

Attributes

OverloadAttribute RemoteAsyncAttribute

Windows requirements

App capabilities

ID_CAP_NETWORKING [Windows Phone] internetClientServer privateNetworkClientServer

Remarks

The ConnectAsync 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 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 method will resolve the remote hostname to an IP address. If the remoteServiceName parameter contains a service name, then the ConnectAsync 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:

• Use one of the GetOutputStreamAsync methods.
• After a successful call to the ConnectAsync method use the OutputStream property.

The GetOutputStreamAsync methods allow an app to send UDP datagrams using a DatagramSocket object to multiple network destinations. Each time the GetOutputStreamAsync 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 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 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 methods also differ from the ConnectAsync method when an app uses the BindEndpointAsync or BindServiceNameAsync method to bind to a local service name or UDP port. With the GetOutputStreamAsync methods, the app will receive packets from any remote destination sent to the local service name or UDP port. With the ConnectAsync methods, the app will only receive packets from the remote destination passed as parameters to the ConnectAsync methods.

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

Using ConnectAsync with a broadcast IP address such as 255.255.255.255 will connect, but will broadcast only through the first network adapter found. To broadcast on all available adapters, use GetOutputStreamAsync.

See also

• ConnectAsync(EndpointPair)
• HostName
• OutputStream
• DataWriter
• IOutputStream