This article lists the terms, structures, and APIs that are deprecated in Microsoft® Windows Mobile® 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.

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

Product Names

eMbedded Visual Basic

ADOCE

CEDB

Security

Outlook Mobile and Messaging

System Management

Networking

WISP

Accessing the Screen Buffer Through the GAME API

Internet Explorer Mobile

Web Server

RAPI Database Functions

Services

Conclusion

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.

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

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#.

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

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.

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).

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

Security Policy Settings

Security Functions

Security Structures

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

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

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

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

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.

// 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);

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

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

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.

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

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

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 not deprecated 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.

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

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.

Other Resources