COM - Component Object Model Tutorial

DCOM - Topics

2008-12-11T21:07:00.000-08:00

Adding DCOM to the Simple Client

To activate our DCOM server we take the basic COM client shell and add some additional methods to make it DCOM-ready. One obvious change

is that we specify the name of the server computer. Here are the other things we must add to the client:

l A way to specify the server computer name. This will load into the COSERVERINFO structure.

l Call CoCreateInstanceEx() instead of CoCreateInstance(). This also involves some different parameters and a structure called

MULTI_QI.

l The first thing you do in any COM program is call CoInitialize. We'll use the default-threading model, which is apartment threading.

// initialize COM

hr = CoInitialize(0);

Specifying the Server with COSERVERINFO

When making a remote DCOM connection you must specify the server computer. The name of the computer can be a standard UNC computer

name or a TCP/IP address. We'll ask the user to enter the computer name. Our example is a console application, so we'll use a simple input

stream (include ) to get user input and display messages.

// Get the server name from user

char name[32];

cout << "Enter Server Name:" <<>

gets( name );

The server name will be loaded into a COSERVERINFO structure. This structure requires a pointer to a wide-character string for the server

name. We'll use _bstr_t copy constructor to convert the string. _bstr_t is a useful class when working with BSTRs and wide characters. Note

that the COSERVERINFO structure was initialized to zero with the memset() function.

// remote server info

COSERVERINFO cs;

// Init structures to zero

memset(&cs, 0, sizeof(cs));

// Allocate the server name in the COSERVERINFO struct

// use _bstr_t copy constructor

cs.pwszName = _bstr_t(name);

Specifying the Interface with MULTI_QI

Normally, we get an interface pointer by calling CoCreateInstance. For DCOM we need to use the extend version, CoCreateInstanceEx.

This extended function works perfectly well for local COM servers as well. CoCreateInstanceEx has several important differences. First, it lets

you specify the server name; and second, it allows you to get more than one interface in a single call.

We've already set up our COSERVERINFO structure. We'll pass it into CoCreateInstanceEx to specify the server. (If you leave this parameter

NULL, you'll get the local computer).

Unlike its predecessor, CoCreateInstanceEx returns more than one interface at a time. It does this by passing in an array of MULTI_QI

structures. Each element of the array specifies a single interface. CoCreateInstanceEx will fill in the data requested.

// structure for CoCreateInstanceEx

MULTI_QI qi[2];

// Array of structures

// set to zero

memset(qi, 0, sizeof(qi));

// Fill the qi with a valid interface

qi[0].pIID = &IID_IGetInfo;

qi[1].pIID = &IID_ISomeOtherInterface;

// get the interface pointer

hr = CoCreateInstanceEx(

CLSID_GetInfo, // clsid

NULL, // outer unknown

CLSCTX_SERVER, // server context

&cs, // server info

2, // size of qi

qi ); // MULTI_QI array

The MULTI_QI structure holds three pieces of information: a) a pointer to the IID, b) the returned interface pointer, and c) an HRESULT. Here's

the structure, as defined in OBJIDL.IDL:

typedef struct tagMULTI_QI

{

// pass this one in

const IID *pIID;

// get these out (must set NULL before calling)

IUnknown *pItf;

HRESULT hr;

} MULTI_QI;

The qi variable is an array of MULTI_QI structures. We start by setting the entire array to zero. This is done with the call to memset(). Next

we fill the pIID element with a pointer to the interface GUID (IID) of the interface we want to extract. In our example here, we're requesting a

pointer to IGetInfo and ISomeOtherInterface (ISomeOtherInterface is a fictional interface.). If we only need a single interface, we'd

make the array size 1 and skip the second element. The 5th parameter to CoCreateInstanceEx defines the size of the array.

Calling CoCreateInstanceEx will populate the MULTI_QI array. Like most COM API functions, CoCreateInstanceEx returns an HRESULT.

This function typically returns any of three HRESULTs.

l S_OK. All interfaces were returned.

l CO_S_NOTALLINTERFACES. At least one of the interfaces was returned, but some others failed.

l E_NOINTERFACE. None of the interfaces could be returned.

To determine which interface failed, you can check the HRESULT in the qi array.

if (SUCCEEDED(hr))

