FILE: HELSVC.EXE Implements an OLE Server in a Service

ID: Q156673

The information in this article applies to:

Microsoft OLE Libraries, used with:
- Microsoft Windows NT 4.0
- Microsoft Windows 2000

SUMMARY

The HELSVC sample is a simple OLE Automation server implemented in a service called "Hello OLE Server Service."

The following file is available for download from the Microsoft Download Center. Click the file name below to download the file:

Helsvc.exe

For more information about how to download files from the Microsoft Download Center, please visit the Download Center at the following Web address

http://www.microsoft.com/downloads/search.asp

and then click How to use the Microsoft Download Center.

MORE INFORMATION

This server implements one application object with a dual interface. It also registers the application object in the RunningObjectTable so that any client can access it. The sample includes a Visual Basic client that can control the server. The sample does not use any framework such as MFC, ATL, etc.

Implementation Notes

NT 4.0 removes the limitations of using OLE in services that are described in the following article in the Microsoft Knowledge Base:

Q149571 Using OLE in Services in Windows NT 3.51

For an overview of implementing an OLE server in a service in NT 4.0 and later versions, read the following topics in the Win32 SDK Online documentation:

"LocalService"
"Installing as a Win32 Service or User Account"

To find these topics, query using the LocalService keyword.

When the service starts, it registers a multiple-use class factory. It then registers an object in the Running Object Table using ROTFLAGS_ALLOWANYCLIENT, which allows clients in any security context to bind to the object using IRunningObjectTable::GetObject or GetActiveObject (if the appropriate permissions are specified in the server's access permissions using the DCOMCNFG tool).

If ROTFLAGS_ALLOWANYCLIENT is not used in the ROT registration, only clients in the same security context as the server will be able to bind to it. RegisterActiveObject currently does not support ROTFLAGS_ALLOWANYCLIENT, so the sample provides a new function, MyRegisterActiveObject, which supports this flag.

IRunningObjectTable::Register supports this flag. Registration using this flag requires a registry entry similar to the following to prevent a CO_E_WRONG_SERVER_IDENTITY error:


   [HKEY_CLASSES_ROOT\APPID\helloservice.exe]
   "APPID"="{0bf52b15-8cab-11cf-8572-00aa00c006cf}"

Because of a bug in NT 4.0, Build 1381, registration using ROTFLAGS_ALLOWCLIENT is always weak, even if ROTFLAGS_REGISTRATIONKEEPSALIVE is also specified. As a consequence, the ROT will release its reference on the object when the last client releases its reference and clients that are launched later will not be able to bind to the running object. A workaround is for the server to place a strong lock on the registered object using CoLockObjectExternal while it is in the ROT.

NOTE: The bug mentioned in the paragraph above has been fixed in NT 4.0, Service Pack 2.

See the .reg file for information of the registry entries used by the service.

Many services are debugged by running them as console applications in the interactive user's identity. For example, this sample service can be debugged by running it as follows:

helloservice -debug

Because the service is already registered to run in a different identity (configurable by the Services control panel applet), OLE will fail CoRegisterClassObject and IRunningObjectTable::Register(ROTFLAGS_ALLOWANYCLIENT) by returning CO_E_WRONG_SERVER_IDENTITY to enforce security and to prevent malicious servers from spoofing the server. To debug by running in the interactive user's identity, make the following changes in the server's registry entries to prevent these failures:

To prevent CoRegisterClassObject failure, remove the following named value:


   [HKEY_CLASSES_ROOT\APPID\{0bf52b15-8cab-11cf-8572-00aa00c006cf}]
   LocalService"="HelloOleServerService"

To prevent IRunningObjectTable::Register(ROTFLAGS_ALLOWANYCLIENT) failure, do the following:

Remove the following named value:
```
   [HKEY_CLASSES_ROOT\APPID\{0bf52b15-8cab-11cf-8572-00aa00c006cf}]
   "LocalService"="HelloOleServerService" 
```
and then add the following named value:
```
   [HKEY_CLASSES_ROOT\APPID\{0bf52b15-8cab-11cf-8572-00aa00c006cf}]
   "RunAs"="Interactive User" 
```
Make sure that you restore the modified registry entries after debugging.

To Compile

NT 4.0 or later is required. To compile, type:

nmake

To compile a version without debug information and without message boxes that are displayed to indicate progress or failure, type:

nmake DEBUG=0

To Run

Change hello.reg to provide the full path of helloservice.tlb.

Type helloservice -install to install the service.

NOTE: This will not run the service.

Add INTERACTIVE to the DefaultAccessPermissions using the DCOMCNFG.EXE tool in the NT system32 directory. Make sure that INTERACTIVE is included in the DefaultLaunchPermissions. This allows the Visual Basic client in the interactive user's security context to access the service.

Use the Visual Basic file, vb.vbp, to control the object. Press the CoCreateInstance button to launch the service if required, and to create the object. Use the GetObject button to bind to a running object. GetObject can be used only if the service is already running. Use the GetMessage and SetMessage buttons to access the HelloMessage property, the SayHello button to invoke the SayHello method, and the CloseService button to invoke the Quit method to shut down the service. The service can also be configured using the Services control panel applet to run automatically when the system starts. It will be listed as "Hello OLE Server Service" in the Services applet.

helloservice -remove can be used to uninstall the service.

Files

SERVICE.C & SERVICE.H have the code to create a service and are copied from the SERVICE sample in the WIn32 SDK. (See the comments in service.h for information on command line arguments accepted by the service.)

MAIN.CPP and HELLO.CPP implement the automation object.

HELLOCF.CPP implements the class factory.

HELLO.ODL is the object description language that describes the property and methods that HELLO exposes.

TLB.H is the header file generated by MIDL.

MAKEFILE is the Makefile for project.

HELLO.REG is the Registry information.

Additional query words: COM DCOM

Keywords : kbsample kbAutomation kbNTOS400 kbWinOS2000 kbGrpCom kbDSupport LeTwoAto LeTwoCom
Version : :
Platform : NT WINDOWS
Issue type :