For your app to pass Windows Store certification,^[50] it must have code that leverages the connection profile just discussed. The goal here is to prevent users from getting unexpected carrier fees by using an app that internally performs networking operations. When on a nonmetered network, your app can use network bandwidth to its heart’s content. But, when on a metered network, your app should dynamically adjust its bandwidth usage based on network connectivity. For example, Windows itself does not download normal system updates when connected via a metered network. However, it does download critical security updates when on a metered network.

Specifically, when on a metered network, your app should

The Windows Store cannot easily verify that your app adheres to these policies. However, if users of your app complain about your app’s network consumption because it is not adhering to these policies, your app will be removed from the Windows Store.

That being said, your app can offer the user a setting that allows your app to violate these restrictions, but the important thing here is the user must be in control. Here is an example of an extension method you can use in your app before initiating a transfer operation. This method returns the maximum size of the transfer in megabytes allowed given the current network connection and the user’s preference:

public static UInt64 GetMaxTransferSizeInMegabytes(this ConnectionProfile cp,
   Boolean userOptIn = false,
   NetworkConnectivityLevel requiredLevel = NetworkConnectivityLevel.InternetAccess) {
   // If no physical connection or less than required, transfer 0 bytes
   if ((cp == null) || (cp.GetNetworkConnectivityLevel() < requiredLevel)) return 0;
   // If the user opts in to full network usage, there is no limit
   if (userOptIn) return UInt64.MaxValue;
   ConnectionCost cc = cp.GetConnectionCost();
   // If expensive, don't transfer anything (your app can really use 1MB more)
   if (cc.Roaming || cc.OverDataLimit) return 0;
   // No limit if not metered
   Boolean isMetered = cc.NetworkCostType == NetworkCostType.Fixed
      || cc.NetworkCostType == NetworkCostType.Variable;
   if (!isMetered) return UInt64.MaxValue;
   // Return MaxTransferSizeinMegabytes (if exist) or no limit
   return cp.GetDataPlanStatus().MaxTransferSizeInMegabytes ?? UInt64.MaxValue;
}

When your app is about to transfer data, it should call this method to see how large a transfer it can do to keep your users happy with your app’s network consumption and also to pass Windows Store certification.

In addition to costs, there are other issues worth keeping in mind when building a networking app—for example, power conservation. Apps should use as little bandwidth as possible to decrease power consumption. Also, it is best to avoid frequent periodic requests because this prevents the network hardware from entering an idle state. Instead, batch requests together and perform them all simultaneously less frequently. Also, consider caching data offline to avoid unnecessary network requests and also to give your users a good experience with your app when a network is unavailable.

Your app can receive a notification whenever network connectivity changes by having it register a callback method with the NetworkInformation class’ static NetworkStatusChanged event. Apps typically use this to re-establish connections whenever network connectivity is restored. Unfortunately, there is no way to easily find out what exactly changed. Also, this event is raised whenever any connection changes. For example, if your system has both wired and Wi-Fi connections, the event is raised when either of these changes. This means your app might have to walk through all the connections (by calling NetworkInformation’s static GetConnectionProfiles method) to see if the one it is currently using has changed; some changed events might not affect your app at all.

Situations might arise where the system or even your app is using multiple connections simultaneously. For example, if your app opened a socket to connect with a server over a mobile broadband connection, your app will continue to use that connection even if other better networks become available later. For these scenarios, you can certainly use the NetworkStatusChanged event to find out if a better connection has become available and re-establish the connection within your app’s code. Finally, if your app is suspended when a network status change occurs, the system will raise the event once when your app resumes.

Although the NetworkStatusChanged event does not indicate what has changed, you can get more information if you create a background task triggered by a SystemTrigger with a SystemTriggerType of NetworkStateChange. Then, whenever this task executes, its IBackgroundTaskInstance’s TriggerDetails property will refer to a NetworkStateChangeEventDetails object that exposes what has changed:

public sealed class NetworkStateChangeEventDetails {
   public Boolean HasNewConnectionCost { get; }
   public Boolean HasNewDomainConnectivityLevel { get; }
   public Boolean HasNewHostNameList { get; }
   public Boolean HasNewInternetConnectionProfile { get; }
   public Boolean HasNewNetworkConnectivityLevel { get; }
   public Boolean HasNewWwanRegistrationState { get; }
}

Because your app can be suspended, background transfers execute in a separate process. You can see this in Task Manager. Figure 7-5 shows the App1 app suspended, but there is also an App1 Download/Upload Host process that is not suspended. If you tap and hold this process and choose Go To Detail, Task Manager takes you to the Details tab, selecting a process called BackgroundTransferHost.exe. (This process ships with Windows itself.)

Figure 7-5. Task Manager showing the separate process Windows uses to perform background transfers.

Each app using WinRT’s background transfer API gets its own instance of the BackgroundTransferHost.exe process, and each instance runs in the package’s app container. If your app uses the background transfer API, you must turn on the Internet (Client) capability in your package’s manifest so that the host process gets this capability too.