if (SUCCEEDED(qi[0].hr)) {

// pItf pointer is OK.

CoCreateInstanceEx Will Fail if There Are Network Problems.

Once you work out the initial bugs, your call to CoCreateInstanceEx will either succeed, or it will fail with an error like

RPC_S_SERVER_UNAVAILABLE. In my code, I usually only check the return status of CoCreateInstanceEx and abort the program if it isn't

S_OK. This is because I can't continue without all the requested interfaces. Note that you still have to call Release on all the interfaces that

were successfully returned.

The subject of error codes is extremely important for DCOM over the network. The lowly HRESULT contains more information then you might

suspect and this information is especially useful in tracking down network errors. I'll cover errors in more detail later in this article.

Once you've established that the interfaces were returned, you can use the interface pointers. In this case, I'm copying the pointer I requested

into a IGetInfo interface pointer for use in the program.

// pointer to interface

IGetInfo *pI;

if (SUCCEEDED(hr))

{

// Basic style string

BSTR bsName;

// Extract the interface from the MULTI_QI structure

pI = (IGetInfo*)qi[0].pItf;

// Call a method on the remote server

hr = pI->GetComputerName( &bsName );

pI->Release();

...

The rest of the code is just normal COM client code. There's nothing special about DCOM clients once you've connected to the server. There is

one big difference that we'll cover later - errors. You can expect a lot of problems when getting your client and server to work together over a

network for the first time. Many of those problems are related to server and proxy/stub registration.

http://devcentral.iticentral.com/articles/DCOM/intro_DCOM/part3/default.php (6 of 11) [7/9/2001 2:53:00 PM]

DevCentral - Understanding DCOM - Part III

Registering the Server and the Proxy/Stub

If you're working on a single machine, registration for DCOM is identical to standard COM. The server program will typically register itself when

you run it with the -REGSERVER switch. Standard Wizard-generated servers will have this code built into them. When the EXE is run with the -

REGSERVER switch, it registers itself in the system registry and exits.

C:\> remoteServer -regserver

In these examples we're using custom interfaces. This means that the proxy/stub DLL is required on the client machine. The proxy/stub is the

component that will send all information between the client and server over the network. To use a proxy/stub DLL, you need to register it.

C:\> REGSVR32 remoteserverps.dll

This registers the proxy/stub DLL on the client so DCOM can automatically activate it. If you're using an IDispatch (or dual) based automation

client, you won't have a proxy/stub DLL. In this case, you'll use a type library to register.

Copying the Client to Another Computer

You've probably built your client and server on the same computer. You probably also tested it on the same computer. Now it's time to copy

the client program to another computer and test it remotely. Copy both the client EXE and the proxy/stub DLL generated by the server. You

don't need to register the server on the client machine. This is because we've specified the server computer name in the COSERVERINFO

structure. The server does have to be registered on the server computer, or nothing will work.

On the client machine, create a new directory that will hold the client code and copy the client code into the directory. Then register the

proxy/stub. You might type something like this into the MS-DOS prompot on the client machine:

C:\> COPY \\Raoul\UnderCOM\RempteClient\Debug\Remoteclient.EXE

C:\> COPY \\Raoul\UnderCOM\RemoteServer\RemoteserverPS.DLL

C:\> REGSVR32 RemoteserverPS.DLL

Many people forget the proxy/stub DLL registration step on the third line. Without it, nothing will work.

Security is a Big Headache

Security is a really important issue, especially for network applications. Eventually, you will have to ensure that your DCOM application is

secure. Once you understand the concepts and get the server working, then you can add security to your application. My advice is to get things

working before you introduce any security.

Security varies between Win95/98 environments and Windows NT. Windows 95/98 offers some limited security features. You can go wild with

security on Windows NT.

You can manipulate security settings for both the client and sever in your program. This is done with the CoInitializeSecurity API call. You

can use this call to either add security or turn security off. You call this method immediately after calling CoInitialize.

// turn off security - overrides defaults

hr = CoInitializeSecurity(NULL, -1, NULL, NULL,

RPC_C_AUTHN_LEVEL_NONE,

RPC_C_IMP_LEVEL_IMPERSONATE,

NULL,

EOAC_NONE,

NULL);

CoInitializeSecurity takes quite a few parameters. All them are important and represent significant security concepts. You'll find extensive

(and challenging) material in the help files on CoInitializeSecurity and RPC security. (See the "Security in COM" article in MSDN).

It is important to note that you can also specify security information for a server using DCOMCNFG and OLEVIEW. These utilities save security

information in the registry. You can also specify security for the client program by explicitly calling CoInitializeSecurity (thus overriding the

default registry settings.)

An interesting aspect of CoInitializeSecurity is that it is called from both the client and server. Many of the parameters are specific to the

client and others to the server.

DCOM Client Source Code

2008-12-10T21:03:00.000-08:00

Following is a listing of the client program. We will describe all the important parts of this code in the following sections.

// RemoteClient.cpp : Defines the entry point for the console application.

#include "stdafx.h" // added _WIN32_DCOM

#include // get "cout"

#include // get _com_error

#include // get time_t

// extract definitions from server project

#include "..\RemoteServer\RemoteServer.h"

#include "..\RemoteServer\RemoteServer_i.c"

// forward reference for status display method

void ShowStatus( HRESULT hr );

int main(int argc, char* argv[])

{

HRESULT hr; // COM error code

IGetInfo *pI; // pointer to interface

// Get the server name from user

char name[32];

cout << "Enter Server Name:" <<>

gets( name );

_bstr_t Server = name;

// remote server info

COSERVERINFO cs;

// Init structures to zero

memset(&cs, 0, sizeof(cs));

// Allocate the server name in the COSERVERINFO struct

cs.pwszName = Server;

// structure for CoCreateInstanceEx

MULTI_QI qi[1];

memset(qi, 0, sizeof(qi));

// initialize COM

hr = CoInitialize(0);

ShowStatus( hr );

// macro to check for success

if (SUCCEEDED(hr))

{

// set a low level of security

hr = CoInitializeSecurity(NULL, -1, NULL, NULL,

RPC_C_AUTHN_LEVEL_NONE,

RPC_C_IMP_LEVEL_IMPERSONATE,

NULL,

EOAC_NONE,

NULL);

// init security

ShowStatus( hr );

}

if (SUCCEEDED(hr))

{

// Fill the qi with a valid interface

qi[0].pIID = &IID_IGetInfo;

// get the interface pointer

hr = CoCreateInstanceEx(

CLSID_GetInfo, // clsid

NULL, // outer unknown

CLSCTX_SERVER, // server context

&cs, // server info

1, // size of qi

qi ); // MULTI_QI array

ShowStatus( hr );

}

if (SUCCEEDED(hr))

http://devcentral.iticentral.com/articles/DCOM/intro_DCOM/part3/default.php (3 of 11) [7/9/2001 2:53:00 PM]

DevCentral - Understanding DCOM - Part III

{

BSTR bsName; // Basic style string

// Extract the interface from the MULTI_QI strucure

pI = (IGetInfo*)qi[0].pItf;

// Call a method on the remote server

hr = pI->GetComputerName( &bsName );

ShowStatus( hr );

// Convert name to a printable string

_bstr_t bst( bsName );

cout << "Server Name :" <<>

// get time from remote computer

time_t tt;

hr = pI->GetTimeT(&tt );

ShowStatus( hr );

// display time_t as a string

cout << "Server Time :" <<>

// Release the interface

pI->Release();

}

// Close COM

CoUninitialize();

// Prompt user to continue

cout << "Press ENTER to continue" <<>

getchar();

return 0;

}

// Display detailed status information

void ShowStatus( HRESULT hr )

{

if (SUCCEEDED(hr))

{

cout << "OK" <<>

}

else

{

// construct a _com_error using the HRESULT

_com_error e(hr);

char temp[32];

// convert to hexidecimal string and display

sprintf( temp, "0x%x", hr );

cout << "Error : " <<>

// The hr as a decimal number

cout << "Decimal : " <<>

// show the 1st 16 bits (SCODE)

cout << "SCODE : " <<>

// Show facility code as a decimal number

cout << "Facility: " <<>

// Show the severity bit

cout << "Severity: " <<>

// Use the _com_error object to format a message string. This is

// Much easier then using ::FormatMessage

cout << "Message : " <<>

}

DCOM Server

2008-12-09T21:02:00.000-08:00

Any server that runs as a program (EXE) will work across a network. In general, you don't have to make any changes to a server to get it towork for DCOM. You may, however, want to add some security to your server, which will involve some effort. I've ignored security in this tutorial to keep things simple, If you're using an in-process server, you will need to make some changes. An in-process server is a DLL, which can't load across a network. A DLL loads into the client program's address space, which will not work for remote connections. There is a work-around called a surrogate,

which wraps the DLL in an executable program; however, it is usually more appropriate to change the server over to an EXE. Generally, the easiest way to convert a DLL to an EXE is to recreate the server using the ATL Wizard and transfer the code from the DLL to the EXE.

For our example I have provided the source code for RemoteServer.exe, which implements a simple EXE-based DCOM server. If you look at the code you will see it is out-of-the-box, wizard-generated code. However, I have added two methods - one to get the server name and another to get the server's system time. After compiling the example, we'll simply copy the client EXE to the client computer. Note that you will also need a proxy/stub DLL because this is a custom interface. You will need to register the proxy/stub DLL on both the client and the server computers. If you are using an automation server with a type library, you will need to copy the typelib and register it on the client computer.

Up a Remote Server Using OLEVIEW and DCOMCNFG

Actually, you can make a server program run remotely just by changing registry settings. There are two Microsoft tools to do this: OLEVIEW and DCOMCNFG. Both tools set the registry so that DCOM tries to find the server on a remote computer. You can type in the remote computer name under the Activation tab of OLEVIEW, and it will be started on that computer. But this is a rather inelegant and inflexible solution, although it does work with older non-DCOM applications. I'm going to concentrate onsetting up the remote activation using programmatic changes to the client. This approach will prove to be more flexible, once you get the hang of it.

The Difference Between COM and DCOM

2008-12-08T21:01:00.000-08:00

Most of the differences between COM and DCOM applications are hidden from the developer. The client and server program can be written

identically, regardless of where the programs are running. This concept is known as Local/Remote Transparency. This makes your job as a

programmer much more consistent.

Of course, there are some real differences in how distributed and local COM work internally. Local communications can be accomplished many

ways, including simple Windows messages. Connecting to a remote computer requires a whole new layer of objects and network traffic.

Despite these rather large differences, there are only a few things in your program you'll need to change.

Like all COM communication, everything starts when the client requests an interface from a server. In DCOM, the client calls

CoCreateInstanceEx(), passing in a description of the server computer and requesting a class identifier (CLSID) and Interface. This request

is handled by the Service Control Manager (SCM), which is a part of Windows. The SCM is responsible for the creation and activation of the

COM object on the server computer. In the case of DCOM, the SCM will attempt to launch the server on the remote computer.

Figure 1. DCOM System Relationships.

Once the remote COM server has been created, all calls will be marshaled through the proxy and stub objects. The proxy and stub

communicate using RPCs (Remote Procedure Calls), which handle all the network interaction. On the server side, the stub object takes care of

marshaling. On the client, the proxy does the work.

The transmittal of data across the network is taken care of by RPC. Actually, DCOM uses an extended type of RPC called an Object RPC, or

ORPC. RPCs can run on a number of protocols, including TCP/IP, UDP, NetBEUI, NetBIOS, and named pipes. The standard RPC protocol is UDP

(User Datagram Protocol). UDP is a connectionless protocol, which seems like a bad fit for a connection-oriented system like DCOM. This isn't a

problem however; DCOM automatically takes care of connections.

As you can see, distributed COM is accomplished through a complex interaction of different hardware, operating system, and software

components. You should realize two important things from this: a) COM does a lot of work behind the scenes, and b) there are a lot of things

that can go wrong.

At the time of writing, only the TCP/IP protocol is available for DCOM data transfer on Windows 95/98 systems. This can be an annoying

limitation, requiring you to install TCP/IP on all Windows 95 systems, even when other network protocols are available.

DCOM

2008-12-07T21:00:00.000-08:00

DCOM stands for "Distributed" COM. In the previous two articles, we have demonstrated COM clients and servers running on the same

computer. In this article, we'll discuss how to extend our range into the area of DCOM and distributed computing.

Most COM programmers only use local "in-process" servers, which run as DLLs. A DLL loads into the process space of the client program, and is

therefore quite reliable and efficient. We are going to be using an EXE-based server. This means the server and client run as separate

programs. This makes sense, when you consider that the two programs are running on different computers. It does, however, introduce a new

level of difficulty.

The good news is that converting from COM to DCOM is easy. The bad news is that there are a lot of things that can go wrong in the process of

connecting the client and server. In this article, the emphasis is on helping you avoid the problems.

Registering server

2008-12-06T20:59:00.000-08:00

The COM subsystem uses the Windows registry to locate and start all COM objects. Each COM server is responsible for self-registering, or

writing its entries into the registry. Thankfully, this task has been mostly automated by ATL, MIDL and the ALT wizard.

One of the files created by MIDL is a registry script. This script contains all the definitions required for the successful operation of our server.

Here is the generated script:

HKCR

{

BeepObj.BeepObj.1 = s 'BeepObj Class'

{

CLSID = s '{861BFE30-56B9-11D1-BD65-204C4F4F5020}'

}

BeepObj.BeepObj = s 'BeepObj Class'

{

CurVer = s 'BeepObj.BeepObj.1'

}

NoRemove CLSID

{

ForceRemove

{861BFE30-56B9-11D1-BD65-204C4F4F5020} =

s 'BeepObj Class'

{

ProgID = s 'BeepObj.BeepObj.1'

VersionIndependentProgID = s 'BeepObj.BeepObj'

ForceRemove 'Programmable'

InprocServer32 = s '%MODULE%'

{

val ThreadingModel = s 'Apartment'

}

Registry Scripts

You may be familiar with .REG scripts for the registry. RGS scripts are similar, but use a complete different syntax and are only used by ATL for

object registration. The syntax allows for simple variable substitution, as in the %MODULE% variable. These scripts are invoked by the ATL

Registry Component (Registrar). This was defined with a macro in the object header:

DECLARE_REGISTRY_RESOURCEID(IDR_BEEPOBJ)

Basically, this script is used to load registry settings when the server calls CComModule::RegisterServer(), and to remove them when

CComModule::UnregisterServer() is called. All COM registry keys are located in HKEY_CLASSES_ROOT. Here are the registry keys being set:

l BeepObj.BeepObj.1 - Current version of the class.

l BeepObj.BeepObj - Identifies the COM object by name.

l CLSID - The unique class identifier for the Object.

There are several sub-keys under the CLISD:

l ProgID - The programmatic identifier.

l VersionIndependentProgID - Associates a ProgID with a CLSID.

l InprocServer32 - Defines a server type (as a DLL). This will vary depending on whether this is an In-Process, Local, or Remote server.

l ThreadingModel - The COM threading model of the object.

l TypeLib - The GUID of the server's type library.

Developed Under:

DCOM Errors

2008-12-05T20:58:00.000-08:00

The following error codes are typical HRESULTs you may get back from your client program. I've included some suggestions about what they

might mean. I've included the symbolic name, as well as the translated message text. This is by no means a comprehensive list, but it's a

great starting point for the most common errors.

CO_E_BAD_SERVER_NAME

A remote activation was necessary but the server

name provided was invalid.

This is one of the few self-explanatory error messages. Note that it doesn't mean

you entered the wrong server name. It means you entered an invalid server name.

Check that the name is in the proper network format - check for invalid characters.

Unresolved or non-existent servers show up with a different error message:

RPC_S_SERVER_UNAVAILABLE.

CO_E_SERVER_EXEC_FAILURE

Server execution failed.

Check the COM security FAQ for more information.

Microsoft Support - Article Q158508

(This site requires registration.)

E_ACCESSDENIED

General access denied error.

This is an error from the security subsystem. The server system rejected a

connection. These problems can be very difficult to diagnose. This error is most

likely when using DCOM for remote connections.

Check for activation problems, especially on Windows 95/98.

Check security settings with DCOMCNFG.

Reinstall the server and the Proxy/Stub DLL.

Be sure you have File/Print sharing enabled.

E_FAIL

Unspecified error.

This is often an application-specific error caused by a method returning E_FAIL.

E_NOINTERFACE

No such interface supported.

You asked a server for an interface it doesn't support. This means your CLSID is

probably OK, but the IID is not. This call is returned by QueryInterface (or through

CoCreateInstance) when it doesn't recognize an interface. It may also be a

proxy/stub problem.

This may be a registration problem. Try re-registering the server and proxy/stub.

E_OUTOFMEMORY

Ran out of memory.

This message may be unrelated to the actual error. See the security FAQ for some

other possibilities.

Microsoft Support - Article Q158508 (This site requires registration.)

ERROR_INVALID_PARAMETER

The parameter is incorrect.

You have a problem in one of the parameters to your function call. This is

commonly seen in functions such as CoCreateInstance, CoCreateInstanceEx,

CoInitializeSecurity, etc.

ERROR_SUCCESS

The operation completed successfully.

The same message as S_OK and NO_ERROR.

REGDB_E_CLASSNOTREG

Class Not Registered.

A registration or CLSID problem. Check your GUIDs.

The server may not be running on the remote Windows 95/98 system.

http://devcentral.iticentral.com/articles/DCOM/intro_DCOM/part3/default.php (10 of 11) [7/9/2001 2:53:01 PM]

DevCentral - Understanding DCOM - Part III

RPC_S_SERVER_UNAVAILABLE

RPC Server is unavailable.

This problem is very common when working with remote servers. This is a generic

remote connection error. RPC is the protocol used to implement DCOM. This can be

a system setup problem or a security problem. You're about to learn a lot about

networking!

You may be trying to connect to an incorrect or disconnected computer. Check the

server name.

Be sure DCOM and RPC are enabled on the computer. Use DCOMCNFG or OLEVIEW

(in "System Configuration" under the File menu).

Re-register the server and proxy/stub.

Check server activation problems, especially on Window 95/98.

Try all the steps defined in the previous section.

Errors And Debugging

2008-12-04T20:57:00.000-08:00

Your client and server programs might work the first time you activate them, but probably they won't. Herein lies the big problem with DCOM.

If you're trying to make things work in a real-world network situation, you're going to hit some snags.

Remote connection problems usually come in four flavors:

1. The client and server didn't work to start with. Debug locally before you try it over the network.

2. Connection problems. If you can't get a good network connection between the client and server computer, DCOM will never work.

Network configuration can be complex.

3. Launching problems. COM will not start the COM server program on the server computer. This is usually a security or registration

problem.

4. You can't connect to the COM object on the server. This is usually a security or registration problem.

The following section discusses some of the problems you may encounter when working across a network. I've tried to outline some of the

approaches I've found useful in diagnosing and fixing problems. Here are some suggestions about how to debug network problems with DCOM.

Step 1: Get it working locally

The first step in debugging is to get the client and server working locally. Install both components on the server machine, and keep at it until

you can successfully communicate. If a component won't work locally, it won't work across a network. You probably developed and tested the

application on a single computer, but if the server is being installed on a different computer, test both client and server on that system too.

By getting the system to work locally, you've eliminated most of the common programming and registration errors. There are still a few things,

like security and remote activation, that you can only test across the network. Specify your local computer in the COSERVERINFO structure,

which will exercise much of the network-related code.

Step 2: Be sure you can connect

Before you even try to install your program, first test and debug the network configuration between the client and server machines. Start by

checking the network neighborhood to ensure that you can browse the remote computer. This is not always possible, but a failure to browse

doesn't necessarily mean that DCOM won't work. In most cases, however, browsing is good starting place for checking connections. Check the

connection in both directions.

Perhaps the most useful tool is PING. PING sends a series of network packets to a specific machine and waits for a response. Most

installations support PING.

C:\> PING www.iticentral.com

Pinging www.iticentral.com 216.27.33.21 with 32 bytes of data:

Reply from 216.27.33.21: bytes=32 time=217ms TTL=120

Reply from 216.27.33.21: bytes=32 time=210ms TTL=120

Reply from 216.27.33.21: bytes=32 time=197ms TTL=120

Reply from 216.27.33.21: bytes=32 time=209ms TTL=120

Ping statistics for 216.27.33.21:

Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),

Approximate round trip times in milli-seconds:

Minimum = 197ms, Maximum = 217ms, Average = 208ms

C:\>

PING does a number of interesting things for you. First, it resolves the name of the remote computer. If you're using TCP/IP, the name of the

remote computer will be converted to a TCP/IP address. In the above example, PING converts the name "www.iticentral.com" into the TCP/IP

address 216.27.33.21.

You should try PING from both directions. If you are using callbacks or connection points, you must have COM working in both directions.

Callbacks and connection points can be very difficult to debug unless you know the network connection is working.

Step 3: Try it out. Don't forget to register the proxy/stub DLL or type library

http://devcentral.iticentral.com/articles/DCOM/intro_DCOM/part3/default.php (8 of 11) [7/9/2001 2:53:00 PM]

DevCentral - Understanding DCOM - Part III

Once you've finished the first two steps, it's worth trying the remote connection. If it works, consider yourself blessed.

The most common reasons for an otherwise OK connection to fail are registration problems. Be sure you registered the COM server on the

server computer. Be sure you registered the proxy/stub DLL on both the client and server computer. If you're using an automation or dual

interface, be sure the type library is registered on both systems. (To register a proxy/stub DLL, use the REGSVR32 command.)

Step 4: Try to get around name resolution problems

Name resolution can be a vexing problem in remote connections. Most people want to work with names like "\\RAOUL" and "\\SERVER" rather

then TCP/IP addresses. The process of turning that readable name into a network address is called Name Resolution, and it can be very

complicated on some system configurations. A common work-around is to refer to the server by its TCP/IP address. This will eliminate many

name resolution problems - which are outside the scope of this discussion. You can easily put a TCP/IP address instead of a standard computer

name into the COSERVERINFO structure.

You can also glean interesting information from the TRACERT (trace route) utility. If you have weird network configurations, they may show

up here.

C:\> TRACERT www.iticentral.com

Tracing route to www.iticentral.com 216.27.33.21

over a maximum of 30 hops:

1 184 ms 169 ms 182 ms ct1.intercenter.net [207.211.129.2]

2 182 ms 189 ms 188 ms ts-gw1.intercenter.net [207.211.129.1]

3 195 ms 192 ms 161 ms ilan-gw1.intercenter.net [207.211.128.1]

4 220 ms 178 ms 206 ms 206.152.70.33

5 188 ms 207 ms 216 ms 207.211.122.2

6 196 ms 189 ms 205 ms 216.27.1.71

7 * * * Request timed out.

8 201 ms 221 ms 197 ms rampart.iticentral.com [216.27.12.142]

9 210 ms 205 ms 192 ms www.iticentral.com [216.27.33.21]

Trace complete.

C:\>

As you can see, the route your DCOM packets are taking to their destination may be surprising!

Be especially aware of gateways, routers, proxies, and firewalls, as they will often block your connection. Firewalls in particular must be

scrutinized, because firewalls will often block DCOM packets. Check with the network administrator.

Step 5: Can't launch the server?

By launching, we mean that COM automatically starts the server on request. This should always work on a local COM connection, but it can be

problematic with network connections. If you're working with Windows 95/98, COM won't automatically launch a server. This limitation is

necessary because of the lack of security on these operating systems. Because Windows NT provides full-blown security, it can automatically

launch servers.

The work-around for this problem with Windows 95/98 clients is simple. Manually start the server before the client connects. Once the server is

launched, it will connect normally.

There is one big 'gotcha'. The server will shutdown as soon as the last client calls Release() . The COM server's reference count will be zero,

and the server will shut itself down. This means the client will fail the next time it tries to connect. You'll get RPC_S_SERVER_UNAVAILABLE or

E_ACCESSDENIED from your call to CoCreateInstanceEx.

My favorite solution is to run a simple "watchdog" program on the server computer. This simple application always maintains a COM connection

to the server. Because this program runs from the server computer, it launches the server automatically when it starts. As long as the

watchdog program is running, the server will stay alive. If desired, you can start the watchdog program from the Startup group to bring the

server up when the machine boots.

Step 6: Try DCOMCNFG and OLEVIEW

You've probably already been using these tools. DCOMCONF and OLEVIEW are two Microsoft utilities that show you registration information

about your COM servers. Both of these products show you registry information in a more structured format. Both tools have disadvantages.

OLEVIEW shows you a lot more information than you may want to see. The latest version of this utility has many good features, and you

should get the latest download download at Microsoft's site: http://www.microsoft.com/com/resource/oleview.php. DCOMCNFG is a fairly crude

tool. It shows a lot of information, but many people have trouble using it effectively. If you aren't already using one of these tools, you should

http://devcentral.iticentral.com/articles/DCOM/intro_DCOM/part3/default.php (9 of 11) [7/9/2001 2:53:01 PM]

DevCentral - Understanding DCOM - Part III

start. There are also some good third-party COM utilities you can preview on the Internet.

Step 7: Re-Register the server and proxy/stub (or Typelib)

Sometimes re-registering the server and proxy/stub DLL can do wonders. If you're using Automation (or dual) interfaces, re-register the type

library.

Step 8: Ask a network administrator

Sometimes the best line of defense will be a competent network administrator. If you've got one, you're lucky. Unfortunately, competent

network administrators are a) rare, b) very busy, and c) averse to working with pesky programmers. An administrator may be able to help you

