Field Testing DCOM

You're going to create a very simple COM server and client to experiment with DCOM. This server will be able to return the name of the remote host computer and its current date/time.

The server will be packaged as an EXE binary. You won't use a DLL packaged server because it requires a surrogate program running on the server computer to work out-of-process. The example will use type library marshaling to avoid the registration of a proxy/stub marshaling DLL. You can refer to http://msdn.microsoft.com for a variety of articles that can help you get a better understanding of COM marshaling. For the purposes of this chapter, just think of it as packaging function parameters for transmission over the network.

Creating the Server Application

You're free to create whatever directory structure you want, but it is a good idea to use a main folder with two subfolders named Server and Client for this project.

You can find the code for the example server application in the EasyDCOM\Server folder on the CD-ROM that accompanies this book.

To create the server application, do the following:

Launch C++Builder.
Select File, New, Application from the main IDE menu.
Save the project in the Server folder as EasyDCOM.bpr renaming Unit1.cpp to MainUnit.cpp .
Switch to the main project's form.
Press F11 to activate the Object Inspector.
Type frmMain at the Name Property.
Design your project's main form to look like the screen in Figure 18.9.

Figure 18.9. The EasyDCOM main form.
Select File, New from the main menu.
Switch to the ActiveX tab.
Double-click Automation Object. The New Automation Object dialog will appear.
Type HostInfo in the CoClass Name field.
Enter Easy DCOM Type Library 1.0 in the Description field and click OK.
Select View, Type Library to bring the Type Library Editor (TLE) to the front.
On the left pane, select the IHostInfo interface.
From the TLE toolbar, click the New, Property button down arrow, and select Read Only from its pop-up menu.
Rename Property1 to Info .
On the right pane, select the Parameters tab and change Parameters type to BSTR* (see Figure 18.10).

Figure 18.10. The TLE editor showing the read-only property info.
Press the Refresh button in the TLE editor to update the source files.

Switch to the HostImpl.cpp file and add the following code to the get_Info() method:

 STDMETHODIMP THostInfoImpl::get_Info(BSTR* Value)  {      try {          char lpBuffer[MAX_COMPUTERNAME_LENGTH + 1];          unsigned long nSize = sizeof(lpBuffer);          if (GetComputerName(lpBuffer, &nSize) == 0)              return HRESULT_FROM_WIN32(GetLastError());          WideString strVal = AnsiString().              sprintf("Date and time at %s is: %s",              lpBuffer, DateTimeToStr(Now()));          *Value = strVal.Detach();      }      catch(Exception &e) {          return Error(e.Message.c_str(), IID_IHostInfo);      }      return S_OK;  };

Press F9 to compile and run the server.

Have a look at the code for the Info property of your EasyDCOM server.

You start by calling the Win32 API function GetComputerName() to store the computer name in the lpBuffer variable returning the appropriate HRESULT on error.

Then, you instantiate a WideString object based on the computer name and its current date and time.

You invoke the Detach() method of the WideString object to release ownership from the underlying BSTR because COM states that an out parameter has to be released by the client, not the server. Detach() relinquishes ownership over the returned string.

Creating the Client Application

You can find the code for the example client application in the EasyDCOM\Client folder on the CD-ROM that accompanies this book.

To create the client application, do the following:

Start a new application and save the project in the Client folder as EasyDCOMClient.bpr , renaming Unit1.cpp to MainUnit.cpp .

Design your project's main form, adding the necessary components to look like the screen in Figure 18.11. When done, rename your components as follows :

Figure 18.11. The `EasyDCOMClient` main form and its components.

graphics/18fig11.gif

Original Name	New Name
`Form1`	`frmMain`
`GroupBox1`	`gbxLocal`
`GroupBox2`	`gbxRemote`
`Edit1`	`txtLocal`
`Edit2`	`txtRemote`
`Button1`	`cmdInfo`
`Button2`	`cmdFinish`

Open EasyDCOMClient.cpp and add the following:
```
 USEUNIT("..\Server\EasyDCOM_TLB.cpp"); 
```
Open MainUnit.h and add the following:
```
 #include "..\Server\EasyDCOM_TLB.h" 
```
Take advantage of C++Builder technology by declaring a smart interface variable to your EasyDCOM server.

Add the following code under TfrmMain class private section:
```
 TCOMIHostInfo m_objHost; 
```

Edit the project's main form source code and add the following code to its constructor:

 char lpBuffer[MAX_COMPUTERNAME_LENGTH + 1];  unsigned long nSize = sizeof(lpBuffer);  GetComputerName(lpBuffer, &nSize);  txtLocal->Text = AnsiString().sprintf("Date and time at %s is: %s",                                        lpBuffer, DateTimeToStr(Now()));

