Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
4/7/2010

Jim Wilson, JW Hedgehog, Inc

July 2007

Summary

This article lists the terms, structures, and APIs that are deprecated in Windows Mobile Version 5.0 and Windows Mobile 6, and therefore will not be available in the next major release of Windows Mobile. You should not use any of these terms, structures, or APIs in new applications or documentation; they should also be removed from any existing applications or documentation. This article provides suggestions for the appropriate replacements for these terms, structures, and APIs; when available, the suggested replacements include links to additional resources that you may find helpful.

Applies To

Windows Mobile 6 Professional

Windows Mobile 6 Standard

Windows Mobile 6 Classic

Windows Mobile 5.0 for Pocket PC Phone Edition

Windows Mobile 5.0 for Smartphone

Windows Mobile 5.0 for Pocket PC

Introduction

Windows Mobile provides developers with a rich application platform compatible with the desktop computer's Win32® platform, while consuming only a fraction of the memory and other resources required by the desktop platform. Maintaining the richness and compatibility of the Windows Mobile platform while remaining so resource efficient has always been a core goal of each new Windows Mobile release. Achieving this goal requires thorough planning, hard work, and sometimes difficult decisions.

As new features are added to Windows Mobile and as Windows Mobile achieves greater compatibility with the desktop platform, new APIs and structures are added—sometimes duplicating or even consolidating features provided by existing Windows Mobile structures and APIs. As nice as it would be to keep every existing structure and API available for the benefit of existing applications, maintaining these redundant structures and APIs slows the development of new Windows Mobile versions and will ultimately lead to Windows Mobile becoming a bloated platform. To avoid these issues, the decision must sometimes be made to deprecate and eventually remove some redundant structures and APIs.

Starting with Windows Mobile 5.0 and continuing with Windows Mobile 6, several Windows Mobile structures and APIs have been deprecated. This article provides a list of these deprecated structures and APIs, along with a few documentation terms that are also deprecated. In each case an alternative structure, API, or term is provided. As much as possible, a reference to an available resource that provides additional information is also included. This paper groups deprecated structures, APIs, and terms by the technology to which they apply.

The structures and APIs listed in this article will not be available in the next major release of Windows Mobile (the version following Windows Mobile 6). You should not use any of the structures or APIs listed in this document for any new application development. You should also remove these structures and APIs from any existing applications that you plan to support on the next major release of Windows Mobile. Similarly, any new documentation should not use the deprecated terms listed in this article, and existing documentation should be updated to replace the deprecated terms with the appropriate replacement term.

Product Names

To better identify the features of each Windows Mobile device and to better align the brand and products with the reality of today's mobile device marketplace, Windows Mobile 6 introduced new naming conventions for Windows Mobile devices. The historical form-factor based distinction between Smartphone and Pocket PC Phone Edition is blurring dramatically, and the goal is to update terminology to evolve to better reflect the evolution of the mobile device industry.

The new product names help to show how each product relates to one another and also helps to avoid confusion created by the term smart phone, which has historically referred to a specific Windows Mobile device but has a much broader meaning when used in general. Table 1 shows the relationship between the old and new Windows Mobile product names.

Table 1. Relationship between old and new Windows Mobile product names

Old Name New Name

Windows Mobile for Pocket PC

Windows Mobile 6 Classic

Windows Mobile for Pocket PC Phone Edition

Windows Mobile 6 Professional

Windows Mobile for Smartphone

Windows Mobile 6 Standard

eMbedded Visual Basic

Starting with Windows Mobile 2003, all Windows Mobile devices include the .NET Compact Framework in ROM. The .NET Compact Framework is a powerful application execution environment providing far more features and capabilities than the eMbedded Microsoft Visual Basic® execution environment. Using Visual Basic .NET, developers familiar with eMbedded Visual Basic can leverage their existing skills to take advantage of the .NET Compact Framework environment to create rich Windows Mobile applications. Visual Basic .NET combined with Microsoft Visual Studio® allows developers who create desktop applications using Visual Basic .NET and Visual Studio to immediately leverage their existing skills to create Windows Mobile applications.