resolve tough security and name resolution problems.

The Class Definition

2008-12-03T20:55:00.000-08:00

Our object uses a default constructor. You can add special initialization here if required, but there are some limitations. One consequence of

using the ATL_NO_VTABLE is that you aren not allowed to call any virtual methods in the constructor. A better place for complex initialization

would be in the FinalConstruct method (which is inherited from CComObjectRootEx.) If you want to use FinalConstruct, override ATL's default

by declaring it in the class definition. It will be called automatically by the ATL framework. (FinalConstruct is often used to create aggregated

objects.)

The DECLARE_REGISTRY_RESOURCEID() macro is used to register the COM object in the system registry. The parameter to this macro,

IDR_BEEPOBJ, points to a resource in the project. This is a special kind of resource that loads the MIDL-generated ".rgs" file.

BEGIN_COM_MAP is a macro that defines an array of COM interfaces that the CComObjectRoot< > class will manage. This class has one

interface, IBeepObj. IBeepObj is our custom interface. It is common for COM objects to implement more than one interface. All supported

interfaces would show up here, as well as in the class inheritance at the top of the class definition.

The Method

At last, we get to the methods. As an application programmer, our main interest will be in this section of the code. Our single Beep() method is

defined in the line:

STDMETHOD(Beep)(/*[in]*/ LONG duration);