C++Builder also provides us a creator class that has static methods for creating local and remote instances of your object.

Double-click the cmdInfo button and add the following code to its OnClick event:

 if (!m_objHost.IsBound()) {      AnsiString strHost;      if (InputQuery("Create Server", "Enter computer name:",          strHost)) {          if (strHost.IsEmpty())              OleCheck(CoHostInfo::Create(m_objHost));          else              OleCheck(CoHostInfo::CreateRemote(WideString(strHost),                                                m_objHost));          WideString strValue;          OleCheck(m_objHost.get_Info(&strValue));          txtRemote->Text = strValue;      }  }

Double-click the cmdFinish button and add the following code to its OnClick event:
```
 Close(); 
```
Click the project's main form, press F11 to activate the Object Inspector, and switch to its Events tab. Double-click the OnClose event and write the following code:
```
 m_objHost.Unbind(); 
```
Press F9 to compile and run the client. Click the Go Get button to display the Create Server dialog. When asked for the machine name, leave it blank and click OK to create the server locally.

Let's review the code for the client application.

The constructor code for the main form retrieves and shows the name of the local computer and its date and time.

The handler code for the cmdInfo button calls the IsBound() method on the smart interface object verifying whether the server object is already instantiated and proceeds accordingly .

The InputQuery() function receives the NETBIOS name, DNS name, or IP address of the remote machine and stores it in the strHost variable.

If strHost is then empty, the server is locally instantiated using the Create method; otherwise , the CreateRemote() method accepts the machine name or IP address stored in strHost and tries to instantiate the server at the specified machine. OleCheck() is used to verify the returned HRESULT , throwing an exception on fail.

The get_Info() method is invoked passing the address of a WideString variable. This variable is then filled with information returned from the hosting machine, and its value is shown in the txtRemote edit control.

Before closing the form, the Unbind() method of the smart interface object is invoked to release the server.

Now it's time to move your EasyDCOM sample to another machine on the network. Copy EasyDCOM.exe to a local drive on the remote machine and run it once to perform self-registration.

NOTE

If you choose a Windows 9X machine to host your server, it won't be able to automatically launch the server; you'll have to launch it manually.

Configuring Launch and Access Permissions

Let's assume, for the sake of your discussion, that the remote and client machines participate in a Microsoft network domain.

You're going to grant launch permission to anyone participating on the network, so proceed as follows:

Run DCOMCnfg.exe and double-click Easy DCOM Type Library 1.0 from the Applications tab list box. On XP, use the Component Services Administrative Tool from the Control Panel, and pick Component Services, Computers, My Computer, DCOM Config. Using this tool is outside the scope of this chapter, but information can be found in the help file.
For Windows 2000 and NT, go to the Security tab and select Use Custom Launch Permissions. Click the Edit button, and then the Add button. Double-click the built-in account Everyone , and then click OK (see Figure 18.12). This states that anyone on the network can now load and run the server, but you still need to grant access to its services.

Figure 18.12. Granting Launch Permission to the Everyone account.
From the Security tab, select Use custom access permissions. Click the Edit button, and then the Add button. Select the local or domain account to which you want to grant access permission, and then click OK (see Figure 18.13).

Figure 18.13. Granting access permission to a selected account.

Configuring Identity

You're going to choose which account the server will use when running. The best option, as mentioned previously, is to select This User and enter an account that gives the server all the necessary privileges it needs when running.

Go to the Identity tab (refer to Figure 18.8). Select This user and enter or browse for the username. Enter the password, confirm it, and click OK.

Running the Example

What have you accomplished in terms of DCOM security for your sample application?

First, you allowed anyone to launch your server. Then, you selected the user or group of users that have clearance to access your server. Finally, you solved the identity problem of your server by specifying the account it would use when running.

Now you're now ready to go.

Start EasyDCOMClient.exe on the client machine, click the Go Get button, and enter the remote machine name or IP address when asked. You should see something like the screen in Figure 18.14.

Figure 18.14. `EasyDCOMClient` talking to its server on a remote machine.

graphics/18fig14.gif

Top

Creating the Server Application

Figure 18.9. The EasyDCOM main form.

Figure 18.10. The TLE editor showing the read-only property info.

Creating the Client Application

Figure 18.11. The EasyDCOMClient main form and its components.

Configuring Launch and Access Permissions

Figure 18.12. Granting Launch Permission to the Everyone account.

Figure 18.13. Granting access permission to a selected account.

Configuring Identity

Running the Example

Figure 18.14. EasyDCOMClient talking to its server on a remote machine.

Figure 18.11. The `EasyDCOMClient` main form and its components.

Figure 18.12. Granting Launch Permission to the `Everyone` account.

Figure 18.14. `EasyDCOMClient` talking to its server on a remote machine.