How to connect with a datagram socket (HTML)

Article
08/31/2015

This topics shows how to use UDP to send and receive network data in a Windows Runtime app with a DatagramSocket.

The client component of the sample creates a UDP socket, uses the socket to send and receive data, and closes the socket. The server component of the sample creates a UDP socket to listen for incoming network packets, receives incoming UDP packets from the client, sends data to the client, and closes the socket. This sample is provided in the JavaScript, C#, and C++ programming languages.

The client component of the sample demonstrates the following features:

Use the DatagramSocket class to create a UDP socket for the client to send and receive data.
Add a handler for a DatagramSocket.MessageReceived event that indicates that a UDP datagram was received on the DatagramSocket object.
Set the remote endpoint for a UDP network server where packets should be sent using one of the DatagramSocket.ConnectAsync methods.
Send data to the server using the Streams.DataWriter object which allows a programmer to write common types (integers and strings, for example) on any stream.
Close the socket.

The server component of the sample demonstrates the following features:

Use the DatagramSocket class to create a UDP socket to listen for and receive incoming datagram packets and for sending packets.
Add a handler for a DatagramSocket.MessageReceived event that indicates that a UDP datagram was received on the DatagramSocket object.
Bind the socket to a local service name to listen for incoming UDP packets using the DatagramSocket.BindServiceNameAsync method.
Receive a DatagramSocket.MessageReceived event that indicates that a UDP datagram was received on the DatagramSocket object.
Receive data from the client using the DatagramSocket.MessageReceived handler. The DatagramSocketMessageReceivedEventArgs object passed to the DatagramSocket.MessageReceived handler allows an app to receive data from the client and also determine the remote address and port that sent the data.
Close the socket.

Note Use of this sample requires network access using the loopback interface.

Objective: Create a network connection to another computer or device using a DatagramSocket socket.

Prerequisites

The following examples use JavaScript. For help creating your first app, see Create your first Windows Store app using JavaScript.

To ensure your Windows Store app is network ready, you must set the capability in the project Package.appxmanifest file. For a definition of each network capability, see How to configure network isolation capabilities.

Instructions

1. Create a new project

Open Microsoft Visual Studio 2013 and select New Project from the File menu.
In the list of templates, choose JavaScript.
Under the section, choose Store apps.
Under the section, select Universal Apps, Windows apps, or Windows Phone apps (depending on the platform you are targeting), and then select Blank Application.
Name the application socketsSample and click OK.

2. Set capabilities to enable network access

You need to set network capabilities for your app if the app needs network access. An app that uses a DatagramSocket to connect to a network service would need network capabilities set.

If the app needs to be able to connect as a client to remote services on the Internet, then the Internet (Client) capability is needed. If the app needs to be able to connect as a client to remote services on a home network or work network, then the Private Networks (Client & Server) capability is needed.

If the app needs to use the DatagramSocket to listen for incoming connections from remote endpoints on the Internet, then the Internet (Client & Server) capability is needed. If the app needs to use the DatagramSocket to listen for incoming connections from remote endpoints on a home network or work network, then the Private Networks (Client & Server) capability is needed.

Note On Windows Phone, there is only one network capability Internet (Client & Server) which enables all network access for the app.

If the server component of this sample listening for incoming connections is running on the same device as the client component, this would require loopback access. Apps developed and run in Visual Studio 2013 will automatically be registered as being exempt from the loopback restrictions. For more information, see How to enable loopback and debug network isolation.

For more information on network access, see How to configure network isolation capabilities.

These steps are needed to set network capabilities for an app before it is deployed if it accesses a network service on the Internet or on a home or work network.

Use Microsoft Visual Studio to open the package.appxmanifest file.
Select the Capabilities tab.
To build the Windows version of the sample, Select the Internet (Client) and Private Networks (Client & Server) capabilities.

To build the Windows Phone version of the sample, select the Internet (Client & Server) capability.
Save and close the manifest file.

3. Add HTML UI

Open the html folder. Open a new startListener.html file and add the following HTML to the <head> and <body> sections.


<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <script src="/js/socketsSample.js"></script>
    <script src="/js/startListener.js"></script>