STDMETHOD is an OLE macro that translates to the following:

typedef LONG HRESULT;

#define STDMETHODCALLTYPE __stdcall

#define STDMETHOD(method) virtual HRESULT STDMETHODCALLTYPE method

We could have written the definition in a more familiar C++ style as follows:

virtual long _stdcall Beep(long lDuration);

We'll find the code for this method in the BeepObj.cpp module. Because this COM object has only one method, the COM object's source code is

pretty sparse. All the COM logic of the object was defined in the ATL template classes. We're left with just the actual application code. When

you are writing real applications, most of your attention will be focused on this module.

STDMETHODIMP Beep(long lDuration)

{

http://devcentral.iticentral.com/articles/DCOM/intro_DCOM/part2/3.php (4 of 6) [7/9/2001 2:52:53 PM]

DevCentral - Understanding DCOM - Part II

::Beep( 660, lDuration );

return S_OK;

}

Again, the function definition translates into a standard function call.

long _stdcall CBeepObj::Beep( long lDuration )

The API beep routine takes two parameters: the frequency of the beep, and it's duration in milliseconds. If you're working with Windows 95,

these two parameters are ignored and you get the default beep. The scope operator "::" is important, but is easily forgotten. If you neglect it,

the method will be calling itself.

The _stdcall tag tells the compiler that the object uses standard windows calling conventions. By default C and C++ use the __cdecl calling