As always, you can use the Windows Event Viewer (EventVwr.exe) to see system logs related to background transfer. Here’s where to look for the log entries: Applications And Service Logs > Microsoft > Windows > Runtime-Networking-BackgroundTransfer.^[53]

WinRT defines a Windows.Web.Http.Filters.HttpBaseProtocolFilter class. When you construct an HttpClient object using its default constructor, the object uses an instance of the HttpBaseProtocolFilter class internally. It is the HttpBaseProtocolFilter object that establishes the TCP socket connection with the server, sends the bytes to it, and receives the response bytes back. In addition, this filter manages caching, cookies, credentials, and a slew of other communication parameters. The class looks like this:

public sealed class HttpBaseProtocolFilter : IHttpFilter, IDisposable {
   public HttpBaseProtocolFilter();
   // Gets an object allowing you to set cache read and write behavior
   public HttpCacheControl CacheControl { get; }
   // Returns the cookie manager allowing you to get and set cookies
   public HttpCookieManager CookieManager { get; }
   // Allows you to set the maximum connections from filter to an HTTP server
   public UInt32 MaxConnectionsPerServer { get; set; }
   // Can filter follow a redirect response (default = true)
   public Boolean AllowAutoRedirect { get; set; }
   // Can filter automatically decompress response data (default = true)
   public Boolean AutomaticDecompression { get; set; }
   // Ignorable SSL errors
   public IList<ChainValidationResult> IgnorableServerCertificateErrors { get; }
   // Can filter use a proxy to send request
   public Boolean UseProxy { get; set; }
   // Sets HTTP proxy credentials
   public PasswordCredential ProxyCredential { get; set; }
   // Sets client certificate to send to server (if requested)
   public Certificate ClientCertificate { get; set; }
   // Sets HTTP server credentials
   public PasswordCredential ServerCredential { get; set; }
   // Can filter prompt for user credentials at server's request (default = true)
   public Boolean AllowUI { get; set; }
   // Sends HTTP request over the wire (SendRequestAsync is IHttpFilter's only member)
   public IAsyncOperationWithProgress<HttpResponseMessage, HttpProgress>
      SendRequestAsync(HttpRequestMessage request);
   // Releases unmanaged resources associated with the HttpBaseProtocolFilter
   public void Dispose();
}

Each package has a per-user cache that can hold downloaded HTTP content.^[55] This prevents one package’s downloaded content from being visible to another package’s app, and it also prevents content downloaded by one user from being visible to another user who happens to be using the same package. Using HttpBaseProtocolFilter’s CacheControl property, your app can control how HTTP responses are cached on the user’s local machine and use this to alter your app’s performance.

Before making an HTTP request, you can set CacheControl’s ReadBehavior to Default (as described in RFC 2616), MostRecent (if the server has more recent data, get it; otherwise, use cached data),^[56] or OnlyFromCache (get data from cache [useful when a PC is offline or at app startup time to show what’s cached quickly]). You can also set CacheControl’s WriteBehavior to control how the read data gets put into the user’s local cache. The possible values are Default (save the response in the local cache) and NoCache (do not save the response in the local cache [useful when streaming media]). When your app gets a response back, HttpResponseMessage’s Source property indicates whether the response came from the server or from the user’s local cache.

Here is an example that reads the most recent data from the server (or cache if it exists there); if read from the server, the data is not cached locally:

using (HttpBaseProtocolFilter filter = new HttpBaseProtocolFilter())
using (HttpClient client = new HttpClient(filter)) {
   // Try to get most recent data from server (or cache)
   filter.CacheControl.ReadBehavior = HttpCacheReadBehavior.MostRecent;
   // If we get it from server, don't store it in cache
   filter.CacheControl.WriteBehavior = HttpCacheWriteBehavior.NoCache;
   HttpRequestMessage request =
      new HttpRequestMessage(HttpMethod.Get, new Uri("http://Wintellect.com/"));
   HttpResponseMessage response = await client.SendRequestAsync(request);
   switch (response.Source) {
      case HttpResponseMessageSource.Cache:     // Data came from cache
         break;
      case HttpResponseMessageSource.Network:   // Data came from server
         break;
   }
}

To improve application performance, WinRT offers a simple Windows.Networking.BackgroundTransfer.ContentPrefetcher class:

public static class ContentPrefetcher {
   // Set of URIs to content the system periodically downloads and caches for your app
   // Use this when URIs don't change between runs of the app (Ex: a URI to weather in a city)
   public static IList<Uri> ContentUris { get; }
   // A URI to an XML file the system periodically downloads. The XML file contains prioritized
   // URIs to other content the system will also download and cache. Use this when URIs to
   // content do change between runs of the app.
   // Example: a URI to an XML file with URIs to the latest news stories
   public static Uri IndirectContentUri { get; set; }
   // NOTE: The system can prefetch data for up to 40 URIs. ContentUris takes precedence
   // over URIs in the XML file referred to by IndirectContentUri
}

