Controlling Devices with the Smart Device Connectivity API

Smart Device Development

Microsoft Visual Studio includes the Smart Device Connectivity APIs that enable developers to take advantage of some core connectivity features in applications. Core connectivity is a communications framework used by products such as Microsoft Visual Studio, Microsoft Visual Studio Remote Tools, and Microsoft Platform Builder to deploy files, start processes, flash devices, and debug applications on smart devices.

Typically, the Smart Device Connectivity API is used to write applications such as Remote Tools for Device Projects. The benefit is that developers focus more on programming logic because details about how to connect to and manage devices are abstracted away. The Smart Device Connectivity APIs enable the following tasks:

List platforms and devices available.
Establish a connection between a local desktop computer and a target device.
Deploy applications, packages, and files to a target device.
Start, stop, and enumerate processes on a target device.
Exchange data between the desktop and target device.

Using the Smart Device Connectivity APIs, you can write remote tools and automate device management tasks.

Typical Architecture of Smart Device Connectivity Applications

The best way to understand the Smart Device Connectivity API is to run through a typical desktop application that uses the Smart Device Connectivity API.

To use the Microsoft.SmartDevice.Connectivity namespace, the desktop application adds a reference to drive:\Program Files\Common Files\Microsoft Shared\CoreCon\1.0\Bin\Microsoft.Smartdevice.Connectivity.dll.
The application creates a DatastoreManager and uses it to enumerate a collection of Platform objects. Each Platform represents a platform, such as Windows Mobile 5.0 Pocket PC, that is installed in the desktop computer's Datastore.
The application uses a Platform to enumerate a collection of Device objects. Each Device represents one of the devices or emulators, such as Windows Mobile 5.0 Pocket PC emulator, that belongs to the platform.
The application uses Device to access information about the device, provision the device, and connect to the device.
After connection to the device, the application uses FileDeployer to deploy files to the device or RemoteProcess to start or stop processes on the device.

If the application must perform custom tasks that are not available in FileDeployer, RemoteProcess, or Device, it can create a RemoteAgent to deploy a device agent to the device and exchange data with it. A device agent is a smart device application that you author and that uses either the Microsoft.SmartDevice.DeviceAgentTransport namespace (for Visual C# or Visual Basic device agents) or the DeviceAgentTransport.dll library (Visual C++ device agents). In order to be deployed by a RemoteAgent, a device agent must be registered in the desktop computer's Datastore as an add-on package. For more information, see Overview of Add-on Packages. The application performs the following steps to deploy and communicate with a device agent:

The desktop application calls RemoteAgent..::.Start to deploy and start the device agent.
After the device agent is running on the device, it calls IDeviceAgentTransport..::.AcknowledgeLaunch to acknowledge the connection.
The device agent calls IDeviceAgentTransport..::.AcceptConnectionEx to accept a packet stream request from the desktop.
The desktop application calls RemoteAgent..::.CreatePacketStream to obtain a DevicePacketStream for data transfer.
From there, the remote application and device agent exchange data by reading and writing Packet or IPacket objects to their respective device packet streams.

The device agent has full programmatic access to gather information and manipulate the device because it runs on the device.

Note:
The device agent described earlier in this topic uses Microsoft.SmartDevice.DeviceAgentTransport and the .NET Compact Framework. Alternatively, you can create unmanaged device agents by using the Unmanaged Device-Side Smart Device Connectivity API.

For a step by step guide on how to create this kind of application, see Walkthrough: Exchanging Data between Desktop and Device Applications.

Files and Namespaces in the Smart Device Connectivity API

The Smart Device Connectivity API consists of:

The Microsoft.SmartDevice.Connectivity namespace for use in desktop applications. (drive:\Program Files\Common Files\Microsoft Shared\CoreCon\1.0\Bin\Microsoft.Smartdevice.Connectivity.dll).
The Microsoft.SmartDevice.DeviceAgentTransport namespace for creating Visual C# or Visual Basic device agent applications. (drive:\Program Files\Common Files\Microsoft Shared\CoreCon\1.0\Target\Microsoft.Smartdevice.DeviceAgentTransport.dll).
Unmanaged Device-Side Smart Device Connectivity API for creating Visual C++ device agent applications. (drive:\Program Files\Common Files\Microsoft Shared\CoreCon\1.0\Target\wce400\cpu\DeviceAgentTransport.dll)

What is the Datastore?

The Datastore is a set of XML files on your desktop computer that contains information about the platforms, devices, emulators, and packages that are installed on the computer. The datastore is part of core connectivity and is installed with Microsoft Visual Studio or Microsoft Platform Builder. The contents of the Datastore are modified whenever you install an SDK that is based on Windows CE such as Windows Mobile.

The Datastore is located in drive:\Users\All Users\Microsoft\corecon\1.0 (Windows Vista) or drive:\Documents and Settings\All Users\Application Data\Microsoft\corecon\1.0 (Windows XP).

Note:
Backup the datastore before modifying any files in the datastore folder. Malformed files will corrupt the datastore and Visual Studio will not function.

You should only modify the addons folder in the datastore. For more information, see Overview of Add-on Packages.

Other Resources

Smart Device Connectivity API Samples