convention. These directives tell the compiler which order it will use for placing parameters on, and removing them from, the stack. Win32

COM uses the _stdcall atribute. Other operating systems may use different calling conventions.

Notice that our Beep() method returns a status of S_OK. This doesn't mean that the caller will always get a successful return status.

Remember that calls to COM methods aren't like standard C++ function calls. There is an entire COM layer between the calling program

(client) and the COM server.

It is entirely possible that the CBeepObj::Beep() method would return S_OK, but the connection would be lost in the middle of a COM call.

Although the function would return S_OK, the calling client would get some sort of RPC error indicating the failure. Even the function result has

to be sent through COM back to the client!

In this example the COM server is running as an In-Process server. Being a DLL, the linkage is so tight there is very little chance of

transmission error. In future examples, where our COM server is running on a remote computer, things will be very different. Network errors

are all too common, and you need to design your applications to handle them.

Server Registration

Object Inheritance

2008-12-02T20:55:00.000-08:00

Probably the first thing you noticed about this code is the multiple inheritance. Our COM object has three base classes. These base classes are

template classes which implement the standard COM functionality for our object. Each of these classes defines a specific COM behavior.

CComObjectRootEx< > and CComObjectRoot< > are the root ATL object classes. These classes handle all the reference counting and

management of the COM class. This includes implementation of the three required IUnknown interfaces, QueryInterface(), AddRef(), and

