Quickstart: Connecting apps using tapping or browsing (XAML)

This topic walks you through the code you need to make your app capable of connecting to another instance of your app running on another device using Proximity.

Proximity is a great way for users on two devices to share your app experience and data. App users can initiate the shared app connection by tapping two devices together or by discovering a peer app within wireless range. When the connection has been established, a socket transfers data between the apps.

To initiate a connection between two instances of the app using a tap gesture, most devices must have NFC. On a PC, this connection channel can be made over Bluetooth, Wi-Fi Direct, or an infrastructure network. On Windows Phone, the connection can be established over Bluetooth or an infrastructure network. Wi-Fi Direct is not supported on Windows Phone. This means that tapping to connect works between a Windows Phone and a PC, but that communication is restricted to using either Bluetooth or an infrastructure network.

Using the Proximity browsing feature, a user on one device can discover your app running on nearby devices without tapping them together. When a user discovers a peer app on a nearby device, the user can request a connection to the peer app. On a PC, browsing uses Wi-Fi Direct. On a Windows Phone, browsing uses Bluetooth. Therefore, an app running on a PC cannot discover a peer app running on a phone by browsing, and vice versa.

The sample in this topic shows you how to use Proximity and the
PeerFinder class to create a long-term socket
connection with a peer app on another device.

For connections triggered by a tap, if the peer app is not running in the foreground on the target
device, then Proximity invites the user to activate the app on the target device. If the peer app is not
installed on the target device, then Proximity invites the user on the target device to install the app from
the Store. For more details on activating apps using a tap gesture, see
"Activating apps using Proximity" in
Proximity and tapping.

Objective: Create a connection between two devices by using Proximity tapping or wireless browsing.

Prerequisites

Microsoft Visual Studio Express 2012 for Windows 8

Instructions

1. Create a new project and enable Proximity

Open Visual Studio Express 2012 for Windows 8 and select New Project from the File menu. In the Visual C# or Visual Basic section, select Windows store and then select Blank app (XAML). Name the app ProximityConnect and click OK.

Open the Package.appxmanifest file and select the Capabilities tab. Select the Proximity capability to enable Proximity. Close and save the manifest file.

2. Add XAML UI

Open the MainPage.xaml file and replace the default Grid element with the following XAML.

<GridBackground="{StaticResource ApplicationPageBackgroundThemeBrush}"><StackPanelMargin="20"><StackPanelOrientation="Horizontal"><TextBlockFontSize="16"VerticalAlignment="Center"Margin="0,0,10,0">Display Name</TextBlock><TextBoxx:Name="DisplayNameTextBox"Width="300"/></StackPanel><StackPanelOrientation="Horizontal"><Buttonx:Name="AdvertiseForPeersButton"Content="Advertise For a Connection"Click="AdvertiseForPeersButton_Click"/><Buttonx:Name="AcceptConnectionButton"Content="Accept Connection"Click="AcceptConnectionButton_Click"/><Buttonx:Name="FindPeersButton"Content="Browse for Peers"Click="FindPeersButton_Click"/><Buttonx:Name="StopFindingPeersButton"Content="Stop Browsing for Peers"Click="StopFindingPeersButton_Click"/></StackPanel><StackPanelOrientation="Horizontal"><TextBoxx:Name="SendMessageTextBox"Width="300"Height="30"/><Buttonx:Name="SendMessageButton"Content="Send Message"Click="SendMessageButton_Click"/></StackPanel><TextBlockx:Name="MessageBlock"Width="600"HorizontalAlignment="Left"/></StackPanel></Grid>

3. Add click event handlers

In this step, you add the code for the click events of the XAML buttons, and a method for writing to the UI thread. The code in the event handler for the AdvertiseForPeersButton button sets the peer name for the local device and starts the PeerFinder. If triggered connections are supported (tapping), the code identifies the event handler for the TriggeredConnectionStateChanged event. In the TriggeredConnectionStateChanged event handler, the code opens a stream socket to send text messages between the peer apps.

The code in the event handler for the FindPeersButton button calls the FindAllPeersAsync method to browse for devices within wireless range. When one or more peers is found, the sample calls the ConnectAsync method to connect to the first peer found. This is for sample purposes only. You should present the user with a list of possible peers to choose from, and then connect to the peer that the user chooses.

The code includes an event handler for the ConnectionRequested event that occurs when a peer opens a connection with you by calling the ConnectAsync method. You can click the Accept Connection button to accept the connection.

The code in the event handler for the StopFindingPeersButton button calls the stop method to stop advertising and browsing for peers whether within wireless range or from a tap gesture.

In the MainPage.xaml.cs or MainPage.xaml.vb file, replace the default OnNavigatedTo event handler in the MainPage class with the following code.

4. Add the code to send and receive messages using the supplied StreamSocket

When a successful connection is made, the code passes the StreamSocket object that was created by the connection to the SendMessage function. The SendMessage function opens a network connection with the proximate device, which enables you to send messages back and forth. Be sure to always call the close method of the StreamSocket object when you are finished with it.

In the MainPage.xaml.cs or MainPage.xaml.vb file, add the following code after the SendMessageButton_Click method.

5. Add the code to activate the app on a peer from a tap

In the code that you added earlier to set up the connection methods and event handlers, you included code in the OnNavigatedTo event handler to complete a socket connection if the app is activated by a tap. In order for that code to function correctly, the launch event arguments must be passed to the main page when it is navigated to. This is done in the OnLaunched event handler, which runs when the app is activated.

Open the App.xaml.cs or App.xaml.vb file and replace the default OnLaunched method with the following.

6. Run the app

To see the app in action, run it on two devices that have Proximity enabled. Click the Advertise for a Connection button in both apps, and then tap the devices together. If you have two Windows devices with Wi-Fi Direct enabled on both devices, you can click the Browse for Peers button on one device to create the connection. If you have two phones and Bluetooth is enabled on both devices, you can also tap Browse for Peers on one phone to create the connection.

Important

This quickstart must be run on two devices. For scenarios that use a tap gesture, each device must have a Proximity device, such as a Near-Field Communication (NFC) radio, installed. For scenarios that use wireless browsing, you need two PCs with Wi-Fi Direct enabled, or two Windows Phones with Bluetooth enabled. If you don't have hardware that supports Proximity tapping, such as an NFC radio, you can use the Proximity driver sample that is part of the Windows Driver Kit (WDK) samples. You can use the sample driver to simulate a tap gesture over a network connection between two Windows devices. For information on how to download the WDK, see Windows Driver Kit (WDK). After you have installed the WDK and samples, you can find the Proximity driver sample in the src\nfp directory in the location where you installed the WDK samples. See the NetNfpProvider.html file in the src\nfp\net directory for instructions on building and running the simulator. After you start the simulator, it runs in the background while your Proximity app is running in the foreground. Your app must be in the foreground for the tap simulation to work.

Summary and next steps

In this tutorial, you created an app that uses a tap gesture or wireless browsing to connect devices.