After populating the ContentPrefetcher with some URIs, the system uses heuristics to determine when to periodically download the content on your app’s behalf. The goal is that, when your app runs, the data it needs has already been downloaded and stored in the package’s cache so that the app can simply make an HTTP request, get the data from the cache, and show the user relevant data without incurring a network performance hit. The exact heuristics are not documented and are subject to change, but they take into account power and network conditions as well as how often the app actually consumed the prefetched data and how often the app is used. The ContentPrefetcher is best for data an app shows at startup time, frequently used data, and data whose usefulness is long-lived.

In addition to a cache, each package also has a per-user set of cookies.^[57] Using HttpBaseProtocolFilter’s CookieManager property, your app can examine cookies returned from HTTP servers. It can also create cookies to send to a server. The following code demonstrates how to examine the cookies returned in an HTTP response from a server:

using (HttpBaseProtocolFilter filter = new HttpBaseProtocolFilter())
using (HttpClient client = new HttpClient(filter)) {
   HttpRequestMessage request =
      new HttpRequestMessage(HttpMethod.Get, new Uri("http://Bing.com/"));
   HttpResponseMessage response = await client.SendRequestAsync(request);
   // See the returned cookies (HttpCookieManager also has SetCookie and DeleteCookie methods)
   foreach (HttpCookie cookie in filter.CookieManager.GetCookies(request.RequestUri)) {
      String cookieInfo = String.Format(
         "Domain={0}, Expires={1}, HttpOnly={2}, Name={3}, Path={4}, Secure={5}, Value={6}",
         cookie.Domain, cookie.Expires, cookie.HttpOnly, cookie.Name, cookie.Path,
         cookie.Secure, cookie.Value);
   }
}

The last thing I want to say about filters is that you can chain them together. That is, you can create your own classes that implement the IHttpFilter interface with its SendRequestAsync method. Then you can create instances of your class and pass them into HttpClient’s constructor. Your filter class’ constructor should accept another filter object in order to maintain the chain of filters. Here is an example of a filter that calculates how much time it takes for the server to respond to each request:

internal sealed class RequestDurationFilter : IHttpFilter {
   private readonly IHttpFilter m_nextFilter;
   public RequestDurationFilter(IHttpFilter nextFilter) {
      if (nextFilter == null) throw new ArgumentNullException("nextFilter");
      m_nextFilter = nextFilter;
   }
   public void Dispose() { m_nextFilter.Dispose(); }
   public TimeSpan RequestDuration { get; private set; }
   public IAsyncOperationWithProgress<HttpResponseMessage, HttpProgress>
      SendRequestAsync(HttpRequestMessage request) {
      return AsyncInfo.Run<HttpResponseMessage, HttpProgress>(
         async (cancellationToken, progress) => {
            RequestDuration = TimeSpan.Zero;
            Stopwatch time = Stopwatch.StartNew(); // Get the current time
            HttpResponseMessage response =
               await m_nextFilter.SendRequestAsync(request).AsTask(cancellationToken, progress);
            RequestDuration = time.Elapsed;        // Set the request's duration
            cancellationToken.ThrowIfCancellationRequested();
            return response;
         });
   }
}

Using this filter is extremely simple:

using (RequestDurationFilter filter = new RequestDurationFilter(new HttpBaseProtocolFilter()))
using (HttpClient client = new HttpClient(filter)) {
   HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get,
                                   new Uri("http://WintellectNOW.com/"));
   HttpResponseMessage response = await client.SendRequestAsync(request);
   String s = String.Format("Request took {0}ms", filter.RequestDuration.TotalMilliseconds);
}

Custom filters open up all kinds of possibilities. You could create a filter that

Really, you’re only limited by your imagination. Microsoft has already implemented some of these filters for you. You can download the source code for them from the MSDN website. For sample filters showing retry and metered networks, see http://code.msdn.microsoft.com/windowsapps/HttpClient-sample-55700664. For a sample showing authentication, see http://code.msdn.microsoft.com/windowsapps/Web-Authentication-d0485122 and look at its AuthFilters folder.

Before showing examples working with sockets, I need to explain how your app identifies a remote system to WinRT. WinRT offers a Windows.Networking.HostName class that abstracts the name or address of a remote system:

public sealed class HostName : IStringable {
   // Constructor
   public HostName(String hostName);           // e.g. "server", "192.168.1.125", etc.
   // Read-only information about the host name:
   public HostNameType Type { get; }           // DomainName, Ipv4, Ipv6, Bluetooth
   public String RawName { get; }              // Same value passed to constructor
   public String DisplayName { get; }          // String that can be shown to a user
   public String CanonicalName { get; }        // String that can be used by the app's code
   public IPInformation IPInformation { get; } // NetworkAdapter info for an Ipv4/Ipv6 address
   // Methods to compare canonical hostnames with one another:
   public Boolean IsEqual(HostName hostName);
   public static Int32 Compare(String value1, String value2);
}

You can construct a HostName object, passing in an IPv4 or IPv6 literal, an actual host name (“Wintellect.com”), or a Bluetooth address. The constructor then sets the Type property to indicate what kind of string you passed in, determines the DisplayName version of the host name (which you can show to a user), and also determines the CanonicalName version (which you can use programmatically within your code).