Because of the clear advantage that Visual Basic .NET provides over eMbedded Visual Basic, eMbedded Visual Basic is deprecated. Developers should immediately discontinue their use of eMbedded Visual Basic. No new applications should be developed with eMbedded Visual Basic and any existing eMbedded Visual Basic applications should be converted to one of the languages that the .NET Compact Framework supports: Visual Basic .NET or C#.

ADOCE

The ADO.NET database API provides managed developers with an easy-to-use, high-level database API; the SQL Server™ Compact Edition OLE DB provider provides native developers with a lightweight, low-level database API. With these options available and eMbedded Visual Basic deprecated, the ADOCE database API is no longer needed and is therefore deprecated as well. The specific ADOCE API replacement depends on your application development language. Table 2 shows the appropriate database API for each language.

Table 2. Deprecated service-related functions and IOCTL messages

Application Development Language Database API

Visual Basic .NET, C#

Developers developing applications with either of these languages should use the .NET Compact Framework's SQL Server Compact Edition ADO.NET provider. For more information see the System.Data.SqlServerCe Namespace Overview and Building Managed Applications (SQL Server Compact Edition)

C++

Developers developing applications with C++, who prefer a relational database, have large data volumes, or need built-in data synchronization support should use the SQL Server Compact Edition OLE DB provider. For more information see SQL Server Compact Edition OLE DB Provider Reference , SQL Server Compact Edition Native Programming , and Building Native Applications (SQL Server Compact Edition) .

Developers developing applications in C++, who prefer a simple, API-based (no query language) database solution, who are working with small data volumes, and do not need built-in data synchronization support can use the EDB database API. For more information, see EDB Database Support .

All Windows Mobile 6 devices include both SQL Server 2005 Compact Edition and .NET Compact Framework 2.0 SP2 in ROM. This gives you a relational database that is immediately available along with both the SQL Server Compact Edition ADO.NET provider and SQL Server Compact Edition OLE DB provider without installing any additional software on the device.

SQL Server 2005 Compact Edition includes built-in data synchronization support that allows you to easily synchronize your mobile device data with a server or desktop computer. Developers who need to synchronize with a server should see Merge Replication and Remote Data Access for more information. Developers who need to synchronize with a Microsoft Access™ database on a desktop computer should see Access Database Synchronizer .

CEDB

The EDB embedded database provides a lightweight storage engine that takes advantage of the SQL Server Compact Edition storage subsystem and provides significantly improved performance over CEDB, especially when dealing with flash memory. EDB incorporates many of the same features as CEDB and adds some significant new features such as the following:

  • Transactions

  • Schemas to define the database structure

  • Improved sort order support

  • Support for data stream types

  • Multi-process and Multi-thread access

Because of the many improvements that EDB provides over CEDB, CEDB is now deprecated in favor of EDB. No new applications should be written using CEDB and any existing applications should be ported to EDB. To simplify porting your applications from CEDB to EDB, EDB provides an API that is very similar to CEDB. For more information on EDB, see EDB Database Support . For more information on porting from CEDB to EDB, see Porting Applications from CEDB to EDB (note: this is a Word document).

Security

There are a few changes in the area of security, all of which are relatively simple. These changes include new security terminology, new security policy settings, new security structures, and new security functions. The change in security terminology is being made to simplify security discussions. The changes in policy settings provide more fine-grained control. The new structure and functions improve compatibility with desktop computers by replacing Windows Mobile–specific functions that duplicate desktop functionality with the desktop functions.

Security Terms

To simplify security documentation and improve consistency, the two security terms Untrusted and Unprivileged are now deprecated. They are replaced by the term Normal. For example, documentation that would have formerly referred to an unprivileged application now refers to that application as an application with normal privilege. For more information, see Windows Mobile Powered Device Security Model .

Security Policy Settings

