ch14_The Remote API (RAPI).pdf

(139 KB) Pobierz
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
Chapter 14
The Remote API (RAPI)
The last chapter discussed Web Services, one option for connecting CF-based
devices to desktop (and server) systems. This chapter covers the Remote API, a second
option for making the device-to-desktop connection for devices that are connected using
ActiveSync. [Comment 21cs.1]
Using RAPI to Access Device Files ........................................................................................... 22
FindPrograms – Using RAPI to Find Files in the Device File System.................................... 24
FindProgramsFaster – Speeding up a File Search ................................................................ 29
Remote Access to Device Registry Entries ............................................................................... 34
Remote Access to Device Property Databases......................................................................... 43
Detecting Changes in Device Connection State ........................................................................... 46
The Auto-Start Method............................................................................................................... 46
The Callback Method ................................................................................................................. 47
Loading Programs and DLLs......................................................................................................... 52
Running Device-Side Programs................................................................................................. 52
Loading Device-Side DLLs ........................................................................................................53
Building a DLL Using Embedded Visual C++......................................................................... 55
Calling a DLL function with CeRapiInvoke ............................................................................. 57
Conclusion ..................................................................................................................................... 58
This chapter discusses the Remote API, an extension to the Win32 API on desktop
versions of Microsoft Windows. The RAPI functions provide a mechanism for code
running on the desktop to access Windows CE-powered devices which are connected to
the desktop via ActiveSync. Most of the RAPI functions involve accessing the object
store of a connected device, although there are a host of other functions that provide
some interesting ways to access a Windows CE system from a desktop system.
Chapter 14 – The Remote API Page 1
Copyright © 2003 Paul Yao & David Durant
Programming the .NET Compact Framework in C#
By Paul Yao & David Durant
Because RAPI is dependent on ActiveSync, it makes sense that we start this chapter
with an exploration of ActiveSync.
What Is ActiveSync?
ActiveSync is a desktop-oriented set of services for connecting a Windows CE
device to a desktop system running any recent version of Microsoft Windows (Microsoft
Windows 98 or later). The purpose of an ActiveSync connection is to (1) move data from
a device to a desktop system, (2) move data from a desktop system to a device,
(3) install an application, (4) de-install an application, or (5) allow the device to access a
network using the desktop computer's network card and ActiveSync's Pass Through
ActiveSync Pass Through
When ActiveSync 3.5 or later is on the desktop, a docked Pocket PC
2002 has access to ActiveSync Pass Through . Andreas Sjöström, of
Business Anyplace ( www.businessanyplace.net ) in Sweden, wrote an
article on this subject on Microsoft's Pocket PC site, which you can read:
From a development point of view, Andreas makes two key points about
what protocols Pass Through supports and which ones it does not.
In brief, Pass Through supports HTTP, HTTPS, IMAP and POP3. It does
not support UDP, ICMP, or PPTP. [Comment 21cs.4]
Kenny Goers suggests that FTP works well in the Pass Through layer as
well. Kenny is a developer at Magenic ( www.magenic.com ) , and the
moderator of the Yahoo Group where Paul Yao likes to hang out and offer
friendly advice and the occasional bad pun. For details on the list, browse
ActiveSync itself is installed on desktop systems, not on Windows CE devices.
Devices like the Pocket PC come packaged with a docking cradle that serves both as a
battery charger and also to provide the physical connection between a device and a
serial or USB connection. When a device is put into its docking cradle, ActiveSync
wakes up and establishes a connection. [Comment 21cs.6]
When you purchase a Pocket PC or other Windows CE-based device, you normally
also find a CD containing ActiveSync for installation on your desktop system. ActiveSync
is also available for download from the Microsoft web site
used to create connections to custom Windows CE based devices as well. [Comment
Table 14-1 ActiveSync sample programs in this chapter [Comment 21cs.8]
Name
Description
Simple RAPI program with startup and shutdown and no threads.
RapiStartup
FindPrograms
Searches device file system for *.exe files using CeFindFirstFile and
CeFindNextFile approach.
FindProgramsFaster
Faster program search sample using CeFindAllFiles .
Chapter 14 – The Remote API
Page 2
Copyright © 2003 Paul Yao & David Durant
870585253.023.png 870585253.024.png 870585253.025.png 870585253.026.png 870585253.001.png 870585253.002.png 870585253.003.png 870585253.004.png 870585253.005.png
 
Programming the .NET Compact Framework in C#
By Paul Yao & David Durant
Name
Description
FindProgramsOnConnect
FindProgramsFaster with IDCCMan connect detection to search for
program files automatically when a connection is detected.
RegShowStartup
Queries device registry to show programs and DLLs that are automatically
started at CE system cold boot.
ShowDatabases
Queries device for mounted property database volumes and property
databases.
YaoDurant.Win32.Rapi
Library containing P/Invoke wrappers for RAPI.DLL
SimpleBlockModeInvoke
Win32 DLL that demonstrates block mode call to CeRapiInvoke .
CallDeviceDll
Test program that calls SimpleBlockModeInvoke.dll
When a password has been established on a Windows CE device, ActiveSync asks
for a password before allowing access to a device. Windows CE devices support two
kinds of passwords: a simple four digit number, as well as a longer alphanumeric value.
Users set the password in the Windows CE Control Panel. [Comment 21cs.9]
ActiveSync treats a Pocket PC – or other Windows CE-powered devices – as a
remote peripheral. This represents a very different approach to Windows CE devices
from the other chapters in this book. For this reason, most of the code in this chapter
runs on the desktop and not on a device. Two sample programs run on a device, but
these are downloaded and run from a desktop program. This chapter's sample programs
are summarized in table 14-1. The C# versions are located on the book CD under the
\YaoDurant\CS\ActiveSync directory. You can find the VB versions under the
\YaoDurant\VB\ActiveSync directory. [Comment 21cs.10]
Partners And Guests
When a device connects to a desktop, ActiveSync determines whether the desktop
and the device have an established partnership. If so, ActiveSync performs a set of
synchronization tasks. If there is no partnership, the user can establish a partnership or
connect as a guest. Full synchronization services are only available to partner devices
and not to guests. [Comment 21cs.11]
Either partner or guest devices can do the following: [Comment 21cs.12]
1
Manual transfer of files between the desktop and the device using the
desktop Windows Explorer. [Comment 21cs.13]
2
Add or remove – that is, to install or de-install – programs [Comment
3
Back up and restore device data [Comment 21cs.15]
4
Connect to an intranet or the Internet using ActiveSync Pass Through
Devices with partnerships can do the following additional tasks:
1
Synchronize files. Files in specially marked folder get copied from the
device to the desktop, or from the desktop to the device depending on
which was more recently modified. [Comment 21cs.17]
2
Synchronize databases. When a partner device connects to a desktop
system, ActiveSync runs all active database synchronization. There are
several built-in database synchronization objects, including one for the
Pocket Outlook calendar, contact list, inbox, and task list. Applications
Chapter 14 – The Remote API
Page 3
Copyright © 2003 Paul Yao & David Durant
870585253.006.png 870585253.007.png 870585253.008.png 870585253.009.png 870585253.010.png 870585253.011.png 870585253.012.png 870585253.013.png 870585253.014.png 870585253.015.png
 
Programming the .NET Compact Framework in C#
By Paul Yao & David Durant
can also install custom database synchronization objects. [Comment
A device can establish a local connection to a desktop system using any of several
mechanisms: via USB port, serial port, Infrared (IrDA) port, or via Bluetooth. Once a
partnership has been established between a device and a desktop, remote connections
can be established using your choice of dial-up modem, a hard-wired network
connection, or a wireless Wi-Fi network connection. [Comment 21cs.19]
ActiveSync Limitations
Before digging into ActiveSync, we ought to point out its limitations: [Comment
1
ActiveSync only supports one active connection at a time. [Comment
2
ActiveSync cannot access the Windows CE emulator. [Comment 21cs.22]
3
ActiveSync does not synchronize between devices. [Comment 21cs.23]
4
ActiveSync does not synchronize with servers. [Comment 21cs.24]
One Active Connection
A given Windows CE device can have a partnership with at most two different
desktop systems. Desktop systems, on the other hand, can have partnerships with an
unlimited number of devices. ActiveSync itself, however, can only handle one device
connection at a time. Windows is multi-tasking, but ActiveSync is not. [Comment 21cs.25]
This makes ActiveSync suitable for some scenarios, and inappropriate for others.
ActiveSync works well when there is a 1:1 mapping between devices and desktops.
ActiveSync does not work as well with a many-to-one relationship between devices and
desktop systems. For example, if you have a large number of devices that leave in the
morning and come back in the evening, ActiveSync is probably not your best choice. It is
for this reason that Microsoft SQL Server CE, a database that runs on Windows CE,
does not use ActiveSync for its device-to-database connectivity. Because it does not rely
on ActiveSync, SQL Server CE allows multiple Windows CE device to simultaneously
synchronize with a single central database server. [Comment 21cs.26]
No Emulator Support
The lack of emulator support means that to build and run ActiveSync applications,
you must have an actual Windows CE device. If you plan to spend any time working on
ActiveSync code, we suggest you make the investment in a network card for your
Windows CE device. The reason is simple: network hardware is relatively inexpensive,
and it allows for much faster development and debugging. In fact, this suggestion is not
just limited to ActiveSync development – but for all your device-side development and
testing. Network download and debugging – whether by wired network or wireless – is
just plain faster than serial or USB port connections. [Comment 21cs.27]
No Synchronization Between Devices
ActiveSync is not a general purpose synchronization mechanism, but is specifically
designed to connected devices with desktop – and not with any desktop, but desktops
running Microsoft Windows 98 and later. Supported versions of Microsoft Windows
include Windows 98, Windows Me, Windows NT (Service Pack 6), Windows 2000,
Windows XP, and the .NET Server. [Comment 21cs.28]
NOTE
ActiveSync Backup and Restore
Chapter 14 – The Remote API
Page 4
Copyright © 2003 Paul Yao & David Durant
Programming the .NET Compact Framework in C#
By Paul Yao & David Durant
While ActiveSync does not provide support for synchronizing between
devices, it does allow you to backup the object store from one device,
and restore to another Windows CE device. The end result is two
identical devices. For users of Windows CE-based devices, this ability to
backup and restore can help safeguard against data loss when a device is
lost or damaged. [Comment 21cs.29]
No Synchronization with Servers
ActiveSync does not synchronize Windows CE devices with servers. There are,
however, server-side systems that communicate with Windows CE-powered devices.
These are summarized in the accompanying sidebar, Connecting Devices to Servers . Those
server side systems do not use ActiveSync, but rather support direct connections to
devices through TCP/IP. [Comment 21cs.30]
ActiveSync Compared to Web Services
Since ActiveSync and Web Services both support desktop-to-device connectivity,
you might at this point wonder how they compare. Both provide Remote Procedure Call
(RPC) support; however ActiveSync is a more specialized form of RPC while Web
Services provide a more general purpose type of RPC. [Comment 21cs.31]
ActiveSync differs from Web Services in that the locus of control for a web service is
at the client – it is, after all, the device that calls the web service. With ActiveSync, on the
other hand, the locus of control is on the desktop as that is where your code primarily
ActiveSync is a desktop-oriented programming interface, which provides a very
simple remote procedure call mechanism for accessing the object store of a Windows
CE device. Use it when your usage scenario involves having a home base for a roaming
device. The home base – the desktop system – provides the place to install software
and synchronize data. [Comment 21cs.33]
Web services, on the other hand, are a general purpose remote procedure call
(RPC) mechanism that allows a device to access a standard (meaning here the SOAP /
XML / HTTP-based standards) web service. You will likely use web services to call out to
third-party services to fetch phone numbers, the weather, travel information, etc.
For the most part, then, the uses of ActiveSync and Web Services are separate and
distinct – use ActiveSync to "phone home", and Web Services to "call out." The only real
overlap is when you implement Web Services on the PC where a Windows CE device
has a partnership. In that case, the decision factor comes down to whether you want to
implement something that is device-driven or desktop-driven. For device-driven
operations, implement a Web Service; for desktop-driven operations, use ActiveSync.
ActiveSync Programming Interfaces
ActiveSync provides a set of Win32 functions and COM interfaces to support its
various services. This chapter focuses on the Remote API (RAPI) and on the Device
Connection Manager. Table 14-2 shows these two, along with other ActiveSync function
sets that are available for your use. [Comment 21cs.36]
Table 14-2 ActiveSync Application Programming Interfaces [Comment 21cs.37]
ActiveSync API
Description
Build Files
Runtime Files
Remote API
A set of 78 C-callable functions for accessing the
RAPI.H
RAPI.DLL
Chapter 14 – The Remote API
Page 5
Copyright © 2003 Paul Yao & David Durant
870585253.016.png 870585253.017.png 870585253.018.png 870585253.019.png 870585253.020.png 870585253.021.png 870585253.022.png
 

Plik z chomika:

Inne pliki z tego folderu:

Inne foldery tego chomika:

Zgłoś jeśli naruszono regulamin