Release(). When our CBeepObj object is created by the server, this base class will keep track of it throughout its lifetime.

The template for CComObjectRootEx specifies the argument CComSingleThreadModel. Single threading means that the COM object won't have

to handle access by multiple threads. During the setup of this object we specified "Apartment threading." Apartment threading uses a windows

message loop to synchronize access to the COM object. This approach is the easiest because it eliminates many threading issues.

CComCoClass< > defines the Class factories that create ATL COM objects. Class factories are special COM classes that are used to create COM

objects. The CComCoClass uses a default type of class factory and allows aggregation.

http://devcentral.iticentral.com/articles/DCOM/intro_DCOM/part2/3.php (3 of 6) [7/9/2001 2:52:53 PM]

DevCentral - Understanding DCOM - Part II

IBeepObj is the interface this server implements. An interface is defined as a C++ struct (recall that structs in C++ act like a class but can

have only public members). If you dig into the automatically generated file BeepServer.h, you'll find that the MIDL has created a definition of

our interface.

interface DECLSPEC_UUID(

"36ECA947-5DC5-11D1-BD6F-204C4F4F5020")

IBeepObj : public IUnknown

{

public:

virtual /* [helpstring] */ HRESULT

STDMETHODCALLTYPE Beep(

/* [in] */ long lDuration) = 0;

};

The DECLSPEC_UUID macro lets the compiler associate a GUID with the interface name. Note that our single method "Beep" is defined as a

pure virtual function. When the CBeepObj is defined, it will have to provide an implementation of that function.

One peculiar thing about this Class definition is that it has the ATL_NO_VTABLE attribute. This macro is an optimization that allows for faster

object initialization.

Object maps

2008-12-01T20:54:00.000-08:00

The CComModule is connected to our COM object (CBeepObj) by the object map seen in the previous section. An object map defines an array

of all of the COM objects the server controls. The object map is defined in code using the OBJECT_MAP macros. Here is our DLL's object map:

BEGIN_OBJECT_MAP(ObjectMap)

OBJECT_ENTRY(CLSID_BeepObj, CBeepObj)

END_OBJECT_MAP()

The OBJECT_ENTRY macro associates the CLSID of the object with a C++ class. It is common for a server to contain more than one COM

object. When this is the case, there will be an OBJECT_ENTRY for each one.

Export File

Our In-Process DLL, like most DLLs, has an export file. The export file will be used by the client to connect to the exported functions in our

DLL. These definitions are in the file BeepServer.def:

; BeepServer.def : Declares the module parameters.

LIBRARY "BeepServer.DLL"

EXPORTS

DllCanUnloadNow @1 PRIVATE

DllGetClassObject @2 PRIVATE

DllRegisterServer @3 PRIVATE