To provide more fine-grained control over individual security policies, the security policy settings SECPOLICY_WAPSIGNEDMSG and SECPOLICY_USEENCRYPT, each of which affect multiple security policies, are now deprecated in favor of security policy settings that set each security policy individually. Table 3 shows the replacement security policy settings. See Security Policy Settings for more information on the individual security policy settings.

Table 3. Deprecated security policy settings and their replacements

Deprecated Setting Replacement Setting

SECPOLICY_WAPSIGNEDMSG (4107)

Use the SECPOLICY_OMACPNETWPINMSG (4141) security policy setting to set the security policy for whether the OMA network PIN signed message will be accepted.

SECPOLICY_WAPSIGNEDMSG (4107)

Use the SECPOLICY_OMACPUSERPINMSG (4142) security policy setting to set the security policy for whether the OMA user PIN or user MAC signed message will be accepted.

SECPOLICY_WAPSIGNEDMSG (4107)

Use the SECPOLICY_OMACPUSERNETWPINMSG (4143) security policy setting to set the security policy for whether the OMA user network PIN signed message will be accepted.

SECPOLICY_USEENCRYPT (4126)

Use the SECPOLICY_SMIMEENCRYPTION (4138) security policy setting to set the security policy for whether the Inbox application will send all messages encrypted.

SECPOLICY_USEENCRYPT (4126)

Use the SECPOLICY_SMIMEENCRYPTIONALGORITHM (4140) security policy setting to set the security policy for which algorithm to use to encrypt a message.

Security Functions

The functions listed in Table 4 are Windows Mobile–specific functions that duplicate functionality provided by desktop computer security functions. To improve compatibility with the desktop, these Windows Mobile–specific functions are deprecated in favor of the corresponding functions that are available on both the Windows Mobile and desktop platforms.

Table 4. Deprecated security functions and their replacements

Deprecated Function Desktop Compatible Function

CeCredRead

CredRead

CeCredWrite

CredWrite

CeCredFree

CredFree

Security Structures

As part of the above change in the security functions, the Windows Mobile–specific security structure Credential is now deprecated and is replaced by the desktop compatible Cred security structure. The Cred structure is used by the CredRead, CredWrite, and CredFree functions along with other related security functions. For easy reference, the deprecated Credential structure and its replacement, Cred, are shown in Table 5.

Table 5. Deprecated security functions and their replacements

Deprecated Structure Replacement Structure

Credential

Cred

Outlook Mobile and Messaging

As the features of Microsoft Office Outlook® Mobile and the Windows Mobile messaging system continue to evolve, it is important that the APIs become more consistent and avoid duplicating functionality. This evolution continues to bring the features of Outlook Mobile and the Windows Mobile messaging system more in line with the features of desktop computers. For these reasons, some functions that duplicate other Windows Mobile messaging features or duplicate desktop computer messaging features have been deprecated. See table 6 for these functions and their replacements.

Table 6. Deprecated security functions and their replacements

Deprecated Function Replacement

HrGetOneProp

Use the IMAPIProp::GetProps method to retrieve all MAPI property values whether retrieving one property or multiple.

HrSetOneProp

Use the IMAPIProp::SetProps method to set all MAPI property values whether setting one property or multiple.

CePimCommand

Use the IContextMenu interface to add commands to the Outlook Mobile Tools menu. The IContextMenu interface is the standard way to add menu items to the shell and therefore allows you to leverage a single set of skills whether modifying menus in Outlook Mobile or the Windows Mobile shell.

SmsReadMessage

Use the IMailRuleClient interface to read SMS messages. The IMailRuleClient interface provides an easy-to-use mechanism for receiving notifications of newly arrived SMS messages and for reading those messages.

System Management

There are a few deprecated general system management and interaction functions. For the most part, these deprecated functions have a direct one-to-one replacement by another function. There are however three functions and one control message that have no replacements because changes to the Windows Mobile platform make their functionality unnecessary.

Table 7 shows the deprecated functions and their replacements; Table 8 shows the deprecated functions that are no longer needed.