The HostName class also offers IsEqual and Compare methods, which compare the canonical versions of two host names. Here is an example demonstrating how to compare host names:

// The top-level domain for the Russian Federation is "xn--p1ai" (in ASCII) and "pφ" (in
// Cyrillic). For more information, see http://en.wikipedia.org/wiki/.%D1%80%D1%84
String kremlinAscii = "πpe3ИДeHT.xn--p1ai";
HostName kremlin = new HostName(kremlinAscii);
String display = kremlin.DisplayName;      // "πpe3ИДeHT.pφ"
String canonical = kremlin.CanonicalName;  // "πpe3ИДeHT.pφ"
// Compares canonical names:
Boolean same = kremlin.IsEqual(new HostName("πpe3ИДeHT.pφ")); // true
Int32 order = HostName.Compare(kremlinAscii, "πpe3ИДeHT.pφ"); // 0
// Compare IPv6 addresses
HostName hostname = new HostName("0::1");
same = hostname.IsEqual(new HostName("0:0::1"));              // true
// Compare host names
hostname = new HostName("WINTELLECT.COM");
same = hostname.IsEqual(new HostName("Wintellect.com"));      // true

In addition to needing a HostName, your app also needs the name of a service that it wants to communicate with on the remote system. The service name is represented by a string. You can use a numeric literal for a port number (like “80” for HTTP) or a service name. Service names are similar to DNS names. DNS names are strings passed to a DNS server that then returns the IP address. Likewise, service names can be passed to a DNS server whose SRV records return a port number.^[58] Instead of querying DNS servers, Windows can map a host name to an IP address by looking up the host name in the %WinDir%System32DriversEtcHosts text file. Similarly, Windows can map a service name to a port number by looking up the service name in the %WinDir%System32DriversEtcServices text file.

The combination of a host name and a service name results in an endpoint. When your app’s local socket connects to a remote socket, you have a pair of endpoints. WinRT defines an EndpointPair class that encapsulates connection information:

public sealed class EndpointPair {
   public EndpointPair(
      HostName localHostName,  String localServiceName,
      HostName remoteHostName, String remoteServiceName);
   public HostName LocalHostName     { get; set; }
   public String   LocalServiceName  { get; set; }
   public HostName RemoteHostName    { get; set; }
   public String   RemoteServiceName { get; set; }
}

As you’ll see, some WinRT APIs accept an EndpointPair argument.

To accomplish client-side TCP communication with WinRT, you use the StreamSocket class, which looks like this:

public sealed class StreamSocket : IDisposable {
   public StreamSocket();
   // OPTIONAL: Modify connection (keep alive, outbound buffer size, QoS)
   // before calling ConnectAsync
   public StreamSocketControl Control { get; }
   // Returns connection read-only information (bandwidth, host/service names, timings)
   public StreamSocketInformation Information { get; }
   // Connect to a service on a remote machine (other overloads not shown here)
   public IAsyncAction ConnectAsync(HostName remoteHostName, String remoteServiceName,
      SocketProtectionLevel protectionLevel);
   // After calling ConnectAsync, the app uses these to read & write data
   public IInputStream  InputStream  { get; }
   public IOutputStream OutputStream { get; }
   // Upgrade a connected socket to use SSL
   public IAsyncAction UpgradeToSslAsync(
      SocketProtectionLevel protectionLevel, HostName validationHostName);
   public void Dispose();  // Close the socket
}

Here is an example that uses a StreamSocket to establish a connection with a server sending it a 32-bit integer length header followed by a set of bytes. The server sums the bytes and returns a 32-bit integer:

private async Task TcpClientAsync() {
   using (StreamSocket socket = new StreamSocket())
   using (DataWriter dw = new DataWriter(socket.OutputStream))
   using (DataReader dr = new DataReader(socket.InputStream)) {
      // Connect to the remote server:
      await socket.ConnectAsync(new HostName("localhost"), "8080");
      // Send message header (UInt32) and message bytes to server:
      Byte[] messageData = new Byte[] { 1, 2 };
      dw.WriteUInt32((UInt32)messageData.Length);
      dw.WriteBytes(messageData);
      await dw.StoreAsync();
      // Read UInt32 response from server:
      await dr.LoadAsync(sizeof(Int32));
      Int32 sum = dr.ReadInt32();
   }
}

When calling IInputStream’s ReadAsync method or when using a DataReader (which calls ReadAsync internally), think about the InputStreamOptions bit flags. Here is what the flags mean:

When any member of a StreamSocket, StreamSocketListener, or DatagramSocket fails, an Exception object is thrown. The Exception object’s HResult property indicates the reason for failure. You can easily convert the HResult value to a more meaningful value by passing it to the Windows.Networking.Sockets.SocketError class’ static GetStatus method. This returns a value from the SocketErrorStatus enumeration.