DllUnregisterServer @4 PRIVATE

It is important to note what is not exported. There are no custom methods, and no export for the "Beep" method. The above are the only

exports you should see in a COM DLL.

Looking into the BeepServer.CPP file, we see that the implementation of these four functions is handled by the COM application class. Here's

the code for DllRegisterServer:

http://devcentral.iticentral.com/articles/DCOM/intro_DCOM/part2/3.php (2 of 6) [7/9/2001 2:52:53 PM]

DevCentral - Understanding DCOM - Part II

// DllRegisterServer - Adds entries to the system registry

STDAPI DllRegisterServer(void)

{

// registers object, typelib and all interfaces in typelib

return _Module.RegisterServer(TRUE);

}

In this case, the DLL just calls ATL's CComModule::RegisterServer() method. CComModule implements the server registration in a way that is

compatible with In-Process, Local, and Remote COM servers. The other four exported DLL functions are equally spartan. The actual

implementation is hidden in the ATL templates.

Most of the code described above is DLL-specific code. You will only get this configuration if you choose to create a DLL-based server. None of

the code in the main module is COM specific. The main module is entirely devoted to the infrastructure required to deliver COM objects in a

DLL, and this code will vary significantly depending on the type of server. The actual code inside the server is much more uniform. The

implementation of a coclass and interface is identical regardless of the type of server (DLL, EXE, server) you create. You can take a coclass

from a DLL server and implement it in an EXE-based server with few changes.

The COM Object -- "CBeepObj"

A COM server has to implement at least one COM object. We are using a single object named "CBeepObj." One of the most interesting things

about this object is that the code was entirely generated by ATL wizards. It is quite remarkable how compact this object definition turns out to

be. The class definition is found in BeepObj.h:

// BeepObj.h : Declaration of the CBeepObj

#include "resource.h" // main symbols

//////////////////////////////////////////////////////

// CBeepObj

class ATL_NO_VTABLE CBeepObj :

public CComObjectRootEx,

public CComCoClass,

public IBeepObj

{

public:

CBeepObj()

{

}

DECLARE_REGISTRY_RESOURCEID(IDR_BEEPOBJ)

BEGIN_COM_MAP(CBeepObj)

COM_INTERFACE_ENTRY(IBeepObj)

END_COM_MAP()

// IBeepObj

public:

STDMETHOD(Beep)(/*[in]*/ long lDuration);

};

This simple header file defines a tremendous amount of functionality, as described in the following sections.

The Main C++ Module

2008-11-30T20:53:00.000-08:00

When we ran the ATL COM Appwizard, we chose to create a DLL-based server and we chose not to use MFC. The first selection screen of the

wizard determined the overall configuration of the server.

The AppWizard created a standard DLL module. This type of standard DLL does not have a WinMain application loop, but it does have a DllMain

function used for the initialization of the DLL when it gets loaded:

CComModule _Module;

BEGIN_OBJECT_MAP(ObjectMap)

OBJECT_ENTRY(CLSID_BeepObj, CBeepObj)

END_OBJECT_MAP()

////////////////////////////////////////

// DLL Entry Point

extern "C"

BOOL WINAPI DllMain(HINSTANCE hInstance,

DWORD dwReason, LPVOID /*lpReserved*/)

{

if (dwReason == DLL_PROCESS_ATTACH)

{

http://devcentral.iticentral.com/articles/DCOM/intro_DCOM/part2/3.php (1 of 6) [7/9/2001 2:52:53 PM]

DevCentral - Understanding DCOM - Part II

_Module.Init(ObjectMap, hInstance);

DisableThreadLibraryCalls(hInstance);

}

else if (dwReason == DLL_PROCESS_DETACH)

_Module.Term();

return TRUE; // ok

}

All the DllMain function really does is check to see if a client is attaching to the DLL and then does some initialization. At first glance, there is no

obvious indication that this is a COM application at all.

The COM portion of our new server is encapsulated in the ATL class CComModule. CComModule is the ATL server base class. It contains all the

COM logic for registering and running servers, and for starting and maintaining COM objects. CComModule is defined in the header file

"altbase.h". This code declares a global CComModule object in the following line:

CComModule _Module;

This single object contains much of the COM server functionality for our application. Its creation and initialization at the start of program

execution sets a chain of events in motion.

ATL requires that your server always name its global CComModule object "_Module". It is possible to override CComModule with your own

class, but you are not allowed to change the name.

If we had chosen an executable-based server, or even a DLL with MFC, this code would be significantly different. There would still be a

CComModule based global object, but the entry point of the program would have been WinMain(). Choosing a MFC-based DLL would have

created a CWinApp-based main object.

ATL-generated Code

2008-11-29T20:53:00.000-08:00

The source code for our server DLL was generated by ATL. For many people it is perfectly acceptable to never look at the code ATL created. For others, not "knowing" the details of this code is unacceptable. This tutorial gives you a quick tour of the code produced by ATL. The code for the server DLL that is now sitting on your hard drive really resides in three different types of files. l First, there are the traditional C++ source and header files. Initially, all of this code is generated by the ATL wizards. l The Beep method was added by using the "AddMethod" dialog, which modified the MIDL interface definition. The MIDL source code is in

an IDL file - in this example it is BeepServer.IDL. The MIDL compiler will use this file to create several output files. These files will take care of much of the grunt work of implementing the server. As we add methods to the COM object, we'll be adding devinitions to the IDL file.

l The third group of source files are automatically generated MIDL output files created by the MIDL compiler. These files are source code files, but because they are automatically generated by the MIDL compiler from IDL source code, these files are never modified directly either by wizards or by developers. You might call them "second generation files" - the wizard created an IDL file and the MIDL

compiler created source code files from that IDL file. The files created by the MIDL include:

m BeepServer.RGS - Registration script for the server.

m BeepServer.h - This file contains definitions for the COM components.

m BeepServer_i.c - GUID structures for the COM components.

m Proxy/Stub files - This includes "C" source code, DLL definitions, and makefile (.mk) for the Proxy and Stub.

The ATL wizard also creates an application "resource," If you look in the project resources, you'll find it under "REGISTRY." This resource