Table 7. Deprecated system management functions and their replacements

Deprecated Function Replacement

CreateFileForMapping

Use CreateFile to open and create memory mapped files.

GetStoreInformation

Use GetDiskFreeSpaceEx to get disk size and available space information.

RegisterDevice

Use ActivateDeviceEx to load a driver.

DeregisterDevice

Use DeactivateDevice to unload a driver.

Table 8. Deprecated system management functions that are no longer needed

Deprecated Function Description

BatteryNotifyOfTimeChange

It is no longer necessary to call this function because the SetSystemTime and SetLocalTime functions notify the battery driver directly to update its timing state values.

PFN_KEYBD_EVENT_CALLBACK

PFN_KEYBD_EVENT_CALLBACKEx

The Graphics, Windows, and Events subsystem (GWES) no longer passes these callback functions to the keyboard driver's PFN_KEYBD_DRIVER_INITIALIZE function because the callbacks are no longer necessary. Instead of relying on the driver callbacks, the GWES now receives notification of keyboard-related events from the Layout Manager, which sends the event notifications to the GWES using the keybd_event function.

IOCTL_POWER_QUERY

This control message is not called by the Power Manager.

Networking

Computer networks have changed tremendously in recent years. No longer is a device limited to a single network address. Windows Mobile devices commonly have two, three, or more network adapters each with their own address. In addition, network addressing is steadily evolving from IPv4 to IPv6. To work effectively in this new network environment, Windows Mobile is deprecating some of the older network functions in favor of new functions that provide more complete network information. Table 9 shows the deprecated functions and their replacements.

Table 9. Deprecated networking APIs and their replacements

Deprecated Function Replacement

Gethostbyname

You should now call the getaddrinfo function to retrieve the address information corresponding to a host name. When resolving a host name to an address, the getaddrinfo function allows you to specify additional criteria such as the service name or port number so as to more accurately resolve the corresponding host address. The getaddrinfo function returns complete address information for all network addresses meeting the specified criteria.

gethostbyaddr

You should now call the getnameinfo function to retrieve the host name that corresponds to a particular network address. Given a host address and port number, the getnameinfo function will return the corresponding host name and service name.

GetAdaptersInfo

To retrieve the list of network adapters for the current device, you should now call the GetAdaptersAddresses function. The GetAdaptersAddresses function allows you to specify whether you would like the IPv4 addresses, IPv6 addresses, or both; you can also specify that certain types of addresses not be returned such as multicast or unicast addresses. The GetAdaptersAddresses function returns all network addresses meeting the specified criteria.

WISP

To reduce redundancy and provide a more consistent API, the WISP API has deprecated the IInkStrokes::ToString function. Deprecating this function also maintains compatibility with the Tablet PC version of WISP. In most cases, calls to the IInkStrokes::ToString function can be replaced with a call to the IInkStrokes::get_RecognitionResult function to retrieve the recognition result, followed by a call to the IInkRecognitionResult::TopString function to get the translated text as shown here.

Copy Code 
// Code assumes that pInkStrokes is a valid reference to a 
//  IInkStrokes interface
BSTR bstrResultText;
IInkRecognitionResult *pRecognitionResult = null;
pInkStrokes->get_RecognitionResult(&pRecognitionResult);
pRecognitionResult->get_TopString(&bstrResultText);

Accessing the Screen Buffer Through the GAME API

Gaming is a popular activity on cell phones. Many new Windows Mobile devices now incorporate hardware such as high-quality displays, fast processors, and hardware accelerated three-dimensional graphics that are able to provide a better gaming experience than ever before. Historically, most games targeting the Windows Mobile platform have used the Game API (GAPI).

GAPI provides only the most basic graphics features. It gives you direct, exclusive access to the video frame buffer (for compatibility with older games, sometimes the API returns a shadow buffer). GAPI provides no basic two-dimensional or three-dimensional drawing abilities and therefore relies heavily on GDI drawing capabilities. GDI provides basic two-dimensional drawing features such as lines, curves, text, and bitmaps; however, GDI does not provide three-dimensional drawing features. As a result, all three-dimensional drawing must be done in software.