</head>
<body>
    <div data-win-control="SdkSample.ScenarioInput">
        <p>
            DatagramSocket is used to create the 'server' side of a connection. It listens on a 'service name' (often a port number) and 
            each time a datagram is received on the port number it fires MessageReceived event.
        </p>
        <p>
            <label for="serviceNameAccept">Service Name:</label>
            <input id="serviceNameAccept" type="text" />
        </p>
        <p>
            <button id="buttonStartListener">Listen</button>
        </p>
    </div>
    <div data-win-control="SdkSample.ScenarioOutput">
        <p id="statusBox"></p>
        <p id="outputBox"></p>
    </div>
</body>
</html>

Open the html folder. Open a new connectToListener.html file and add the following HTML to the <head> and <body> sections.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <script src="/js/connectToListener.js"></script>
</head>
<body>
    <div data-win-control="SdkSample.ScenarioInput">
        <p>
            Next, you need the 'other side of the connection' -- you need to connect to a listener. The host name
            and service name (often a port number) to connect to are the 'Host name:' and 'Service name:' entries.
            The service name should match what you started to listen to!
        </p>
        <p>
            The connection will automatically use IPv6 as needed. It will also resolve internationalized
            domain names.
        </p>
        <p>
            Due to the network security system, you cannot connect to other applications running on the same
            machine. This means that you can only use 'localhost' to connect to the same application (specifically,
            you can connect to a listener on the same machine running in the same app container)
        </p>
        <p>
            <label for="hostNameConnect">Host Name:</label>
            <input id="hostNameConnect" type="text" disabled="disabled" />
        </p>
        <p>
            <label for="serviceNameConnect">Service Name:</label>
            <input id="serviceNameConnect" type="text" />
        </p>
        <p>
            <button id="buttonOpen">Connect Now</button>
        </p>
    </div>
    <div data-win-control="SdkSample.ScenarioOutput">
        <p id="statusBox"></p>
        <p id="outputBox"></p>
    </div>
</body>
</html>

Open the html folder. Open a new sendData.html file and add the following HTML to the <head> and> <body> sections.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <script src="/js/sendData.js"></script>
</head>
<body>
    <div data-win-control="SdkSample.ScenarioInput">
        <p>
            Now you can send data to the "server". Sending data is often done with the DataWriter
            object; it will write to the socket stream.
        </p>
        <p>
            <button id="buttonSend">Send 'hello' now</button>
        </p>
    </div>
    <div data-win-control="SdkSample.ScenarioOutput">
        <p id="statusBox"></p>
        <p id="outputBox"></p>
    </div>
</body>
</html>

Open the html folder. Open a new closeSocket.html file and add the following HTML to the <head> and <body> sections.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <script src="/js/closeSocket.js"></script>
</head>
<body>
    <div data-win-control="SdkSample.ScenarioInput">
        <p>
            Lastly, you can close all sockets.
        </p>
        <p>
            If you don't close your socket, it will be closed for you when the application exits.
        </p>
        <p>
            <button id="buttonClose">Close all sockets</button>
        </p>
    </div>
    <div data-win-control="SdkSample.ScenarioOutput">
        <p id="statusBox"></p>
        <p id="outputBox"></p>
    </div>
</body>
</html>

4. Define the sample and the scenarios

The code in this step defines the sample, the HTML files, and the scenarios that are used by the sample. The code also add event listeners and starts the app. The scenario options allow the user to start the socket listener, start the client to connect to the listener, have the client send some data to the server, and close the sockets.

Open the js folder. Open the default.js file and add the following code to the file.

    var sampleTitle = "DatagramSocket";

    var scenarios = [
        { url: "/html/startListener.html", title: "Start DatagramSocket Listener" },
        { url: "/html/connectToListener.html", title: "Connect to Listener" },
        { url: "/html/sendData.html", title: "Send Data" },
        { url: "/html/closeSocket.html", title: "Close Socket" }
    ];

    function activated(eventObject) {
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
            // Use setPromise to indicate to the system that the splash screen must not be torn down
            // until after processAll and navigate complete asynchronously.
            eventObject.setPromise(WinJS.UI.processAll().then(function () {
                // Navigate to either the first scenario or to the last running scenario
                // before suspension or termination.
                var url = WinJS.Application.sessionState.lastUrl || scenarios[0].url;
                return WinJS.Navigation.navigate(url);
            }));
        }
    }

    WinJS.Navigation.addEventListener("navigated", function (eventObject) {
        var url = eventObject.detail.location;
        var host = document.getElementById("contentHost");
        // Call unload method on current scenario, if there is one
        host.winControl && host.winControl.unload && host.winControl.unload();
        WinJS.Utilities.empty(host);
        eventObject.detail.setPromise(WinJS.UI.Pages.render(url, host, eventObject.detail.state).then(function () {
            WinJS.Application.sessionState.lastUrl = url;
        }));
    });

    WinJS.Namespace.define("SdkSample", {
        sampleTitle: sampleTitle,
        scenarios: scenarios
    });

    WinJS.Application.addEventListener("activated", activated, false);
    WinJS.Application.start();