contains the registration script defined in BeepServer.RGS. The name of the resource is IDR_BEEPOBJ.

We look at all of these different components in the sections below.

Client Side

2008-11-28T20:51:00.000-08:00

The client presented in the first installment of this series has the benefits of clarity and compactness. However, it contains little error-checking code and that makes it insufficient in a real application. Let's review that code, however, because it is so simple and it shows the exact steps that you must take to create a successful client:

void main()

{

HRESULT hr; // COM error code

IBeepDllObj *IBeep; // pointer to interface

hr = CoInitialize(0); // initialize COM

if (SUCCEEDED(hr)) // macro to check for success

{

hr = CoCreateInstance(

clsid,// COM class id

NULL, // outer unknown

CLSCTX_INPROC_SERVER, // server INFO

iid, // interface id

(void**)&IBeep ); // pointer to interface

if (SUCCEEDED(hr))

{

hr = IBeep-Beep(800); // call method

hr = IBeep-Release(); // release interface

}

CoUninitialize(); // close COM

}

The call to CoInitialize and CoCreateInstance initializes COM and gets a pointer to the necessary interface. Then you can call methods on the interface. When you are done calling methods you release the interface and call CoUninitialize to finish with COM. That's all there is to it. That would be all there is to it, that is, if things always worked as planned. There are a number of things that can go wrong when a COM clienttries to start a COM server. Some of the more common problems include:

l The client could not start COM

l The client could not locate the requested server

l The client could locate the requested server but it did not start properly

l The client could not find the requested interface

l The client could not find the requested method

l The client could find the requested method but it failed when called

l The client could not clean up properly

In order to track these potenital problems, you have to check things every step of the way by looking at HRESULT values. The above code does the checking, but it is difficult to tell what has gone wrong because the code is completely silent if an error occurs. The following function remedies that situation:

// This function displays detailed

// information contained in an HRESULT.

BOOL ShowStatus(HRESULT hr)

{

// construct a _com_error using the HRESULT

_com_error e(hr);

// The hr as a decimal number

cout << "hr as decimal: " <<>

// show the 1st 16 bits (SCODE)

cout << "SCODE: " <<>

// Show facility code as a decimal number

cout << "Facility: " <<>

// Show the severity bit

cout << "Severity: " <<>

// Use the _com_error object to format a message string.

// This is much easier then using ::FormatMessage

cout << "Message string: " <<>

return TRUE;

}

This function dismantles an HRESULT and prints all of its components, including the extremely useful English ErrorMessage value. You can call

it any time with this function call:

// display HRESULT on screen

ShowStatus( hr );

Figure 1. MFC Dialog example

To fully explore the different error modes of a simple COM program, the client in the following

demonstration code uses an MFC dialog application to let you control a number of possible errors

and see the effect they have on the HRESULT. When the client runs it will look like Figure 1.

You can see that the radio buttons on the left let you experiment with a lack of a CoInitialize

function, a bad class ID, and a bad interface ID. If you click the Run button the area on the right will

show the effect of the different errors on the HRESULT returned by different functions in the client.

When you explore the client code in this example, you will find that it is a somewhat more robust

version of the standard client code we used above. It also allows remote connections through

DCOM. For example, it sets default security using the CoInitializeSecurity function to introduce you

to that function, and it also makes use of the CoCreateInstanceEx function so that remote servers on other machines can be called. Walk

through the code, look up those two functions in the documentation and you will be amazed to find how easy it is to understand now that you

know something about COM!

Server Side

2008-11-27T20:49:00.000-08:00

The ATL Wizard makes COM server creation extremely easy. The first step in creating a COM coclass is coming up with one or more pieces of functionality that you want to separate from the main body of an application's code. You probably want to separate the functionality in order to make it reusable across multiple applications. But you may also want to do it because it allows a team of programmers to divide easily into

separate working groups, or because it makes code development or maintenance easier. Whatever the reason, defining the functionality is the first step. One thing that makes defining the boundary easy is the fact that a COM server can act almost identically to a normal C++ class. Like a class, you instantiate an instance of the COM class and then start calling its methods. The syntax of COM instantiation and method calling is slightly different from the syntax in C++, but the ideas are identical. If a COM server has only one interface, then it is, for all practical purposes, a class. (You still have to obey the rules of COM when accessing the object.)

Once you have decided on the functionality and the methods that will be used to access it, you are ready to build your server. As we saw in Understanding DCOM - Part I, there are four basic steps to creating a server:

1. Use the ATL Wizard to create the shell for your COM server. You choose whether you want the server to be a DLL, an EXE or a service.

2. Create a new COM object inside the server shell. You will choose the threading model. This creates the interface into which you can install your methods.

3. Add the methods to your object and declare their parameters.

4. Write the code for your methods.Each of these tasks has been described in detail in the previous article entitled Understanding a Simple COM Server.

After the first installment of "Understanding DCOM" appeared, one frequently asked question concerned threading models. Specifically, what is the difference between apartment-threaded and free-threaded COM objects? The easiest way to understand the difference is to think of apartment-threaded COM objects as single-threaded, while thinking of free-threaded COM objects as multi-threaded.

In apartment threading, method calls from multiple clients are serialized in the COM object on the server.

That is, each individual method call completes its execution before the next method call can begin. Apartment-threaded COM objects are therefore inherently thread safe. Freethreaded

COM objects can have multiple method calls executing in the COM object at the same time. Each method call from each client runs ona different thread. In a free-threaded COM object you therefore have to pay attention to multi-threading issues such as synchronization.

Initially you will want to use apartment threading because it makes your life easier, but over time the move to free threading may offer you

more advantages.

COM Clients and Servers

2008-11-26T20:47:00.000-08:00

Based on the previous trio of DCOM articles that appeared in DevJournal, you can see that it is extremely easy to create COM clients and servers. Just a handful of lines on both the client and server sides yields a complete COM application. You can now see why many developers use COM whenever they want to create a DLL - it only takes about 5 minutes to set up an in-process COM DLL and get it working.

The purpose of this article is to discuss how you might create your own COM servers and use them in real applications you create. As you will recall, the client code previously presented was a bit sparse. We will examine the standard steps you will take to create any server, and then look at the code you need to embed in any client to activate the server properly.