Download the Step 5 Files - 30.9 KB

Introduction

Welcome to Step 5 of our DCOM tutorial. In this series, I will strip the mystique, the headache, and confusion from DCOM by giving you a comprehensive tutorial with a straightforward example. OK, no promises -- but I will give it a good try.

If you want to follow along with this tutorial and add code and use the Visual C++ Wizards as we go along, that's great. In fact, I very very highly recommend that, because otherwise this tutorial is a big waste of electronic ink (?). However, I follow along exactly with the tutorial myself, as I write it, and develop the code and use the Visual C++ wizards just as I say you should. The screenshots, in fact, are from my development of the files for each step! To download this already-developed code to compare with your own, simply click the 'Download the Step n Files - n KB" links at the top of each step. There's also an archive of the files for all the steps at the Questions and Answers page for this tutorial. I still recommend that you follow along with us as we go; this way, you can learn while you code. If you ever have problems along the way with this tutorial, feel free to:

Connection Points Demystified

Before we plunge in with Step 5 of our tutorial, let's just take a moment for me to rip the shrouds of mystery off of Connection Points. Figure 1 below shows a generic scenario which is true for COM, DCOM, and even function call backs, for goodness' sake.

Figure 1. A source and a sink.

This involves two objects, a "source" and a "sink". Think of the "source" like the water faucet of the kitchen sink at home. You turn a handle, and stuff comes out of it (hopefully water). Where does it go? If nothing's backed up, this water flows down into the bottom and goes into the drain (which can be thought of as the "sink"). OK, so things flow from the source, to the sink. In the kitchen sink analogy above, this is water. However, I've never seen a computer network system run with water flowing across the wires, so obviously something else is at work in DCOM.

In DCOM, there is a "client," somewhere on the network, and there is a "server," also somewhere on the network. Without the use of connection points, things flow only one way: method calls replace our water, the client replaces our faucet, and the server replaces the drain. This is way oversimplifying things, but the user "turns a handle" (that is, clicks a button, for example), and "stuff" (that is, method calls) "comes out of" the client. This "stuff that comes out" then "flows" over the network using DCOM. These calls "flow" to the server, which then collects them and acts like the "drain", or our sink. Here's Figure 2, which is almost exactly like Figure 1, but puts the client in place of the "source" and the server in place of the "sink," with the network in between:

Figure 2. Our client and server as the source and the sink.

OK, so now we have method calls flowing like water; wonderful. However, when the client calls methods, the server does all kinds of things that might be interesting to clients. So the server fires events all over the place. If our client doesn't care if the server fires events, it will just ignore them. However, if it cares, it will Advise() the server. Then the source-sink relationship of Figure 2 can be thought of in reverse:

Figure 3. The reverse of Figure 2.

Connection points come in when you have the following happening:

The client is the source of a method call,
The server sinks (that is, acts as the sink for) the method call.
An "event call" comes out of the now-server-as-source.
The client sinks the event call and does something.

As you can see, this is a round-trip. A method call goes from the client to the server, and then an event call goes from the server, to the client, as seen in Figure 4.

Figure 4. A round-trip.

The Advise() step is done before item number 1 above, and the Unadvise() step (where the client goes back to being aloof) happens after item number 4. The points of contact on both the client and server and the Advise()ing and Unadvise()ing that happens all together form...

A CONNECTION POINT!!

Whew... what a revelation... Let's start Step 5 before I get too carried away...

Step 5: Add the OnSayHello Event to the Event Source Interface `DHelloWorldEvents`

Let's plunge in, shall we? To add an event to the source, it's really, really easy. Just use the Visual C++ Wizards! Open up ClassView, and right-click the DHelloWorldEvents icon, and then click Add Method. The Add Method to Interface dialog box appears. Type OnSayHello in the Method Name box, and type [in] BSTR bstrHost in the Parameters box, as shown in Figure 5, below.

Adding the OnSayHello event to the DHelloWorldEvents event interface.
Figure 5. Adding the OnSayHello() event to the DHelloWorldEvents event interface.

Once you're done, click OK. ClassView should resemble Figure 6 below. Now click FileView, and find the HelloServ.idl file, under the Source Files folder. Right-click that baby, and then choose Compile. Watch the compiler work away in the Output window, and wait until the build is complete.

Figure 6. ClassView after adding the OnSayHello event.

Once the build has been finished, click on ClassView. Right-click the CHelloWorld class, and then click Implement Connection Point. The Implement Connection Point dialog box appears. If you haven't compiled the IDL file yet like I told you to, Visual C++ will prompt you to do so. Figure 7, below, shows you how to select that you want to make the server able to fire off its OnSayHello event:

Figure 7. Specifying that we want to implement Connection Points for the DHelloWorldEvents event interface.

When everything looks like Figure 7, click OK. The Visual C++ IDE will now generate all the server-side code you need for Connection Points. Each time you change an event in the DHelloWorldEvents event interface, you need to do the (1) compile the IDL, (2) right-click CHelloWorld and choose Implement Connection Point, (3) check the box by DHelloWorldEvents, and (4) click OK steps.

Notes From the Rear

The final part of Step 5 which we have to take care of is firing the event. Remember, we declared the OnSayHello() event in the IDL file as:

HRESULT OnSayHello(BSTR bstrHost);

Listing 1. The declaration of the OnSayHello() event.

To fire the event from any CHelloWorld member function, just call Fire_OnSayHello(). It's a member function of a new base class, CProxyDHelloWorldEvents< > that the Implement Connection Points dialog box just added for us. To this end, let's add code to the CHelloWorld::SayHello() function to fire the event to the client:

STDMETHODIMP CHelloWorld::SayHello()
{
    USES_CONVERSION;

    // Get the network name of this computer
    TCHAR szComputerName[MAX_COMPUTERNAME_LENGTH + 1];
    DWORD dwSize = MAX_COMPUTERNAME_LENGTH + 1;

    if (!GetComputerName(szComputerName, &dwSize))
        return E_FAIL;    // failed to get the name of this computer

    // Say Hello to the client
    Fire_OnSayHello(T2OLE(szComputerName));

    return S_OK;
}

Listing 2. Code to add to finish the CHelloWorld::SayHello() member function.

That's it! We're finished with Step 5. Click Next to go on to Step 6, or click Back to step back to Step 4 if you're browsing through the tutorial. If you have any questions, try clicking on Questions and Answers to go to the page with the good stuff, and then e-mail me at brian@harttechservices.com if you're still stuck.

<< Back | Next >>

Questions and Answers

DCOM D-Mystified: A DCOM Tutorial, Step 5