This chapter describes the step-by-step process of creating and building VxDCOM applications using Tornado. To more easily create VxDCOM applications, the basic VxDCOM support includes the following tools:

Lets you easily generate skeleton code for a basic VxDCOM application, without having to define CoClasses and interfaces in IDL (the Interface Definition Language).

Facilitates writing client and server implementation code.

Compiles IDL file, generating the necessary proxy/stub and header files required by VxDCOM.

For a detailed description of the VxDCOM technology, see the VxWorks Programmer's Guide: VxDCOM Applications.

VxDCOM clients and servers for VxWorks can be created either as bootable or downloadable applications. The following step-by-step overview summarizes the VxDCOM development process:

Whether you choose to create a bootable or downloadable client or server, you need a VxWorks bootable image that contains a kernel and VxDCOM support. You need such an image for all VxDCOM applications.

If you are creating a bootable application, add your VxDCOM application files to the bootable system image. If you are creating a downloadable application, add your VxDCOM files to this downloadable module. Then download that module to the bootable system containing the VxDCOM support.

After you have created the kernel, add the appropriate VxDCOM support components. Some components are required for all VxDCOM applications, some are required only for DCOM, and some are optional, providing additional functionality. This section describes VxDCOM support and when to add it to your kernel.

If your application includes DCOM, you can optionally configure parameters for this component. Change the parameter values from within the project facility by selecting Properties from the popup menu on the appropriate binary component.

The DCOM parameter descriptions, their default values, and the value ranges are described in VxWorks Programmer's Guide: VxDCOM Applications.

The VxDCOM Wizard lets you generate a completely new VxDCOM project, or import an existing COM or DCOM server. To run the wizard, type at the command line:

% installDir/host/hostType/bin/torVars.bat  
% comwizard projDir 

where the projDir is the directory for your project. The files generated by the wizard are generated in this directory. The directory name you type in is the default name for your CoClass for new projects. You have an option to modify this name in the wizard.

The first page of the VxDCOM wizard, shown in Figure 11-1,lets you choose the project type. The options are:

Create skeleton files for a new COM or DCOM component. For details, see Creating a COM/DCOM Skeleton Project on p. 376.

Create a project using existing COM application code. For details, see Importing Existing Files into a New Project on p. 381.

Choose the type of project and click Next.

If you are creating a new project, you simply specify your server type and implementation language, and define your CoClass and interfaces using the wizard GUI. You do not have to write then in IDL (Interface Definition Language); nor do you have to write proxy/stub code.

From the information you enter, the wizard generates the primary IDL definition file and the additional files appropriate to the server model and client program selected. These output files are described in The Generated Output on p. 383.

Figure 11-2 shows the CoClass Input dialog of the wizard. From this dialog you define the CoClass by adding interface methods and parameters. This dialog defaults to a CoClass named for the argument you passed to comwizard.

You can modify the name of the CoClass (or any items), by highlighting the item and choosing Edit.

To define the CoClass, you add interfaces and interface methods, and you specify parameter types for those methods. You typically do this in steps:

• Add one or more interfaces to the CoClass.

• For each interface, add one or more methods.

• For each method, add one or more parameters, specifying the attribute and type of each.

When your CoClass definition is complete, click Next.

Figure 11-5:   Method Parameter Data Types

It is also possible to use non-automation types, however these are not available from the VxDCOM wizard dialog and may require additional linking. If you need to use non-automation data types, see the Adding Non-Automation Types.

The widl tool compiles both automation data types and non-automation data types. The types compiled by widl are listed in the VxWorks Programmer's Guide: VxDCOM Applications.

Once your CoClass definition is complete, clicking Next displays the CoClass Options dialog of the wizard, shown in Figure 11-6. From this dialog you specify the CoClass server model, implementation language, and any optional client programs. Then click Next.

The last dialog of the wizard, Project Creation, appears. Simply click Finish to generate your project.

If you have an existing COM application, choose the option to Import existing files into new Project and choose Next. This brings up the Import Existing Project dialog shown in Figure 11-7.

The files to add are the .idl file, the server implementation file, and the CoClass header file.

If you wish to edit your .idl file by hand, you can refer to the VxWorks Programmer's Guide for details on the IDL file structure and the correct syntax for defining elements in that file. Remember to specify an HRESULT as the return type for all interface methods and to use automation data-types and directional attributes appropriately for your interface parameters.