5. Define variables for sockets and event functions

The code in this step creates a number of variables including the listener socket, the client socket, and various variable for errors and events. Variables are created to track whether the client socket is in a connected or closing state. This step also defines the hostname and service name (UDP port) to connect and send data to as well as the local service name (UDP port) on which to accept and receive data. The value of the remote hostname, remote service name, and local service name are set to a default value which can be changed in the UI.

Open the js folder. Open a new socketsSample.js file and add the following code to the file.

var socketsSample = {};

(function () {
    "use strict";

    socketsSample.listener = null;
    socketsSample.listenerOutputStream = null;
    socketsSample.listenerPeerAddress = null;
    socketsSample.listenerPeerPort = null;
    socketsSample.clientSocket = null;
    socketsSample.clientDataWriter = null;
    socketsSample.connected = false;
    socketsSample.closing = false;
    socketsSample.bindingToService = false;

    socketsSample.serviceNameAccept = "22112";
    socketsSample.hostNameConnect = "localhost";
    socketsSample.serviceNameConnect = "22112";

    socketsSample.close = function () {

        socketsSample.closing = true;

        if (socketsSample.listener) {
            socketsSample.listener.close();
        }

        if (socketsSample.clientSocket) {
            socketsSample.clientSocket.close();
        }

        socketsSample.listener = null;
        socketsSample.listenerOutputStream = null;
        socketsSample.listenerPeerAddress = null;
        socketsSample.listenerPeerPort = null;
        socketsSample.clientSocket = null;
        socketsSample.clientDataWriter = null;
        socketsSample.connected = false;
    };

    socketsSample.displayStatus = function (message) {
        document.getElementById("statusBox").innerHTML = message;
    };

    socketsSample.displayOutput = function (message) {
        document.getElementById("outputBox").innerHTML = message;
    };

    socketsSample.setValues = function () {
        var serviceNameAcceptInput = document.getElementById("serviceNameAccept");
        var hostNameConnectInput = document.getElementById("hostNameConnect");
        var serviceNameConnectInput = document.getElementById("serviceNameConnect");

        if (serviceNameAcceptInput) {
            serviceNameAcceptInput.value = socketsSample.serviceNameAccept;
        }
        if (hostNameConnectInput) {
            hostNameConnectInput.value = socketsSample.hostNameConnect;
        }
        if (serviceNameConnectInput) {
            serviceNameConnectInput.value = socketsSample.serviceNameConnect;
        }
    };

    socketsSample.getValues = function (evt) {
        switch (evt.target.id) {
            case "serviceNameAccept":
                socketsSample.serviceNameAccept = evt.target.value;
                break;
            case "hostNameConnect":
                socketsSample.hostNameConnect = evt.target.value;
                break;
            case "serviceNameConnect":
                socketsSample.serviceNameConnect = evt.target.value;
                break;
        }
    };
})();

6. Create a listener and start listening to a service name (port)

The code in this section creates a listener and starts listening. There are also functions added to handle events when the user requests that the listener bind to an IP address and UDP port, accept a connection, and read data sent from the client.

Note Although this specific example is self-contained (client and server are in the same app), you would normally have separate client and server apps.

