The WINC Win32 utilities

WINC is an implementation of the non-GUI parts of Symbian OS. Its chief purpose is to allow Symbian OS application engines to be used to access application documents from programs running on a PC.

WINC is a specialist implementation of Symbian OS. The primary requirements for WINC were:

• allow Symbian OS application engines to be run from ordinary Win32 application programs in order to access application document files

• allow any drive and directory on the PC's filing system to be accessed through the WINC File Server API — not just the emulated virtual drives as under WINS

The difference between WINS and ARMI is a complete rebuild. However, WINC DLLs run in the same processor architecture as WINS DLLs, and therefore a complete rebuild is not necessary. In fact, only the DLLs delivered by the Base are different from their WINS counterparts. In other cases, the WINC component is exactly the same as the corresponding WINS component. In general, with the exceptions mentioned, any DLL implemented under WINC should be exactly the same as its WINS counterpart without code change or rebuilding.

WINC components are found in ..\epoc32\release\winc\variant\, corresponding to the ..\epoc32\release\wins\variant\ directories used for WINS.

The following sections list the APIs that are supported for use by programs under WINC. Each table contains a brief description of the component, including any distinctive WINC behaviour; the library that offers the API; and a link to further description for the API.

The implementation of these components differs between WINC and WINS. The APIs, however, are identical.

The implementation of the kernel server and executive also differ in WINC from WINS.

The full APIs of the following engine support components may be used:

The full APIs of the application engines are available. This enables WINC programs to use these engines to write, read or modify Symbian OS application documents.

Under WINC, graphical display is not supported. A Windows program using WINC DLLs is responsible for its own graphical display. It does provide though support for the manipulation of bitmaps in files and in memory, and some very limited support for printing.

A number of other components are included in the winc\udeb and winc\urel directories. APIs to these components are not currently published. In some cases the components are not for use by external developers.

WINC performs no drive mapping. This allows programs invoked from WINC to access any drive and directory on the PC's file system, just like any other Win32 program.

All file server sessions have a default directory of c:\. This implies that filename arguments cannot be passed, as with most Win32 programs, with paths that are evaluated relative to the current directory at the time the program was invoked. Instead, filename arguments must use absolute filenames.

Since WINC makes much re-use of WINS, it is easiest to understand the process of building WINC programs by reference to that of building WINS programs.

As for WINS, the process is:

• compose a .mmp file to specify the project

• run makmake to generate either a .winc command-line make file, or a Microsoft Visual C++ project file.

• for command-line builds, run nmake to build using the command-line makefile

• for interactive development, open the workspace in the Microsoft Visual C++ debugger, and iteratively edit, compile and debug the program

The form of a WINC makefile is precisely the same as that for a WINS makefile. Any options specified in the makefile for the WINS platform will also be applied to WINC.

If you are re-using a DLL which has already been built for WINS, the process is even simpler: essentially, you copy the DLL from \epoc32\release\wins\variant\ into \epoc32\release\winc\variant\.

Like the WINS and ARMI platforms, WINC provides a text console that implements the interface defined by CConsoleBase. The difference is that the console accessed through this class is a standard Win32 console window.

The console is the primary user interface for command-line utilities. The console supports redirection of output (stdout) to file and international keyboard input.

A WINC command-line utility needs a main program which is a .exe. As with other .exes in Symbian OS, control is received through the E32Main() function which takes no arguments. Therefore, to parse command line arguments, you need to access the command line arguments using a Symbian OS API. The CCommandLineArguments class is the most convenient way to do this.

Delivering and running a command-line utility requires care: see the following topic "Running and delivering programs".

Full Windows GUI applications are Windows programs, rather than re-built Symbian OS programs.

Windows GUI applications make use of DLLs built and tested under WINC. However, such DLLs are built into Windows GUI applications using the tools provided by Microsoft Visual C++, rather than by using Symbian’s own tools.

Symbian OS window server and components dependent on it cannot be used to draw graphics under Windows.

As in WINS, device-level code may require the use of Win32 libraries directly. Use the win32_library statement in the .mmp file, just as you would under WINS.

Under WINC, the following macros are defined by the build tools:

These macros may be used in order to control conditional compilation. Note that the __WINS__ macro is always defined for WINC programs, in addition to the __WINC__ macro.

UIDs are usually irrelevant under WINC. However, the same scheme as used in WINS may also be used in WINC.

WINC programs are built into ..\epoc32\release\winc\variant\. For development and testing, they may be run from there.

It is inadvisable, however, to include a WINC build directory in your path, as many developers also include \epoc32\release\wins\variant\ in their path, which contains many of the same DLLs, or different DLLs with the same name. Therefore, WINC programs must usually be invoked by specifying the full path name, rather than just the filename of the .exe. Usually, it is most convenient to do this using a batch file, like this:

@echo off
\epoc32\release\winc\deb\almain.exe

Sometimes, the batch file may be used to pre-process arguments. This is often necessary, because WINC requires absolute paths for its filename arguments rather than relative ones.