Due to the improved performance, the rich feature set, and desktop compatibility of Microsoft DirectDraw® and Microsoft Direct3D® Mobile, GAPI is now deprecated in favor of these APIs. DirectDraw provides powerful, two-dimensional drawing capabilities; Direct3D Mobile provides powerful three-dimensional drawing capabilities. Both APIs are hardware independent while taking full advantage of available hardware acceleration. DirectDraw and Direct3D Mobile are compatible subsets of the DirectDraw and Direct3D APIs on the desktop allowing desktop developers to take advantage of their existing skills and code to produce Windows Mobile games. Direct3D Mobile offers both a managed and native API.

For more information on DirectDraw and Direct3D Mobile, see DirectDraw Application Development and Direct3D Mobile Application Development .

Gaming Input

The one caveat to deprecating GAPI is gaming input. At the time of this writing, Windows Mobile does not offer an alternative to the direct input control that GAPI provides. For now you must continue to use GAPI for direct input control. As soon as an alternative to GAPI direct input control is available, an updated version of this article will provide the appropriate information.

Internet Explorer Mobile

Microsoft Internet Explorer® Mobile is a powerful, highly programmable Web browser offering many of the same programmability features as the desktop version of Internet Explorer including basic AJAX support. To improve application compatibility between Internet Explorer Mobile and Internet Explorer, Windows Mobile has deprecated several interfaces and a markup element in favor of desktop compatible versions that offer additional features. Table 10 shows the deprecated interfaces and markup element.

Table 10. Deprecated Internet Explorer Mobile interfaces and markup element, and their replacements

Deprecated Interface/Element Replacement Interface/Element

IBrowser, IBrowser2, IBrowser3

IWebBrowser2

_DPIEWebBrowserEvents2

DWebBrowserEvents2

<Applet> element

<Object> element

Web Server

To improve compatibility with the server-based version of Internet Information Services (IIS), the Windows Mobile Web server is deprecating ISAPI filters that rely on raw data notifications and the HSE_REQ_SEND_RESPONSE_HEADER structure.

Applications that use ISAPI filters that rely on raw data notification are now deprecated. These applications should instead use ISAPI extensions to process and generate data to and from the Web server. As a result, the following event notification types should no longer be used:

  • SF_NOTIFY_READ_RAW_DATA

  • SF_NOTIFY_SEND_RESPONSE

The HSE_REQ_SEND_RESPONSE_HEADER is now deprecated. Instead you should use the HSE_REQ_SEND_RESPONSE_HEADER_EX structure to send HTTP response headers. The HSE_REQ_SEND_RESPONSE_HEADER_EX structure provides duplicate functionality but does so more efficiently. The HSE_REQ_SEND_RESPONSE_HEADER_EX structure also adds features that are not supported by HSE_REQ_SEND_RESPONSE_HEADER, such as the capability for your application to optionally append additional headers to the response.

RAPI Database Functions

The Windows Mobile Remote API (RAPI) functions that you use to manage Windows Mobile EDB databases include a number of functions that provide duplicate functionality. The original version of these functions accepts only the database ID, which is not guaranteed to be unique across volumes. The newer extended versions of these APIs accept the volume ID, which when combined with the database ID uniquely identifies each database. To simplify the API and reduce redundancy, all of the functions that do not accept the volume ID are now deprecated. Table 11 lists the deprecated COM-based functions and their replacements. Table 12 lists the deprecated C-style functions and their replacements.

Table 11. Deprecated COM-based RAPI file system database functions

Deprecated Function Replacement Function

IRAPISession::CeCreateDatabase

IRAPISession::CeCreateDatabaseEx

IRAPISession::CeDeleteDatabase

IRAPISession::CeDeleteDatabaseEx

IRAPISession::CeFindFirstDatabase

IRAPISession::CeFindFirstDatabaseEx

IRAPISession::CeFindNextDatabase