Open the js folder. Open a new startListener.js file and add the following code to the file:

    var page = WinJS.UI.Pages.define("/html/startListener.html", {
        ready: function (element, options) {
            document.getElementById("buttonStartListener").addEventListener("click", startListener, false);
            document.getElementById("serviceNameAccept").addEventListener("change", socketsSample.getValues, false);
            socketsSample.setValues();
        }
    });

    function startListener() {
        var serviceName = document.getElementById("serviceNameAccept").value;
        if (serviceName === "") {
            socketsSample.displayStatus("Please provide a service name.");
            return;
        }

        if (socketsSample.listener) {
            socketsSample.displayStatus("Already have a listener; call close to close the listener.");
            return;
        }

        socketsSample.closing = false;
        socketsSample.bindingToService = true;
        socketsSample.listener = new Windows.Networking.Sockets.DatagramSocket();
        socketsSample.listener.addEventListener("messagereceived", onServerMessageReceived);
        socketsSample.displayStatus("Server: listener creation started.");
        socketsSample.listener.bindServiceNameAsync(serviceName).done(function () {
            socketsSample.displayStatus("Server: listener creation completed.");
            socketsSample.bindingToService = false;
        }, onError);
    }

    function onServerMessageReceived(eventArgument) {
        if (socketsSample.listenerOutputStream) {
            echoMessage(socketsSample.listenerOutputStream, eventArgument);
            return;
        }

        socketsSample.listener.getOutputStreamAsync(eventArgument.remoteAddress, eventArgument.remotePort).done(function (outputStream) {
            if (!socketsSample.listenerOutputStream) {
                socketsSample.listenerOutputStream = outputStream;
                socketsSample.listenerPeerAddress = eventArgument.remoteAddress;
                socketsSample.listenerPeerPort = eventArgument.remotePort;
            }

            echoMessage(socketsSample.listenerOutputStream, eventArgument);
        });
    }

    function echoMessage(outputStream, eventArgument) {
        if (socketsSample.listenerPeerAddress !== eventArgument.remoteAddress ||
            socketsSample.listenerPeerPort !== eventArgument.remotePort) {
            socketsSample.displayStatus("Got datagram from " + eventArguments.remoteAddress + ":" + eventArguments.remotePort +
                ", but already 'connected' to " + socketsSample.listenerPeerAddress + ":" + socketsSample.listenerPeerPort);
            return;
        }

        outputStream.writeAsync(eventArgument.getDataReader().detachBuffer()).done(function () {
            // Do nothing - client will print out a message when data is received.
        });
    }

    function onError(reason) {
        // Clean up a listener if we failed to bind to a port.
        if (socketsSample.bindingToService) {
            socketsSample.listener = null;
            socketsSample.bindingToService = false;
        }

        // When we close a socket, outstanding async operations will be canceled and the
        // error callbacks called.  There's no point in displaying those errors.
        if (!socketsSample.closing) {
            socketsSample.displayStatus(reason);
        }
    }

7. Create the socket and connect to a remote endpoint

The code in this step adds a function to create the socket and connect to the remote endpoint, typically a server, using the DatagramSocket.ConnectAsync method. A function is added to handle when a message is received by the client. A function is also added to handle cases when there is an error when the client tries to make a connection.

Open the js folder. Open a new connectToListener.js file and add the following code to the file:

    var page = WinJS.UI.Pages.define("/html/connectToListener.html", {
        ready: function (element, options) {
            document.getElementById("buttonOpen").addEventListener("click", openClient, false);
            document.getElementById("hostNameConnect").addEventListener("change", socketsSample.getValues, false);
            document.getElementById("serviceNameConnect").addEventListener("change", socketsSample.getValues, false);
            socketsSample.setValues();
        }
    });

    function openClient() {
        var serviceName = document.getElementById("serviceNameConnect").value;
        if (serviceName === "") {
            socketsSample.displayStatus("Please provide a service name.");
            return;
        }

        // By default 'hostNameConnect' is disabled and host name validation is not required. When enabling the text
        // box validating the host name is required since it was received from an untrusted source (user input).
        // Note that when enabling the text box users may provide names for hosts on the intErnet that require the
        // "Internet (Client)" capability.
        var hostName;
        try {
            hostName = new Windows.Networking.HostName(document.getElementById("hostNameConnect").value);
        } catch (error) {
            socketsSample.displayStatus("Error: Invalid host name.");
            return;
        }

        if (socketsSample.clientSocket) {
            socketsSample.displayStatus("Already have a client; call close to close the listener and the client.");
            return;
        }

        socketsSample.closing = false;
        socketsSample.clientSocket = new Windows.Networking.Sockets.DatagramSocket();
        socketsSample.clientSocket.addEventListener("messagereceived", onMessageReceived);
        socketsSample.displayStatus("Client: connection started.");
        socketsSample.clientSocket.connectAsync(hostName, serviceName).done(function () {
            socketsSample.displayStatus("Client: connection completed.");
            socketsSample.connected = true;
        }, onError);
    }

    function onMessageReceived(eventArgument) {
        try {
            var messageLength = eventArgument.getDataReader().unconsumedBufferLength;
            var message = eventArgument.getDataReader().readString(messageLength);
            socketsSample.displayStatus("Client: receive message from server \"" + message + "\"");
        } catch (exception) {
            status = Windows.Networking.Sockets.SocketError.getStatus(exception.number);
            if (status === Windows.Networking.Sockets.SocketErrorStatus.connectionResetByPeer) {
                socketsSample.displayStatus("Peer does not listen on the specific port. Please make sure that you run step 1 first " +
                "or you have a server properly working on a remote server.");
            } else {
                socketsSample.displayStatus("Error happened when receiving a datagram: " + exception.message);
            }
        }
    }

    function onError(reason) {
        socketsSample.clientSocket = null;

        // When we close a socket, outstanding async operations will be canceled and the
        // error callbacks called.  There's no point in displaying those errors.
        if (!socketsSample.closing) {
            socketsSample.displayStatus(reason);
        }
    }