If you do not use automation data types, refer to Adding Non-Automation Types below. As a guide for writing in these files you can use the wizard GUI dialogs and wizard generated IDL files, and the CoMathDemo.idl file.

If for any reason you need to add additional interface definitions manually to the auto-generated .idl file, for each additional interface you must:

• Generate a new GUID (you can use the UUIDGEN utility to do this).

• Specify this value as the [uuid] attribute of your interface.

If you are using non-automation data types, the simplest way to add them is to generate all of the simple automation data types for the interface first using the wizard, generate the skeleton code. Then edit the .idl file and server implementation file by hand, adding the interface methods that could not be added with the wizard because they use non-automation types.

If you are defining interface methods that use non-automation types, you would not use the [oleautomation] attribute in your interface definition.

For more information on IDL, see the Microsoft documentation. Be aware that some of that information applies only to RPC interfaces and not to COM interfaces.

The wizard generates output files in several subdirectories of your project name directory referred to here as basename. The content of those directories differs depending upon the options you selected in the wizard.

When the wizard finishes running it generates output files and creates 2 directories, which are:

• basename

• basename/Client

Subsequent sections describe the additional files that appear in these two directories. Depending upon the type of server and client you selected in the wizard, the content of these directories differs.

These are the primary files to identify for working with your project. You can use these files to write code, compile, edit, or browse. Some are used for compiling, linking, building, and deployment of your application.

The makefile used for building the project from the command line. Using this file is the default method for building the downloadable module. For details, see 11.7 Building and Linking the Application.

This is the IDL file, identified by the .idl extension. This file is automatically compiled by widl when you build your Tornado project.

This is the CoClass implementation file for your server, identified by the Impl.cpp extension. This is the file in which you implement the interface methods of your server CoClass.

This is the CoClass header file, identified by the Impl.h extension. This file contains definitions and prototypes generated from the items you defined in the wizard.

This is the skeleton implementation file for your client if you choose COM as your server and client model. It is identified by the Client.cpp extension. You edit this file to add client code to activate the COM server.

This is the skeleton implementation file for your DCOM client application. It is identified by the DCOMClient.cpp extension. You edit this file to add client code to activate the DCOM server.

This is the registry-script file, identified by the .rgs extension. This file is used by the VxDCOM build tools to register the CoClass after it has been built. It is generated only when the DCOM server is selected. You only need to edit this file if you are writing a DCOM application, in which case you modify the `vxworks.target' entry.

This is the host-side (client) makefile, always generated as nmakefile. It is used (with nmake) to build the MFC client application for Win32 or for VxWorks.

The COM and DCOM server files differ only in the proxy stub code file used for marshaling.

If you selected more than one client program with your server choice, then all files necessary for each client are output into the basename/Client directory. Remember that, for DCOM server projects, the basename/Client directory also contains the basename.rgs file. However, this file is only used by DCOM clients to register the type library.

Once your system is created, you are ready to implement your CoClass methods for the server component and write the code for any client programs.

• COM server code in the implementation file basenameImpl.cpp, located in your project directory.

• COM client code in the implementation files, which are either basenameClient.cpp for a C++ COM client, or basenameDCOMClient.cpp for a C++ DCOM client. The client implementation files are located in the /Client subdirectory of your project directory.

The VxWorks Programmer's Guide: VxDCOM Applications describes this process. That chapter includes a reference for WOTL, the C++ template library used to write VxDCOM applications. It also covers the topics of using real-time extensions, adding OPC interfaces, working with HRESULT return values, and details of the SAFEARRAY types supported under VxDCOM.

Add the appropriate files, generated by the wizard, to your project. These files include the implementation code for the server and client. If you are creating a bootable application, add the files to the bootable system image. If you are creating a downloadable application, add the files to a downloadable module, ensuring that the module is downloaded to a bootable system containing the required VxDCOM support for you application.

Then, build the project. Although you can use the project facility from the IDE to build, the recommended method is to use the wizard-generated Makefile from the command line. The generated Makefile automatically runs widl. If you are building from the project facility, you must run widl manually. Running widl generates the proxy/stub code, the identification GUIDs, and the interface header prototypes. The build process also links the proxy/stub code.

This section describes registering proxy DLLs, the type library, and the server, authenticating and activating the server.

If your project uses non-automation types, you must register the proxy DLLs on Windows.

Typically, when you define your interface you use automation data types. These are the types you can select from the VxDCOM wizard for your interface method parameters. When you use these types, the parameters are defined by the [oleautomation] attribute, to indicate that they are automation types. This signals to the Win32 Automation Marshaler that no extra Win32 proxy/stub DLLs are required because the marshaling of these types is handled automatically.

However, if your project requires non-automation types then you cannot specify the [oleautomation] attribute nor automate the marshaling of the parameter types. For interfaces that use non-automation types, you must generate and install your own Win32 proxy/stub DLLs. The DLL containing the interface proxy must be distributed with all client applications that use that new interface.

The specific non-automation types that widl can compile are described in the VxWorks Programmer's Guide: VxDCOM Applications.

The details of generating Win32 proxy/stub DLLs is outside of the scope of this document. Please refer to the Win32SDK MIDL documentation for details.

The type library is a binary file with a .tlb extension, that stores information about a DCOM object's properties and methods in a form that is accessible to other applications at run time. Windows' client applications use a type library to determine which interfaces an object supports and how to invoke the interface methods. For this reason, the type library must be registered. To register the type library, run installDir\host\x86-win32\bin\vxreg32.exe. This command adds the type library to the Windows Registry at its current location, so that the object can be accessed from the Windows host. If you add interfaces to the IDL file, the type library must also be re-registered so that the interface becomes known to the Windows Automation Marshaler.

The registry will contain an entry called `vxworks.target' that needs to be modified to point to the actual target, so that it is available from, for example, Visual Basic. There are two ways to change the target machine entry and register the type library:

