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.
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
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
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.
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
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
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);
The declaration of the
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:
TCHAR szComputerName[MAX_COMPUTERNAME_LENGTH + 1];
DWORD dwSize = MAX_COMPUTERNAME_LENGTH + 1;
if (!GetComputerName(szComputerName, &dwSize))
Code to add to finish the
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 email@example.com if you're still stuck.
<< Back | Next >>
Questions and Answers