Although it’s not nearly as common as client-side-initiated communication, your Windows Store app can listen for TCP connections coming into it. This is useful for peer-to-peer scenarios where your app wants to let multiple users collaborate with each user on his or her own PC. A game might use this to allow two users to play against each other. Setting your app as a TCP listener requires the use of the StreamSocketListener class, which looks like this:

public sealed class StreamSocketListener : IDisposable {
   public StreamSocketListener();
   // OPTIONAL: Modify connection (QoS) before calling BindXxxAsync
   public StreamSocketListenerControl Control { get; }
   // Returns read-only information about the connection (local port)
   public StreamSocketListenerInformation Information { get; }
   // This event is raised whenever a client connects to this socket listener
   public event TypedEventHandler<StreamSocketListener,
      StreamSocketListenerConnectionReceivedEventArgs> ConnectionReceived;
   // Start listening on local IP addresses of all NICs
   // If localServiceName is "", system picks port
   public IAsyncAction BindServiceNameAsync(String localServiceName);
   // Start listening on the hostname/IP address and service name specified.
   // If localHostName is 'null', local IP is used; if localServiceName is "", OS picks port.
   public IAsyncAction BindEndpointAsync(HostName localHostName, String localServiceName);
   public void Dispose();    // Close the socket
}

When another machine connects to this StreamSocketListener, the ConnectionReceived event is raised. Any registered callback method receives a reference to the StreamSocketListener and, more importantly, a reference to a StreamSocketListenerConnectionReceivedEventArgs object, which looks like this:

public sealed class StreamSocketListenerConnectionReceivedEventArgs {
   // Returns a StreamSocket created by the client connection
   // Use its IInputStream and IOutputStream to talk to the client
   public StreamSocket Socket { get; }
}

Here is an example that uses a StreamSocketListener to process requests when clients connect. Each client sends the service a set of bytes. The service sums the bytes together and returns the sum back to the client:

// NOTE: Don't let the returned StreamSocketListener be garbage collected
//       until you no longer want to accept connections
private async Task<StreamSocketListener> StartTcpServiceAsync(String localServiceName) {
   var tcpService = new StreamSocketListener();
   // You must register handlers before calling BindXxxAsync
   tcpService.ConnectionReceived += OnConnectionReceived;
   await tcpService.BindServiceNameAsync(localServiceName); // Listen on desired port
   return tcpService;
}
private async void OnClientConnectionReceivedAsync(StreamSocketListener listener,
   StreamSocketListenerConnectionReceivedEventArgs e) {
   using (StreamSocket client = e.Socket)
   using (DataReader dr = new DataReader(e.Socket.InputStream))
   using (DataWriter dw = new DataWriter(e.Socket.OutputStream)) {
      // Read request header from client:
      await dr.LoadAsync(sizeof(Int32));
      UInt32 messageLength = dr.ReadUInt32();
      // Read request data from client:
      await dr.LoadAsync(messageLength);
      Byte[] bytes = new Byte[messageLength];
      dr.ReadBytes(bytes);
      Int32 sum = bytes.Sum(number => number);  // Calculate response
      // Send response to client:
      dw.WriteInt32(sum);
      await dw.StoreAsync();  // Required to send the response back to the client
   }
}

Many organizations configure their firewalls to disallow traditional socket communication to better secure their resources. However, many organizations do allow their firewalls to flow HTTP and HTTPS traffic over ports 80 and 443, respectively. This allows standard Internet access to the World Wide Web. But HTTP(S) traffic has its own shortcomings. For example, it is a request/response protocol that has a lot of overheard associated with it, making it less efficient than using the TCP protocol that HTTP(S) is built upon.