8. Send and receive data on the client

The code in this step adds a function to send data to the remote UDP endpoint using methods on the Windows.Storage.Streams.DataWriter class.

Open the js folder. Open a new sendData.js file and add the following code to file:

    var page = WinJS.UI.Pages.define("/html/sendData.html", {
        ready: function (element, options) {
            document.getElementById("buttonSend").addEventListener("click", sendHello, false);
        }
    });

    function sendHello() {
        if (!socketsSample.connected) {
            socketsSample.displayStatus("Client: you must connect the client before using it.");
            return;
        }

        if (!socketsSample.clientDataWriter) {
            socketsSample.clientDataWriter = new Windows.Storage.Streams.DataWriter(socketsSample.clientSocket.outputStream);
        }

        var string = "Hello World";
        socketsSample.clientDataWriter.writeString(string);

        socketsSample.displayStatus("Client sending: " + string + ".");
        socketsSample.clientDataWriter.storeAsync().done(function () {
            socketsSample.displayStatus("Client sent: " + string + ".");
        }, onError);
    }

    function onError(reason) {
        // When we close a socket, outstanding async operations will be canceled and the
        // error callbacks called.  There's no point in displaying those errors.
        if (!socketsSample.closing) {
            socketsSample.displayStatus(reason);
        }
    }

9. Close the sockets

The code in this step will close the sockets using the DatagramSocket.Close method. When sockets are closed, all pending operations will end and the error routines are called.

Open the js folder. Open a new socketClose.js file and add the following code to the file:

    var page = WinJS.UI.Pages.define("/html/sendData.html", {
        ready: function (element, options) {
            document.getElementById("buttonSend").addEventListener("click", sendHello, false);
        }
    });

    function sendHello() {
        if (!socketsSample.connected) {
            socketsSample.displayStatus("Client: you must connect the client before using it.");
            return;
        }

        if (!socketsSample.clientDataWriter) {
            socketsSample.clientDataWriter = new Windows.Storage.Streams.DataWriter(socketsSample.clientSocket.outputStream);
        }

        var string = "Hello World";
        socketsSample.clientDataWriter.writeString(string);

        socketsSample.displayStatus("Client sending: " + string + ".");
        socketsSample.clientDataWriter.storeAsync().done(function () {
            socketsSample.displayStatus("Client sent: " + string + ".");
        }, onError);
    }

    function onError(reason) {
        // When we close a socket, outstanding async operations will be canceled and the
        // error callbacks called.  There's no point in displaying those errors.
        if (!socketsSample.closing) {
            socketsSample.displayStatus(reason);
        }
    }

10. Run the application

To run the app, press F5 in Visual Studio to run the project. Select the buttons in order to start the listener, to connect the client to the listener, to send data, and to close sockets.

Summary and next steps

In this topic you created an app that uses a UDP datagram socket to make a network connection and send data using a DatagramSocket object. The app also showed how to listen on a UDP port and receive data.

The source code and build files for this topic are available as the DatagramSocket sample.

You can also use a stream socket to make a network connection used to send and receive data. For an example, see How to connect with a stream socket.

Other resources

Connecting with sockets

How to configure network isolation capabilities

How to connect with a stream socket

How to set timeouts on socket operations

How to use advanced socket controls

Troubleshoot and debug network connections

Reference

DatagramSocket

Windows.Networking