IRAPISession::CeFindNextDatabaseEx

IRAPISession::CeOidGetInfo

IRAPISession::CeOidGetInfoEx

IRAPISession::CeOpenDatabase

IRAPISession::CeOpenDatabaseEx

IRAPISession::CeReadRecordProps

IRAPISession::CeReadRecordPropsEx

IRAPISession::CeSetDatabaseInfo

IRAPISession::CeSetDatabaseInfoEx

Table 12. Deprecated C-style RAPI file system database functions

Deprecated Function Replacement Function

CeCreateDatabase (RAPI)

CeCreateDatabaseEx (RAPI)

CeDeleteDatabase (RAPI)

CeDeleteDatabaseEx (RAPI)

CeFindFirstDatabase (RAPI)

CeFindFirstDatabaseEx (RAPI)

CeFindNextDatabase (RAPI)

CeFindNextDatabaseEx (RAPI)

CeOidGetInfo (RAPI)

CeOidGetInfoEx (RAPI)

CeOpenDatabase (RAPI)

CeOpenDatabaseEx (RAPI)

CeReadRecordProps (RAPI)

CeReadRecordPropsEx (RAPI)

CeSetDatabaseInfo (RAPI)

CeSetDatabaseInfoEx (RAPI)
Note:
Developers who are still using the C-style RAPI to access a Windows Mobile device from a desktop computer may want to consider migrating to the COM-based RAPI (also known as RAPI 2). The C-based API is notdeprecated but is limited to accessing only a single connected device. Although Windows Mobile does not currently support multiple concurrently connected devices, developers who use the COM-based RAPI will be prepared to access multiple concurrently connected Windows Mobile devices should this feature be added in the future.

Services

To simplify interacting with services, Windows Mobile is reducing the number of service-specific functions and IOCTL messages and replacing them with more general functions that provide the same functionality. Table 13 shows the deprecated functions and IOCTL messages along with their corresponding replacement functions.

Table 13 Deprecated service-related functions and IOCTL messages

Deprecated Function or IOCTL Message Replacement Function

GetServiceHandle

You should now call the CreateFile function to retrieve a service handle. When calling the CreateFile function, pass the service prefix and index value. See Controlling a Running Service for more information and an example.

ServiceIoControl

To control a service you should now use the CreateFile function to retrieve the service handle and then call the DeviceIoControl function to send the control message. The DeviceIoControl function accepts the same parameters as the ServiceIoControl function.

IOCTL_SERVICE_UNLOAD

To unload a service, you should now call the DeregisterService function.

Conclusion

Reducing redundancy and improving compatibility with the desktop platform provides many benefits. Reducing redundancy helps to maintain the resource efficiency of Windows Mobile and helps to simplify Windows Mobile programming by keeping the APIs as concise as reasonably possible; reduced redundancy also avoids the confusion created by duplicated functionality. The improved compatibility with the desktop allows you to work effectively on both platforms with a common set of skills, which reduces development time and training costs.

There is no question that removing APIs from Windows Mobile will affect some applications. Although it may not feel like it at the time that you're updating your applications, these changes do help to make Windows Mobile a better platform in the long run and help us to deliver increasingly powerful applications leveraging one core set of skills.

See Also

Jim Wilson is president of JW Hedgehog, Inc. (http://www.jwhh.com) a New Hampshire–based consulting firm specializing in solutions, content creation, and mentoring for the Windows Mobile platform. Jim has worked extensively with the .NET Framework and .NET Compact Framework since the original beta release of each; he has over 20 years experience in the software industry including more than 14 years experience with relational database programming including SQL Server and SQL Server Compact Edition. Jim writes frequently for MSDN and has developed mobility curriculums for two of the industry’s leading technology training organizations, DevelopMentor and PluralSight. Jim speaks regularly at Tech Ed, the Professional Developer's Conference (PDC), VSLive, and the Mobility & Embedded DevCon. You'll find Jim online at http://pluralsight.com/blogs/jimw.