To address the HTTP(S) protocol’s strengths and weaknesses, the WebSocket protocol was created. (See http://www.w3.org/TR/websockets/.) The WebSocket protocol allows asynchronous, bidirectional, high-performance communication through firewalls using ports 80 and 443. It works by having a client initiate an HTTP(S) communication with a server. And then, once communication is established, the client and server continue using the same TCP socket. This establishes the connection successfully through the firewall (and proxy servers) and then allows for high-performance, bidirectional communication thereafter.^[59] The bidirectional aspect allows a server to send data to the client when it wants to; there’s no need for clients to periodically poll the server, use long-polling, or establish the client as a server, too, so that it can accept requests.^[60]

Of course, the client and the server must both support the WebSocket protocol, and today, not many servers support this protocol. A WebSocket client connects to a server by specifying a URL with a “ws://” or “wss://” schema. The former imitates the conversation using HTTP and transfers data in the clear over the network, while the latter initiates the conversation using HTTPS and encrypts the data as it goes over the network. In most cases, you’ll want to use a secure WebSocket connection because this sets up a secure end-to-end tunnel that intermediate proxy servers allow, dramatically increasing the chance your connection succeeds.

WinRT offers two classes that allow a Windows Store app to initiate the client-side communication to a WebSocket server: StreamWebSocket and MessageWebSocket.^[61] I’ll talk about the StreamWebSocket class in this section and the MessageWebSocket class in the next section. The StreamWebSocket class is very similar to the StreamSocket class; here is what it looks like:

public sealed class StreamWebSocket : IWebSocket, IDisposable {
   public StreamWebSocket();
   // OPTIONAL: Modify connection (output buffer size, NoDelay, credentials)
   //           before calling ConnectAsync
   public StreamWebSocketControl Control { get; }
   // Returns connection read-only information (local address, protocol, bandwidth stats)
   public StreamWebSocketInformation Information { get; }
   // This event is raised when the server closes the connection
   public event TypedEventHandler<IWebSocket, WebSocketClosedEventArgs> Closed;
   // Adds an HTTP request header sent when ConnectAsync is called
   public void SetRequestHeader(String headerName, String headerValue);
   // Connect to a remote machine ("ws://" or "wss://")
   public IAsyncAction ConnectAsync(Uri uri);
   // After calling ConnectAsync, the app uses these to read & write data
   public IInputStream  InputStream  { get; }
   public IOutputStream OutputStream { get; }
   // Closes the socket, indicating a reason and optional UTF-8 string with additional info
   public void Close(UInt16 code, String reason);
   public void Dispose();  // Close the socket
}

The WebSocket protocol defines a closing handshake. If the server closes the connection, the Closed event is raised. If you want to close the connection, just call the Dispose method or the Close method that takes a status code and reason.^[62] For troubleshooting issues related to WebSockets, see the system event logs under the following: Applications And Services Logs > Microsoft > Windows > Websocket-Protocol-Component.

And here is code demonstrating how to use the StreamWebSocket class to send data to the publicly accessible WebSocket Echo service (which you can learn more about at http://www.websocket.org/echo.html):

private async Task StreamWebSocketClientAsync() {
   using (StreamWebSocket ws = new StreamWebSocket()) {
      // Connect to the remote service (use "wss" for secure WebSocket [TLS])
      await ws.ConnectAsync(new Uri("wss://echo.websocket.org/"));
      // Write a UInt32 (string length) & a UTF-8 string to the service:
      using (DataWriter dw = new DataWriter(ws.OutputStream)) {
         String s = "Jeffrey";
         dw.WriteUInt32(dw.MeasureString(s));
         dw.WriteString(s);
         await dw.StoreAsync();
      }
      // The WebSocket Echo service just returns back whatever you send it.
      // Read a UInt32 (string length) & a UTF-8 string response from the service:
      using (DataReader dr = new DataReader(ws.InputStream)
         { InputStreamOptions = InputStreamOptions.Partial }) {
         while (dr.UnconsumedBufferLength < sizeof(UInt32)) {
            await dr.LoadAsync(1024);
         }
         UInt32 stringLen = dr.ReadUInt32();
         while (dr.UnconsumedBufferLength < stringLen) {
            await dr.LoadAsync(1024);
         }
         String s = dr.ReadString(stringLen);
      }
   }
}

Sometimes, it can be difficult to work with streaming protocols (as required by StreamSocket, StreamSocketListener, and StreamWebSocket). Instead, it’s frequently useful to send messages back and forth. To simplify these scenarios, WinRT offers a MessageWebSocket class that sends and receives data as messages consisting of UTF-8 text or binary data. The MessageWebSocket class looks like this:

public sealed class MessageWebSocket : IWebSocket, IDisposable {
   public MessageWebSocket();
   // OPTIONAL: Modify connection (max msg size, msg type (binary/UTF8), output buffer size,
   //          credentials) before calling ConnectAsync
   public MessageWebSocketControl Control { get; }
   // Returns connection read-only information (local address, protocol, bandwidth stats)
   public MessageWebSocketInformation Information { get; }
   // This event is raised when a message is received
   public event TypedEventHandler<MessageWebSocket,  MessageWebSocketMessageReceivedEventArgs>
      MessageReceived;
   // This event is raised when the server closes the connection
   public event TypedEventHandler<IWebSocket, WebSocketClosedEventArgs> Closed;
   // Adds an HTTP request header sent when ConnectAsync is called
   public void SetRequestHeader(string headerName, string headerValue);
   // Connect to a remote machine ("ws://" or "wss://")
   public IAsyncAction ConnectAsync(Uri uri);
   // After calling ConnectAsync, the app uses this to write a message
   public IOutputStream OutputStream { get; }
   // Closes the socket, indicating a reason and optional UTF-8 string with additional info
   public void Close(UInt16 code, String reason);
   public void Dispose();  // Close the socket
}

Here is a rewrite of the StreamWebSocketClientAsync method shown at the end of the previous section. This new version uses the MessageWebSocket class, greatly simplifying the code that processes the server’s response:

private async void MessageWebSocketClientAsync() {
   using (MessageWebSocket socket = new MessageWebSocket()) {
      // You must register handlers before calling ConnectAsync
      socket.MessageReceived += OnWebSocketMessageReceived;
      await socket.ConnectAsync(new Uri("wss://echo.websocket.org/"));
      using (DataWriter dw = new DataWriter(socket.OutputStream)) {
         dw.WriteString("Jeffrey");
         await dw.StoreAsync();  // Send a "message" to the service
      }
   }
}
private void OnWebSocketMessageReceived(MessageWebSocket sender,
   MessageWebSocketMessageReceivedEventArgs args) {
   // The service responded with a "message"; read all of it as a string
   using (DataReader dr = args.GetDataReader()) {
      String s = dr.ReadString(dr.UnconsumedBufferLength);
   }
}

For peer-to-peer communication using the UDP protocol, WinRT offers the DatagramSocket class. The DatagramSocket class allows you to

The class itself looks like this:

public sealed class DatagramSocket : IDisposable {
   public DatagramSocket();
   // OPTIONAL: Modify connection (outbound unicast hop limit, QoS, don't fragment, inbound
   //           buffer size) before calling BindXxxAsync, ConnectAsync, or GetOutputStreamAsync
   public DatagramSocketControl Control { get; }
   // Returns connection read-only information (local & remote hostname/port)
   public DatagramSocketInformation Information { get; }
   // This event is raised whenever this socket receives a message
   public event TypedEventHandler<DatagramSocket, DatagramSocketMessageReceivedEventArgs>
      MessageReceived;
   // Call these methods to listen for incoming data (OS picks port if localServicename is "0").
   public IAsyncAction BindServiceNameAsync(String localServiceName);
   public IAsyncAction BindEndpointAsync(HostName localHostName, String localServiceName);
   // After calling BindXxxAsync, a listener can call this to listen for multicast data packets.
   public void JoinMulticastGroup(HostName host);
   // Call this method to send data to a single remote machine
   public IAsyncAction ConnectAsync(HostName remoteHostName, String remoteServiceName);
   public IAsyncAction ConnectAsync(EndpointPair endpointPair);
   // After calling ConnectAsync, the app uses this to send data to the remote machine
   public IOutputStream OutputStream { get; }
   // Call this method (instead of ConnectAsync) to make a single request to a remote machine
   public IAsyncOperation<IOutputStream>
      GetOutputStreamAsync(HostName remoteHostName, String remoteServiceName);
   public IAsyncOperation<IOutputStream> GetOutputStreamAsync(EndpointPair endpointPair);
   public void Dispose();  // Close the socket
   // Static methods returning all endpoints based on remote hostname/service name.
   // You can connect to one of the returned endpoints
   public static IAsyncOperation< IReadOnlyList<EndpointPair>> GetEndpointPairsAsync(
      HostName remoteHostName, String remoteServiceName);
   public static IAsyncOperation< IReadOnlyList<EndpointPair>> GetEndpointPairsAsync(
      HostName remoteHostName, String remoteServiceName, HostNameSortOptions sortOptions);
}

Here is an example that uses a DatagramSocket to establish a listening server. The server accepts a set of bytes, sums them together, and returns the sum back to the client:

// NOTE: Don't let the returned DatagramSocket be garbage collected
//       until you no longer want to accept messages
private async Task<DatagramSocket> StartDatagramServiceAsync(String localServiceName) {
   var datagramService = new DatagramSocket();
   // You must register handlers before calling BindXxxAsync
   datagramService.MessageReceived += OnDatagramServiceMessageReceived;
   await datagramService.BindServiceNameAsync(localServiceName); // Listen on desired port
   return datagramService;
}
private async void OnDatagramServiceMessageReceived(DatagramSocket sender,
   DatagramSocketMessageReceivedEventArgs e) {
   // NOTE: This method could be called by any thread; to update UI use a CoreDispatcher
   // Read request from client:
   DataReader dr = e.GetDataReader();
   Byte[] bytes = new Byte[dr.UnconsumedBufferLength];
   dr.ReadBytes(bytes);
   // Process client's request:
   Int32 sum = bytes.Sum(number => number);
   // Send response to client:
   IOutputStream outputStream =
      await sender.GetOutputStreamAsync(e.RemoteAddress, e.RemotePort);
   using (var dw = new DataWriter(outputStream)) {
      dw.WriteInt32(sum);
      await dw.StoreAsync();
   }
}

Here is the client-side code that demonstrates how to make multiple requests to the same server:

private async Task DatagramClientAsync() {
   HostName localhost = new HostName("localhost");
   // This pattern makes multiple requests to a single server:
   using (var socket = new DatagramSocket()) {
      // You must register handlers before calling ConnectAsync
      socket.MessageReceived += OnDatagramClientMessageReceived;
      // ConnectAsync implicitly binds to a port so the server can respond
      await socket.ConnectAsync(localhost, c_datagramServiceName);
      // Send the 1st request:
      await socket.OutputStream.WriteAsync(new Byte[] { 1, 2 }.AsBuffer());
      // Send the 2nd request:
      await socket.OutputStream.WriteAsync(new Byte[] { 2, 3 }.AsBuffer());
   }
}
private void OnDatagramClientMessageReceived(
   DatagramSocket sender, DatagramSocketMessageReceivedEventArgs e) {
   // NOTE: This method could be called by any thread; to update UI use a CoreDispatcher
   using (DataReader dr = e.GetDataReader()) {
      Int32 sum = dr.ReadInt32();
   }
}

You can use a different pattern to perform client requests to multiple servers. The following code demonstrates this pattern:

private async Task DatagramClientAsync() {
   HostName host1 = new HostName("server1.com");
   HostName host2 = new HostName("server2.com");
   // This pattern makes multiple requests to different servers:
   using (var socket = new DatagramSocket()) {
      // Register handler before calling GetOutputStreamAsync
      socket.MessageReceived += OnDatagramClientMessageReceived;
      // Send 1st request (GetOutputStreamAsync implicitly binds to a port
      // so the server can respond):
      IOutputStream output = await socket.GetOutputStreamAsync(host1, c_datagramServiceName);
      await output.WriteAsync(new Byte[] { 1, 2 }.AsBuffer());
      // Send  2nd request (GetOutputStreamAsync implicitly binds to a port
      // so the server can respond):
      output = await socket.GetOutputStreamAsync(host2, c_datagramServiceName);
      await output.WriteAsync(new Byte[] { 2, 3 }.AsBuffer());
   }
}

There is a crucial difference between ConnectAsync and GetOutputStreamAsync. When you use ConnectAsync, the local socket will accept response data only from the remote host/service name passed to ConnectAsync. You can verify this by creating a new DatagramSocket on the server and then use it to send a response. If you do this, you see that the client does not get the response. On the other hand, GetOutputStreamAsync accepts response data from any other host/service name.

ConnectAsync and GetOutputStreamAsync both have overloads that take an EndpointPair as a parameter. Because the definition of an EndpointPair is the two endpoints between a local and remote host, you can imagine there are multiple EndpointPairs from one machine to another. The static GetOutputStreamAsync method returns the endpoints. On my PC, I get three EndpointPair objects: one pair over IPv6 (Ethernet), and two pairs over IPv4 (Ethernet and Wi-Fi). By default, the system sorts these endpoint pairs in order of quickest connection. But this means that Windows might connect quickly to an unreliable connection. In your app, you can get the list sorted with the most-reliable connection first by calling GetEndpointPairsAsync and passing in the HostNameSortOptions.OptimizeForLongConnections flag.

With DatagramSocket, you can also send and receive UDP multicast packets. Multicast allows one machine to broadcast a data packet to a number of other machines simultaneously. The sender sends the packet once, and the network infrastructure (like routers) replicates the data as it gets forwarded to the receivers. Multicast is typically used to stream audio and video to a large number of clients.

You set up a PC as a multicast listener the exact same way you set up a DatagramSocket listener. But then you must join the socket to a multicast group by specifying a multicast IP address (which you can learn more about at http://en.wikipedia.org/wiki/Multicast_address):

// NOTE: Don't let the returned DatagramSocket be garbage collected
//       until you no longer want to accept messages
private async Task<DatagramSocket> StartMulticastListenerAsync(String localServiceName) {
   DatagramSocket multicastListener = new DatagramSocket();
   // You must register handlers before calling BindXxxAsync
   multicastListener.MessageReceived += OnMulticastListenerMessageReceived;
   await multicastListener.BindServiceNameAsync(localServiceName); // Listen on desired port
   // IPv4 multicast IP addresses: 224.0.0.0 to 239.255.255.255
   HostName hostname = new HostName("224.168.100.2"); // Pick a multicast IP address
   multicastListener.JoinMulticastGroup(hostname);    // Join socket to the multicast IP address
   return multicastListener;
}

When the socket receives a message, you process it as you normally would in the OnMulticastListenerMessageReceived event handler. In the handler, you can examine the DatagramSocketMessageReceivedEventArgs object’s RemoteAddress and RemotePort properties to determine which remote machine sent the data packet.

You can check how the multicast address is bound to the network cards with netsh interface ipv4 show joins. The output will be similar to what’s shown next. Note how 224.168.100.2 is bound to all network interfaces.

C:>netsh interface ipv4 show joins
Interface 1: Loopback Pseudo-Interface 1
Scope       References  Last  Address
----------  ----------  ----  ---------------------------------
0                    1  Yes   224.168.100.2
0                    4  Yes   239.255.255.250
Interface 13: Wi-Fi
Scope       References  Last  Address
----------  ----------  ----  ---------------------------------
0                    0  No    224.0.0.1
0                    1  Yes   224.0.0.252
0                    1  No    224.168.100.2
0                    4  No    239.255.255.250
Interface 12: Ethernet
Scope       References  Last  Address
----------  ----------  ----  ---------------------------------
0                    0  No    224.0.0.1
0                    1  No    224.0.0.252
0                    1  Yes   224.0.0.253
0                    1  No    224.168.100.2
0                    4  No    239.255.255.250
Interface 18: Bluetooth Network Connection
Scope       References  Last  Address
----------  ----------  ----  ---------------------------------
0                    0  Yes   224.0.0.1
0                    1  Yes   224.168.100.2

Sending data to a multicast group is identical to how you normally send data using a DatagramSocket; you just need to use the multicast IP address and service name (port).