#ifndef DOXYGEN_SKIP
/* $Id$ */
#endif /* DOXYGEN_SKIP */

/*!
\page wince GDAL for Windows CE

\section wince_overview Overview

This document is devoted to give some overview of the GDAL port for Windows CE operating system. The OGR port is the first attempt to get GDAL library working on Windows CE.

\section wince_status Current Status

Currently, only vector data support is available in form of OGR library port for Windows CE. Next milestone will be to port raster data features to make Windows CE port of GDAL more complete.

List of GDAL features ported to Windows CE:
<ul>
    <li>\link cpl_port.h CPL\endlink library</li>
<li>Base OGR API </li>
<li>Subset of OGR data drivers (ogr\ogrsf_frmts):
    <ul>
	<li>Generic</li>
	<li><a href="ogr/drv_mitab.html">Mitab</a></li>
	<li><a href="ogr/drv_shapefile.html">Shape</a></li>
    </ul>
</li>
<li><a href="http://sourceforge.net/projects/wcelibcex/">WCELibCEx</a> - extensions for C library available on Windows CE operating system<br />This is a separate project derived from the work made on GDAL port for Windows CE.</li>
</ul>

List of features not included in the GDAL port for Windows CE:
<ul>
    <li>Raster data support</li>
    <li><a href="http://geos.refractions.net">GEOS</a> has not been ported yet, so OGR for Windows CE compiles without GEOS support (work in progress)</li>
    <li><a href="ogr/ogr_formats.html">OGR drivers</a> not listed in the features list above</li>
</ul>

\section wince_platforms Supported Platforms

GDAL port for Windows CE has been tested on Windows Mobile for Pocket PC 2003 operating system (see \ref wince_wince). It is based on Windows CE 4.2 .NET version. There should be no problems with running it on systems based on latest Windows CE 5.0.

The GDAL port was tested with following compiler for Windows CE devices (see \ref wince_msvc):
<ul>
    <li>Microsoft eMbedded Visual C++ 4.0 (SP 4)</li>
    <li>Microsoft Visual C++ 2005</li>
</ul>

\subsection wince_wince About Windows CE

<a href="http://www.microsoft.com/windows/embedded/default.mspx">Windows CE</a> is one of two embedded operating systems create by Microsoft. The second is <a href="http://msdn.microsoft.com/embedded/windowsxpembedded/default.aspx">Windows XP Embedded</a>. The GDAL port is dedicated to the first one - Windows CE system. It may work on Windows XP Embedded as well but I have not tested it. (If you're interested in differences between those two systems, look at the <a href="http://www.embeddedtechnologyjournal.com/articles_2005/20051004_msft.htm">Comparing Windows CE and Windows XP Embedded</a> by Mike Hall.)

So, remember, in order use GDAL port you will need a mobile device running Windows CE.

Now, a few words about Windows CE and derived systems versions.
Usually, users are quite confused about all those different versions of Windows CE and derived systems. In fact, the idea is quite simple.
Windows CE is a name of base operating system and can be seen as equivalent of Windows NT for Windows on desktop. All desktop versions like Windows 2000 or XP are still Windows NT systems.
Windows CE is highly modular system and can be used as a base operating system by everyone who wants to build his own system. Microsoft provides a few officially configured versions and called them Windows Mobile. Now, you have a few versions of Windows Mobile:
<ul>
    <li>Windows Mobile for Pocket PC</li>
    <li>Windows Mobile for Smartphone</li>
</ul>

All those Windows CE derived systems are still Windows CE. So, GDAL port for Windows CE should work on all of them without any problems.

As I said, I tested GDAL port on Windows CE 4.2. That means it will work on:
<ul>
    <li>Windows Mobile 2003</li>
    <li>Windows Mobile 2003 Second Edition</li>
</ul>

It's also expected to work on latest Windows Mobile 5.0.

For better understanding of versions of Windows CE, please take a look at these web sites:
<ul>
    <li><a href="http://channel9.msdn.com/wiki/default.aspx/Channel9.WindowsMobileFeedback">What's the Windows Mobile platform?</a></li>
    <li><a href="http://en.wikipedia.org/wiki/Image:Windows_CE_Timeline.png">Windows CE Timeline</a></li>
</ul>

\subsection wince_msvc About Visual C++ IDE

First, if you have not decided which tool you need, take a look at this <a href="http://blogs.msdn.com/windowsmobile/archive/2005/06/02/424382.aspx">Windows Mobile Tool Support Matrix</a>.

Microsoft eMbedded Visual C++ 4.0 (eVC++ 4.0) is available free of charge and can be downloaded from following <a href="http://www.microsoft.com/downloads/details.aspx?familyid=1DACDB3D-50D1-41B2-A107-FA75AE960856&displaylang=en">download</a> website. Also, remember to <a href="http://www.microsoft.com/downloads/details.aspx?familyid=4a4ed1f4-91d3-4dbe-986e-a812984318e5&displaylang=en">download</a> and install latest Service Pack (currently, it's SP4).

Recently, Microsoft included C++ compiler for mobile devices into the \em big Visual C++ compiler, starting from 2005 (8.0) version. So, it seems there will be no new releases of eVC++.
In order to use GDAL port for Windows CE with <a href="http://msdn.microsoft.com/visualc/">Visual C++ 2005</a> compiler you will need the Standard Edition or higher because Express Edition does not provide support for Windows CE mobile devices. For more details see this <a href="http://msdn.microsoft.com/vstudio/products/compare/default.aspx">comparison</a>.

\section wince_howto Getting Started

This section explains how to build GDAL for Windows CE as a library. There are not much details about how to use it but it should not be a problem. As explained above, for now, GDAL for Windows CE includes OGR features only, so in order to use it just follow instructions from the <a href="ogr/ogr_apitut.html">OGR API Tutorial</a>. To help you to make the start easier, there are a few test applications based on this tutorial, so try to build and run them. If new features will be added in future, like rasters support, this section will be updated as well.

\subsection wince_howto_get Downloading GDAL port sources

GDAL port for Windows CE is available from the official CVS repository. Follow instructions in CVS section on the <a href="http://www.gdal.org/download.html#download_sources_cvs">GDAL download page</a>.

After you checkout GDAL sources, you will get also <em>gdal\wince</em> directory. This directory consists of all files related to Window CE port.

Now, the first thing you should do is to read <em>gdal/wince/README</em> file. There you will find all details about content of <em>gdal/wince</em> directory and building instructions.

\subsection wince_howto_build_evc4 Building GDAL port using eVC++ and makefiles

<ol>
    <li>Open command line (cmd.exe) on your Windows box and go to GDAL sources directory. In example to:

    \code
    C:\gdal
    \endcode
    </li>

    <li>Run configuration script for ARM target. It's default location is:

    \code
    C:\Program Files\Microsoft eMbedded C++ 4.0\EVC\wce420\bin\WCEARMV4.BAT
    \endcode

    Now, runs some commands to check if everything is configured well: 

    \code
    C:\gdal> clarm.exe /?
    Microsoft (R) C/C++ Optimizing Compiler Version 12.20.9615 for ARM
    Copyright (C) Microsoft Corp 1984-2002. All rights reserved.

    C:\gdal> echo %PLATFORM%
    POCKET PC 2003
    
    C:\gdal> echo %OSVERSION%
    WCE420
    \endcode
    </li>
    <li>Build GDAL library:<br />
    
    \code
    C:\gdal> nmake /f makefile.evc4
    \endcode
    </li>

    <li>If everything went without any errors you should have following files in gdal root directory (C:\gdal):
        <ul>
	<li>gdalce.lib - static library (PREFERED)</li>
	<li>gdalce13.dll - Dynamic-Link Library (DLL) (See IMPORTANT note)</li>
	<li>gdalce_i.exp - export file for DLL</li>
	<li>gdalce_i.lib - import library for DLL</li>
	</ul>
    </li>

    \note Currently \em gdalce13.dll built with NMake seems to be broken. So, if you want to use GDAL for Windows CE as a DLL please use eVC++ 4.0 project file from \em evc4_gdalce_dll directory at the moment. This issue is known and waiting for fix :-)

\subsection wince_howto_build_evc4_proj Building GDAL port using eVC++ project files

The easiest way is to build GDAL port for Windows CE using Visual C++ project files. There are two project files available in the <em>gdal/wince</em> directory:
<ul>
    <li>evc4_gdalce_lib - project file for eMbedded Visual C++ 4.0 to build GDAL port for Windows CE as a static library</li>
    <li>evc4_gdalce_dll - project file for eMbedded Visual C++ 4.0 to build GDAL port for Windows CE as a DLL</li>
</ul>

So, just open workspace file (\em .vcw) you want to use in the eVC++ IDE and build it.

\note There are also some project files and test applications provided. Look into the <em>gdal/wince/README</em> file for details.

\subsection wince_howto_build_vc2005_proj Building GDAL port using VC++ 2005 project file

Recently, I also added project file to build GDAL for Windows CE using Visual C++ 2005. This project file is available in the <em>gdal/wince/msvc8_gdalce_lib</em> directory. Sibling test project is available in the <em>gdal/wince/msvc8_gdalce_lib_test</em>.

\section wince_help How can I help?

I'd like to encourage everyone interested in using GDAL on Windows CE devices to help in its development.
Here is a list of what you can do as a contribution to the project:
<ul>
    <li>You can build GDAL for Windows CE and report problems if you will meet any</li>
    <li>You can try to build new OGR drivers</li>
    <li>You can test GDAL/OGR on different Windows CE devices</li>
    <li>You can write sample applications using GDAL/OGR and announce them on the <a href="http://lists.maptools.org/mailman/listinfo/gdal-dev/">GDAL mailing list</a></li>
    <li>If you have found a bug or something is not working on the Windows CE, please report it on the <a href="http://bugzilla.remotesensing.org">GDAL's Bugzilla</a>
</ul>

There is also <em>gdal/wince/TODO</em> file where you can find list of things we are going to do.

If you have any comments or questions, please sent them to the gdal-dev@lists.maptools.org mailing list or directly to me on mateusz@loskot.net .

*/