View source for Windows SDK

==Target Makefile==

The SDK makefile provides targets for building the [[Runtime Reference|STRIDE Runtime]] library and two executable applications - a strideDaemon (for a [[#Multiprocess_Application_Integration|multiprocess]] application environment), and an installTestApp (for running the STRIDE installation tests - see [[Verifying_Installation#Using_a_Platform_SDK|Using a Platform SDK]] for more information).

The default make target builds the STRIDE Runtime library and the strideDaemon executable. When a single process runtime library is specified (see RTSINGLEPROC below), the strideDaemon is omitted. To build the installation test application, specify the '''installtest''' make target. 

The '''installtest''' target compiles SCL source markup present in the Runtime source and therefore requires that the [[Build Tools]] be installed on your system and in your executable search path.

===Configuration===

The behavior of the makefile can be affected by setting certain make variable parameters. For example, the following make invocation will change the value of the TOOLCHAIN and DEBUG variables when making:

  make TOOLCHAIN=arm DEBUG=1

The following variable are intended to be specified or overridden as needed:

====TOOLCHAIN====

The default compiler toolchain when TOOLCHAIN is set to '''x86''' which assumes a WinMobile x86 version of cl/link/lib to be in your path. For any other TOOLCHAIN value, the toolchain compiler is cl$(TOOLCHAIN) where $(TOOLCHAIN) is replaced by the specified TOOLCHAIN setting. If your toolchain does not fit this pattern, you will need to modify the makefile or explicitly override values for CC, CPP, LINK, and AR.

====LIBRARYTYPE====

The default behavior of the makefile is to build the STRIDE Runtime as a dynamic library. If you prefer a static library, set this value to '.lib'.

====DEBUG====

The default configuration compiles with optimization and NDEBUG defined.  If you prefer debuggable binaries, set this value to 1.

====RTSINGLEPROC====

The default configuration compiles the runtime library with multiprocess support.  If you don't want (or can't support) multiprocess functionality, you can disable this by explicitly setting this value to 1.

====STANDALONE_INSTALLTEST====

The default configuration, set to '''0''', builds the installTestApp as a [[#Multiprocess_Application_Integration|multiprocess]] application. When set to '''1''' the installTestApp is built as a [[#Standalone_Application_Integration|standalone]] application. <br>
The STANDALONE_INSTALLTEST variable is affected by the value of RTSINGLEPROC. If RTSINGLEPROC is '''1''' and STANDALONE_INSTALLTEST is '''0''', this is an invalid combination and STANDALONE_INSTALLTEST will automatically be set to '''1'''.

====S2SCOPTS====

The STRIDE build process that produces the database and [[Intercept Module]] for the installation tests relies on target settings. These settings are passed as options to the stride compiler and are most conveniently stored in an options file.  We provide a default options file with target settings that are appropriate for x86 Windows targets with Microsoft compilers -- this file is ''SDK\WinMobile\settings\stride.s2scompile'' in the SDK distribution. 

We recommend that you make a copy of this file and adjust the settings as appropriate for your target. You can then set this variable - '''S2SCOPTS''' to the path to your settings file.  This will cause the make process to use the specified target settings options instead of the default one provided in the SDK. This same settings file should ultimately be used for the STRIDE build integration with your application source code.

===S2 Build Flags===
The target Makefile sets the following Build Tool flags:

  S2_BIND_FLAGS = --starting_suid=7000
  S2_IM_FLAGS = --disable_access_class

The [[S2sbind#Options|s2sbind]] and [[S2sinstrument#Options|s2sinstrument]] flags are combined so that the test application only registers for test message IDs that are created in a higher range so that it doesn't conflict with other application processes.

==Target API (stride.h)==

The WinMobile SDK provides a simplified application interface for initializing the STRIDE subsystem and starting STRIDE messaging and IM threads. The API includes the following routines:

===srBOOL strideInit(const strideIO_t * io)===

This function initializes the STRIDE subsystem.  The IO configuration is passed in as an argument. If this argument is NULL, then the process will attempt to attach to an already running runtime application (daemon) using shared memory for IPC. THis function should only be called once per application.

===srBOOL strideUninit(void)===

Terminates any threads that have been started with this API and uninitializes the STRIDE subsystem.

===srBOOL strideCreateThread(strideThreadFunc_t entry, const srCHAR * name)===

Creates a thread to be managed by the STRIDE subsystem. Threads created using this routine will be sent a palSTOP_EVENT notification (available from palWait) and should respond promptly to this event. The name parameter is used primarily for logging purposes.

===strideCreateIMThread(name)===

This is a macro that wraps the invocation of [[#strideCreateThread|strideCreateThread]] for intercept module entry point functions. Only the IM name must be provided.

===void strideExWaitForExit(void)===

This function can be called by the main application thread to block until the application is shutdown. 

This function is optional - if you create the application's message loop do not call this function.

===void strideExSetupMainWindow(const char* name, void* instance, int showCmd)===

This function is called by applications to create the main window of the process. The first argument specifies a name of the window. The second argument specifies the handle to the current instance of the application. And the third specifies how the window is to be shown.

This function is optional - if you create the application's main window do not call this function.

==Target Integration==

Here are a few examples of how to integrate the stride API into your application.

'''Note:''' the following code assumes that the intercept module was generated with a name of ''myintercept''.  Change all references to that name in your code to the chosen intercept module name.

===Standalone Application Integration===

The following code demonstrates how to integrate your application with the STRIDE Runtime. Your application might require other logic at startup - you can integrate the following calls according to your needs. Note that this code initializes the STRIDE subsystem and assumes a single standalone process that creates the STRIDE system threads as well as application threads. 

<source lang="c">
#include <windows.h>
#include <stride.h>
#include <myinterceptIMEntry.h>

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPWSTR lpCmdLine, int nShowCmd)
{
    strideExSetupMainWindow("MyApp", hInstance, nShowCmd);
    strideIO_t io = {strideDEFAULT};
    if (strideInit(&io) != srTRUE)
        return -1;

    if (strideCreateIMThread(myintercept) != srTRUE)
        return -1;

    strideExWaitForExit();
    strideUninit();
    return 0;   
}
</source>

===Multiprocess Application Integration===

This code demonstrates how to integrate your application with the STRIDE Runtime in multiprocess mode. In this mode, the pre-packaged strideDaemon runs simultaneously with the application and provides the STRIDE IO and runtime thread initialization. The host communicates with the application process through the strideDaemon (or another STRIDE IO process). In this sample, the only difference with the preceding sample is the call to strideInit which, in this case, specifies no IO parameters which indicates to the API that the communication and runtime threads should not be started.   

<source lang="c">
#include <windows.h>
#include <stride.h>
#include <myinterceptIMEntry.h>

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPWSTR lpCmdLine, int nShowCmd)
{
    strideExSetupMainWindow("MyApp", hInstance, nShowCmd);
    if (strideInit(NULL) != srTRUE)
        return -1;

    if (strideCreateIMThread(myintercept) != srTRUE)
        return -1;

    strideExWaitForExit();
    strideUninit();
    return 0;   
}
</source>

==Windows PAL==

===PAL Configuration (palcfg.h)===
The following parameters can be configured in ''palcfg.h'' to effect the behavior of the compiled pal source files.

; PAL_USE_SERIAL_TRANSPORT : if defined, serial communication support is enabled.
; PAL_USE_TCPIP_TRANSPORT : if defined, sockets-based communication support is enabled.
; PAL_DEFAULT_DEVICE_NAME : default IO device to use.
; PAL_DEFAULT_TCP_PORT : default port for TCP communication.
; PAL_DEFAULT_SERIAL_PORT : default COM port to use for serial communication.
; PAL_DEFAULT_SERIAL_BAUDRATE : default baud rate for serial communication.
; PAL_DEFAULT_SERIAL_MODE : default data/parity/stop settings for serial communication.
; PAL_MAX_THREADS : max STRIDE integrated threads that can be managed by the STRIDE API.
; PAL_MAX_TIMERS : max STRIDE timers that can be active in the system.

[[Category: SDKs]]