• Edit the basename.rgs file (generated by the wizard) by changing the `vxworks.target' entry to the target IP address, and then run vxreg32 as described above.

• Run vxreg32 first, and then change the Windows registry entry for the target by opening up DCOMCNFG and using that tool to change the location.

You must register your DCOM server classes in the VxWorks COM registry, so that client applications can locate them. There is one server-class per object-module. The object-module contains the server-class code, the proxy/stub code, and a registration object. This registration object registers the server-class with the VxWorks Registry when its constructor runs, guaranteeing that modules are automatically registered, regardless of whether they are pre-linked or downloaded. This auto-registration process does not rely on constructor ordering and can, thus, be safely performed at any point during system initialization.

To automatically register a DCOM server at load time or system startup, include the AUTOREGISTER_COCLASS macro in the CoClass implementation file. This will create an entry for the class in the VxWorks COM registry. AUTOREGISTER_COCLASS associates the CoClass with its CLSID, and registers the module name in the VxRegistry against its CLSID.

This macro is automatically included when the skeleton implementation file is generated. Thus, you do not need to add the macro code yourself (unless you work with files that were not auto-generated.)

The AUTOREGISTER_COCLASS macro takes three arguments: the server implementation CoClass, priority-scheme, and the default priority. The priority parameters are used as part of the real-time extension priority schemes, and are discussed in the VxWorks AE Programmer's Guide: Writing COM and DCOM Clients and Servers.

The DCOM registry under VxWorks is not the complex, multi-purpose registry that Win32 supports, but is designed specifically for that purpose of:

• Allowing COM server classes to register their CLSIDs (class-IDs).

• Providing a link to an instantiation procedure, given that CLSID.

• Determining the correct proxy/stub configuration for any given interface, given its IID (unique identifier).

Therefore, the VxWorks registry works on a simple associative lookup method, keyed by the interface and class identifiers. The value that can be stored in the registry-entry is simply a string, which is used by various internal functions to look up proxy/stub classes, system-provided objects (such as the standard marshaler), and other objects identified by these values.

VxWorks also exposes non-Win32-compliant API calls to provide access to this registry. However, user/application code does not need to use these APIs, since widl automatically generates the code for registration of server-classes.

VxDCOM can participate in the basic NTLM authentication procedures when acting as a server, but not as a client. It can recognize incoming authentication requests from NT and correctly take part in the challenge/response transaction, but by default will not take any action based upon those transactions. Future versions of VxDCOM may more fully support the NTLM security system depending upon NT domain security, network trusts, and so on. However, for now the safest and most predictable approach is to disable client-side security by using either the registry/DCOMCNFG tool or by calling CoInitializeSecurity( ).

After you have completed these steps you can run your program. See the VxWorks Programmer's Guide: VxDCOM Applications for descriptions of the MathDemo program client code, which activates the demo server component.

All VxDCOM threads must be created with VX_FP_TASK.