Tutorial Home
Previous Lesson
Lesson List
Next Lesson
|
|
COM Tutorial Samples |
Tutorial Home |
Previous Lesson |
Lesson List |
Next Lesson |
The READTUT sample builds a simple READTUT.EXE application that is used as the main utility for reading the online tutorial for the COM Tutorial Samples. The TUTORIAL.EXE utility, found in the main tutorial directory, is produced in this sample. To do this, a copy of READTUT.EXE is simply renamed to TUTORIAL.EXE and placed in the main tutorial directory where it provides the main tutorial entry for the entire lesson series.
This lesson illustrates:
For functional descriptions and a tutorial code tour of READTUT, see the Code Tour section in READTUT.HTM. For details on the external user operation of READTUT, see both the Usage and Operation sections in READTUT.HTM. To read READTUT.HTM, run TUTORIAL.EXE in the main tutorial directory and click the READTUT lesson in the table of lessons. You can also achieve the same thing by clicking the READTUT.HTM file after locating the main tutorial directory in the Windows Explorer.
For details on setting up your system to build and test the code samples in this COM Tutorial series, see Building the Code Samples. The supplied makefile (MAKEFILE) is Microsoft NMAKE-compatible. To create a debug build, issue the NMAKE command in the Command Prompt window.
For convenient use in Microsoft's Visual Studio, a project file is provided for each sample. To load the project for the READTUT sample, you can run Visual Studio at the Command Prompt in the sample's directory as follows:
MSDEV READTUT.DSP
You can also simply double-click the READTUT.DSP file in the Windows Explorer to load a sample's project into Visual Studio. From within Visual Studio you can then browse the C++ classes of the sample source and generally perform the other edit-compile-debug operations. Note that, as part of the Platform SDK, the compilation of these samples from within Visual Studio requires the proper setting of directory paths in Visual Studio. For more details, see Building the Code Samples.
READTUT.EXE is an application that you can run directly from Windows or from the Command Prompt. READTUT can be run in one of the following forms.
READTUT
Launches the Web browser to read file READTUT.HTM in the same
directory as the executing READTUT.EXE. If READTUT.EXE is renamed to
TUTORIAL.EXE then file TUTORIAL.HTM will be read in the same manner.
READTUT MyHTMLFile.HTM
Launches the Web browser to read file MyHTMLFile.HTM in the main
tutorial directory. This directory is assumed to be the parent of
the directory where READTUT.EXE is executing.
READTUT MySiblingDir\MyHTMLFile.HTM
Launches the Web browser to read MyHTMLFile.HTM in the MySiblingDir
directory that is a sibling to the directory where READTUT.EXE is
executing.
READTUT //www.mycompany.com
Launches the Web browser with URL internet address
http://www.mycompany.com.
READTUT.EXE must be compiled before you can run it. For more details on building the samples, see Building the Code Samples.
If you have already built the READTUT sample, you can simply run READTUT.EXE in a command window. A small tutorial home page, READTUT.HTM, is provided in the READTUT sample directory. This test page is viewed by READTUT.EXE when it is run.
The READTUT application operates transparently except when an error occurs. If an error occurs, a modal error dialog box is displayed with one of the following errors:
READTUT.EXE: COM initialization failed. READTUT.EXE: Can't find HTM file. READTUT.EXE: Can't run browser.
Files Description
READTUT.TXT Short description of sample.
READTUT.HTM Short sample HTML home page for testing READTUT.EXE.
MAKEFILE The generic makefile for building the code sample.
READTUT.H The include file for the READTUT application. Contains
string literals and Resource identifiers.
READTUT.CPP The main implementation file for READTUT.EXE. Has WinMain.
READTUT.RC The application resource definition file.
READTUT.ICO The application icon resource.
READTUT.DSP Microsoft Visual Studio Project file.
The READTUT.EXE utility in this lesson is used to launch the system Web browser on a specified (or asssumed) HTML Web page file. READTUT is so simple that no main window or message loop is required. The only user interface that might be encountered is a set of message dialog boxes to notify the user of progress or error conditions.
The main content of the program is in READTUT.CPP. The following fragment contains the declaration files included.
/*-------------------------------------------------------------------------
We include WINDOWS.H for all Win32 applications.
We include OLE2.H because we will be calling the COM/OLE Libraries.
We include APPUTIL.H because we will be building this application using
the utility functions in the APPUTIL Library (ie, APPUTIL.LIB).
We include READTUT.H because it has resource definitions specific to
this tutorial application.
-------------------------------------------------------------------------*/
#include <windows.h>
#include <ole2.h>
#include <apputil.h>
#include "readtut.h"
WINDOWS.H is included because this is a Win32 Windows application. OLE2.H is included because calls will be made to such COM/OLE functions as CoInitialize and CoUninitialize. APPUTIL.H is located in the common sibling include directory, INC. It is included by almost all samples in this series as a very thin Win32 application framework. APPUTIL also contains many utility functions that are used to help samples expose their inner behavior for tutorial purposes. See APPUTIL.HTM for details. READTUT.H is included for resource IDs and string literals that are unique to READTUT.
All the work of READTUT is done in the WinMain function in READTUT.CPP.
extern "C" int PASCAL WinMain(
HINSTANCE hInstance,
HINSTANCE hPrevInstance,
LPSTR pszCmdLine,
int nCmdShow)
{
int iFail = FALSE;
LPSTR psz;
char ch;
if (SUCCEEDED(CoInitialize(NULL)))
{
// Show a message box saying that loading of tutorial is underway.
DelayBox(hInstance, MAKEINTRESOURCE(IDD_LOADING_MSG), NULL);
/*--------------------------------------------------------------------
Walk down the command line looking for an HTML target. The first
non-whitespace character after whitespace is assumed to be the
beginning of the HTML target specification. This can be a fully
qualified internet URL or a path/filename. This is all done in ANSI
because pszCmdLine is in ANSI. Any command line switches are
skipped and ignored.
--------------------------------------------------------------------*/
psz = pszCmdLine;
while (ch = *psz)
{
BOOL bStop = FALSE;
switch (ch)
{
case '\t':
case '\n':
case '\r':
case ' ':
// Skip any white space.
psz = SkipAnsi(psz, TRUE);
continue;
case '/':
// Handle '/' switches here. If '//' then assume it's a URL.
ch = *(++psz);
if ('/' == ch)
{
--psz;
bStop = TRUE;
break;
}
else
{
// If any '/' switches found skip to next white space.
psz = SkipAnsi(psz, FALSE);
continue;
}
case '-':
// If any '-' switches found skip to next white space.
psz = SkipAnsi(psz, FALSE);
continue;
default:
bStop = TRUE;
break;
}
if (bStop)
break;
psz++;
}
if (0 == ch)
{
/*------------------------------------------------------------------
If the command line has no HTML target specified then assume a
file with name [thismodulename].HTM in the same directory as this
executing EXE. In this case, the assumed file is READTUT.HTM. Call
the APPUTIL ReadTutorial utility function to Browse this HTML
file. If READTUT.EXE is renamed to TUTORIAL.EXE then the assumed
file to browse is TUTORIAL.HTM.
------------------------------------------------------------------*/
ReadTutorial(hInstance, NULL, NULL);
}
else
{
// If the command line has an HTML target specified then use it
// to call the APPUTIL GoWeb utility function to Browse to the
// specified HTML file on the world wide Web.
GoWeb(hInstance, psz);
}
// We're exiting this app so shut down the COM Library.
CoUninitialize();
}
else
{
// Show error message box if we can't initialize the COM libraries.
MessageBox(NULL,
TEXT(NOCOM_ERROR_STR),
TEXT(ERROR_TITLE_STR),
MB_OK | MB_ICONEXCLAMATION);
iFail = TRUE;
}
return iFail;
}
Because this application will likely make calls to COM services, the program calls COM's CoInitialize function to initialize the COM service libraries. This CoInitialize call must be paired with a matching CoUninitialize call that is made above near the end of WinMain.
The program displays a simple message box for several seconds to notify the user that the Web browser is being launched. The DelayBox utility function in APPUTIL is called to do this. Notice that a dialog resource from the executing READTUT module is used for the buttonless dialog that appears. That dialog definition is found in READTUT.RC and is identified by the IDD_LOADING_MSG resource ID. That ID is #defined in include file READTUT.H. The Win32 MAKEINTRESOURCE macro is used to convert an ID number into a resource name string which the DelayBox function requires to specify a dialog template.
The program then scans its own command line to determine the kind of HTML target that the Web browser will be directed to browse.
With the psz string pointer variable assigned to point to the command line input argument string, the above while loop in WinMain uses the SkipAnsi function to skip white space and any command line switches. The SkipAnsi function is a utility function defined in the APPUTIL library. SkipAnsi can either skip over whitespace characters or skip over non-whitespace characters. This is determined by the value of TRUE or FALSE for the second parameter. Note that SkipAnsi only accepts ANSI character string pointers. This is because the pszCmdLine command line string is available to WinMain only in ANSI regardless of whether this program is compiled for Unicode. See APPUTIL.HTM for more details on SkipAnsi.
The program then calls either the APPUTIL ReadTutorial or GoWeb functions based on whether an HTML target was specified on the command line. When ch == 0 above then no target was specified.
The ReadTutorial function launches the Web browser to read a specified .HTM file. ReadTutorial is in the APPUTIL library. ReadTutorial calls another APPUTIL function, ReadHelp, to perform the actual launch of the Web browser. Here is ReadHelp from APPUTIL.CPP in the sibling APPUTIL directory.
void ReadHelp(
HWND hWndOwner,
LPTSTR pszHelpFile)
{
int iRes;
if (NULL != pszHelpFile)
{
// First check if the .HTM help file is there at all.
if (FileExist(pszHelpFile))
{
// Use shell to invoke web browser on the HTML help file.
iRes = (int) ShellExecute(
hWndOwner,
TEXT("open"),
pszHelpFile,
NULL,
NULL,
SW_SHOWNORMAL);
if (iRes <= 32)
{
// If unable to browse then put up an error box.
HrMsg(hWndOwner, TEXT(NOBROWSE_ERROR_STR), E_FAIL);
}
}
else
{
// If the .HTM file doesn't exist the put up an error box.
iRes = MessageBox(
hWndOwner,
TEXT(NOHTM_ERROR_STR),
TEXT(ERROR_TITLE_STR),
MB_OK | MB_ICONEXCLAMATION);
}
}
return;
}
Using a call to the Win32 ShellExecute function, ReadHelp uses the operating system Shell to launch the current system Web browser on a specified HTML file. This action relies on a current file type association that establishes an installed Web browser as the agent that handles .HTM files. It assumes that a Web browser is installed and that the file association was set up during the install process.
Usually the READTUT.EXE program will have no target specified on the command line. In such a case, APPUTIL's ReadTutorial function is called with a NULL for the HTML target parameter. As a result, ReadTutorial determines the path and file name of the EXE in which it is executed and uses that information to construct the path and name of the target HTML file. Thus, if READTUT.EXE resides in directory D:\MSSDK\SAMPLES\COM\TUTSAMP\READTUT it will launch the Web browser to view the file D:\MSSDK\SAMPLES\COM\TUTSAMP\READTUT\READTUT.HTM. Such a small HTML page is provided as file READTUT.HTM in the READTUT sample directory. This initial HTML page is the entry to a potentialy large tutorial.
As another example, if READTUT.EXE is copied to directory D:\MSSDK\SAMPLES\COM\TUTSAMP, renamed to TUTORIAL.EXE, and executed, then TUTORIAL.EXE will launch the Web browser to browse file D:\MSSDK\SAMPLES\COM\TUTSAMP\TUTORIAL.HTM. This is what was actually done to provide TUTORIAL.EXE in the main tutorial directory of this sample series. TUTORIAL.EXE is just a renamed copy of READTUT.EXE.
The program calls GoWeb when an HTML target was specified on the READTUT command line. The GoWeb function accepts a pointer to an ANSI string that specifies the target HTML file. If the target is of the form //www.mycompany.com, then GoWeb detects this and launches the Web browser using a complete world wide Web internet URL address of the form http://www.mycompany.com. If the specified target string does not have a leading '//' then a full path and file name for the local file system is assumed and GoWeb launches the Web browser using that full specification.
Back to page top