Previous Page TOC Next Page See Page



— 3 —
Interfacing To The Web With DDE and OLE


Much like other Windows-based applications, most Web browsers support OLE automation and DDE control. In this chapter, we go through the methods and syntax of controlling the Netscape Web browser from a Visual Basic program using these technologies. The most typical uses for this are to retrieve the current URL from the browser or to cause the browser to load a specific URL.

This chapter assumes you have some knowledge of both DDE and OLE Automation. If you need a refresher, there are many introductory texts that go into detail on these topics. Likewise, the VB help file provides a good introduction to both topics.

Manipulating Netscape Navigator using DDE


The complete documentation (as of March 22, 1995) of Netscape's DDE Implementation can be found at http://home.netscape.com/newsref/std/ddeapi.html. In the following sections, I will describe and outline the DDE topics (which are simply names for data elements available via DDE) exposed by Netscape Navigator.

Netscape can act as both a DDE client and a server, depending on which topics are used. It is important to remember that if you use any of the topics that make use of Netscape as the client, your application needs to register itself as a DDE server. The service name used for Netscape Navigator during DDE conversations is NETSCAPE.

WWW_Activate


The WWW_Activate topic maximizes Netscape if it is minimized, or it brings a Netscape window to the front of all other applications and gives it focus.

WWW_Alert


In this topic, Netscape acts as the client. Netscape passes to the server application three parameters, qcsMessage, dwType, and dwButtons:

0x0

Error Alert Dialog

0x1

Warning Alert Dialog

0x2

Question Alert Dialog

0x3

Status Alert Dialog


0x0

OK button only

0x1

OK and Cancel buttons

0x2

Yes/No buttons

0x3

Yes/No/Cancel buttons


The value returned by WWW_Alert is held in dwAnswer, the valid responses are:

0x0

Error : the alert box could not be displayed

0x1

The OK button was pressed

0x2

The Cancel button was pressed

0x3

The No button was pressed

0x4

The Yes button was pressed



WWW_BeginProgress


In the WWW_BeginProgress topic, Netscape acts as the client. The two arguments, dwWindowID, the ID of the Netscape window that is loading a document, and qcsInitialMessage, which is a message that the DDE server displays to indicate that Netscape has begun to load the document.

When a DDE application provides Netscape with a DDE server name in the WWW_OpenURL topic, Netscape sends progress indicators to that DDE server.

This topic returns the ID of the window that replies with progress topics that are used in other progress topics that will be sent to the DDE server. If WWW_BeginProgress returns 0X0, the DDE server no longer accepts other progress topics from Netscape

WWW_CancelProgress


The single argument to WWW_CancelProgress topic is the Transaction ID. The Transaction ID is the return value from the WWW_BeginProgress topic. The WWW_CancelProgress topic tells Netscape to cancel the download for that specific Transaction ID.

WWW_EndProgress


WWW_EndProgress notifies the DDE server that Netscape is finished loading a URL. This does not necessarily mean that Netscape has completely loaded the URL, rather that Netscape has quit trying to load the URL either due to an error or that the URL has been completely loaded.

WWW_Exit


WWW_Exit causes Netscape to attempt to exit. Netscape exits unless an OLE Automation application is blocking Netscape from exiting. Netscape windows that aren't involved in the OLE operation will close, however. Any argument passed to the WWW_Exit topic is not ignored.

WWW_GetWindowInfo


The argument to WWW_GetWindowInfo is the Netscape window ID or 0xFFFFFFFF (that's eight "efs") that specifies the last active Netscape window. This returns the URL and the title of the page that is currently loaded in the Netscape window.

WWW_ListWindows


WWW_ListWindows returns an array of double length words holding the window IDs. The array is terminated by the null character (0x0). If a Netscape window is minimized, it is not reported as a window. Any argument provided to the WWW_ListWindows topic is ignored.

WWW_MakingProgress


In this topic, Netscape passes the following parameters to the DDE server application:

The DDE server application should return a Boolean value: True if Netscape should stop loading that URL; False otherwise.

WWW_OpenURL


The WWW_OpenURL is called as both a client and a server topic between Netscape and the other DDE-enabled application. When Netscape acts as the server, the following are the arguments sent by the client application:

0x1

Ignore the chached documents when loading the URL.

0x2

Ignore the chaced images when loading the URL.

0x4

Do the loading of the URL in the background.


Netscape returns the window ID of the Netscape window that is servicing the request to open the URL. A return value of 0x0 indicates failure; 0xFFFFFFFF indicates that the data loaded is of a MIME type that Netscape cannot display.

Netscape, acting as a client, can also use WWW_OpenURL to request that a DDE application load a URL. The following are the arguments sent from the Netscape window to the DDE application:

The DDE application should return 0x0 if the operation failed, 0xFFFFFFFF if the URL data was not accepted by the DDE application, and any other value to indicate to Netscape that the operation has been successful.

WWW_ParseAnchor


In the WWW_ParseAnchor topic, the absolute URL and relative URL is sent to Netscape, which acts as the DDE server. Then Netscape returns the combined URL to the DDE client application.

WWW_QueryURLFile


Here, Netscape acts as the DDE server. The client application passes Netscape a path and filename that might have been loaded by Netscape during that session. Netscape returns the URL of that file if it was loaded during that session. If the file was not loaded, the topic fails.

WWW_QueryViewer


In WWW_QueryViewer, Netscape sends the URL that it is currently loading and the MIME content type of the URL. The DDE server application should return to Netscape the fully qualified path and filename to which Netscape should save the file.

WWW_RegisterProtocol


WWW_RegisterProtocol is used by the DDE client application to tell Netscape that it will handle URLs of a certain protocol type. The first argument passed is the DDE server that will be handling the URL for the specified protocol. The second argument is the protocol to be handled. Netscape returns a Boolean value indicating success or failure of registration. The topic fails if a DDE server is currently registered to handle that protocol.

Whenever Netscape encounters a URL using the protocol specified, it acts as a DDE client and uses the WWW_OpenURL topic to request that the registered server load the URL.

WWW_RegisterURLEcho


This topic from the DDE client application notifies Netscape that it should send WWW_URLEcho topics when they occur. The single argument to Netscape is the name of the DDE server application that will be notified.

WWW_RegisterViewer


WWW_RegisterViewer allows a DDE application to register itself with Netscape to receive data of a specified MIME type.

The DDE application sends Netscape the following arguments:

0x1

Indicates that the data received should be saved to a temporary file, and then the routine ShellExecute() should be called.

0x2

Finds the filename to use for storing the data received by using the WWW_QueryViewer topic.

0x4

Saves the data received to a temporary file and then calls the WWW_ViewDocFile topic.

0x8

WWW_ViewDocData|WWW_ViewDocCache[el] (Undefined as yet).


Netscape either returns a Boolean True or False: True indicates that the registration process has completed successfully. False means that there is already another DDE server application registered to receive that MIME type.

WWW_RegisterWindowChange


In WWW_RegisterWindowChange, the DDE application sends two arguments to Netscape: First, the name of the DDE server that wants to be informed of Netscape window changes, and, second, the Netscape window ID that will be "watched" for changes.

Netscape returns a double word holding the window ID of the Netscape window that informs the DDE application of changes. This is usually the same as the window ID that is passed as the second argument to the topic.

WWW_SetProgressRange


In the WWW_SetProgressRange topic, Netscape sends to the DDE application two arguments:

The DDE application doesn't need to furnish Netscape with a return value.

WWW_ShowFile


In the WWW_ShowFile topic, the DDE application sends to Netscape the following arguments:

Netscape returns the window ID of the Netscape window that is loading the file. If 0x0 is returned, this indicates that the call to the ShowFile topic failed. If 0xFFFFFFFF is returned by Netscape, the file is not of a MIME type that Netscape can display.

WWW_UnRegisterProtocol


In WWW_UnRegisterProtocol, the DDE application passes to Netscape the name of the server application that no longer wants to handle a protocol, and the second parameter is the protocol type. Netscape returns a Boolean True if the topic has been successful; false otherwise.

WWW_UnRegisterURLEcho


With WWW_UnRegisterURLEcho, the DDE application passes to Netscape the name of the server application that no longer wants to receive WWW_URLEcho topic notifications from Netscape. There are no return arguments.

WWW_UnRegisterViewer


In WWW_UnRegisterViewer, the DDE application sends to Netscape the name of the server that should be unregistered for a given MIME type. The second argument is that MIME type. Netscape returns a Boolean value: True, if the operation has been successful; false otherwise.

WWW_UnRegisterWindowChange


The DDE application sends to Netscape, the server that doesn't want WWW_WindowChange topics sent to it and the window ID of the Netscape window that should no longer be monitored.

Netscape replies with Boolean True if the topic has been successful; false otherwise.

WWW_URLEcho


Each time Netscape loads a URL, it sends WWW_URLEcho to all DDE server applications that are registered via WWW_RegisterURLEcho.

Netscape sends the following arguments:


WWW_Version


WWW_Version allows the DDE application to query Netscape about its version. Any argument the DDE application sends to Netscape is ignored. Netscape replies with a double word holding the version of the API currently in use by Netscape.

WWW_ViewDocFile


In WWW_ViewDocFile, Netscape sends to the DDE application the following arguments:


WWW_WindowChange


WWW_WindowChange can treat Netscape as both a DDE client and a DDE server. When Netscape acts as the client, Netscape sends to the DDE server application the following arguments:

0x00000001

The Netscape window has changed position or size, or both.

0x00000002

The Netscape window has been maximized.

0x00000004

The Netscape window has been normalized.

0x00000008

The Netscape window has been minimized.

0x00000010

The Netscape window has been closed.

0x00010000

The Netscape window is attempting to exit.


When Netscape acts as the server application, the DDE client can request the window to do any of the following: move, resize, minimize, maximize, or close.

The arguments to Netscape using the WWW_WindowChange topic are

0x00000001

Netscape should change position to the values contained in following arguments.

0x00000002

The Netscape window should maximize.

0x00000004

The Netscape window should normalize.

0x00000008

The Netscape window should minimize.

0x00000010

The Netscape window should close.


The following arguments must be specified if the operation on the Netscape window is to reposition or resize the window:


Grabbing the URL and Page Name from Netscape Using DDE


An example of using DDE would be to retrieve the currently loaded URL and page name from Netscape into a textbox. You can accomplish this by the following sample application.

Start with a plain form and add a textbox and a command button, as shown in Figure 3.1.

Figure 3.1. Design-time view of the Netscape-DDE test application.

Then, by setting the multiline property of the textbox to true and inserting the code in Listing 3.1 in the Click event of the command button, the textbox will request the URL and page title from Netscape.

Listing 3.1. The command button's click event.

Text1.LinkTopic = "NETSCAPE|WWW_GetWindowInfo"
Text1.LinkItem = &HFFFFFFFF
Text1.LinkMode = 2
Text1.LinkRequest

Figure 3.2 shows what is displayed when Netscape has loaded the Netscape home page, and the command button of the Visual Basic application has been pressed.

Figure 3.2. Runtime view of the Netscape-DDE test application.

Although it is possible to write Visual Basic applications that control Netscape using DDE, the preferred method is using OLE Automation. The remainder of this chapter looks into using OLE Automation to add control of Netscape to your applications.

Using OLE Automation to Control Netscape Navigator


In the beginning, there was DDE—and only DDE—for Windows interprocess communication. Its successor, OLE Automation, is a much nicer solution to this problem of getting applications to work cooperatively.

Exposing Netscape in Visual Basic 4.0


To get a look at the methods exposed by Netscape, select Tools | References, click on Browse, and then select the NETSCAPE.TLB file in the Netscape Program directory.

Then open the Object Browser and select Netscape from the drop-down combo box. The classes and modules for Netscape then appear, as shown in Figure 3.3.

Figure 3.3. Netscape's TLB file as viewed by the Object Browser.

Notice that the following items appear in the Classes/Modules box of the Object Browser: CNetworkCX, COleRegistry, INetwork, and IOleRegistry.

Now, if you look in the documentation, available at http://home.mcom.com/newsref/std/oleapi.html, the documented classes are Network.1 and Registry.1.



Confused yet? For some reason, the classes exposed in the NETSCAPE.TLB file do not line up with the documentation. The classes in the documentation work fine, so ignore the information in the Object Browser and go with what the documentation says.

A possible reason for this may be a syntax change between Netscape 1.1 and Personal Netscape 2.01. The documentation was written for 1.1, the author has 2.01.

So, stick with what's documented, and everything should work just fine.

The OLE-Exposed Classes and Functions of Netscape


The two classes Netscape exposes via OLE are Netscape.Network.1 and Netscape.Registry.1. The Network grouping of methods provides foreign applications the ability to use the functionality of Netscape from within that application. The Registry grouping of functions allows non-Netscape programs to register themselves as Netscape plug-ins to handle specific MIME types.

The Methods of the Netscape.Network.1 Class

This section describes the methods exposed by the Netscape.Network.1 class.

BytesReady()

The BytesReady() function is passed no arguments. Netscape returns a short integer containing the number of bytes that are available to be read from Netscape using the Read() function.

Close()

The Close() function, which is passed with no arguments and returns nothing, disconnects any active Netscape connections and resets the Netscape.Network.1 object.

This function is used either to terminate an active download or to indicate when the application is finished with the load from a previous call to the Open() function.

GetConnectEncoding()

GetConnectEncoding() passes no arguments and returns a string containing the MIME type of the currently loaded or loading document. This function should only be called if Open() is successful.

GetContentLength()

GetContentLength() returns the total length of the currently loaded document in bytes as a long integer. This function should only be called if Open() is successful.

GetContentType()

GetContentType() returns the MIME type of the currently loaded document as a string. This function should only be called if Open() is successful.

GetErrorMessage()

If a call to GetStatus() indicates that an error has occurred, use GetErrorMessage() to retrieve the Netscape-generated error message. The error message is returned as a string.

GetExpires()

The return value of GetExpires() is the time and date of when the data received by the current load is no longer considered valid.

GetFlagFancyFTP()

A call to GetFlagFancyFTP() returns a Boolean value: True if FTP output contains the additional listing information (file size, file type, last modified date, and so forth); False otherwise.

GetFlagFancyNews()

This function returns a Boolean value: True, if Netscape displays only newsgroups with descriptions; False to display all newsgroups.

GetFlagShowAllNews()

GetFlagShowAllNews() returns a Boolean value: True, to list all news articles; False to list only unread articles.

GetLastModified()

A call to GetLastModified() returns a string containing the time and date that the current load was last modified.

GetPassword()

GetPassword() returns a string—the currently set password from a previous call to SetPassword(). A null string is returned if no password has been specified.

GetServerStatus()

If a server error occurs, which can be detected by a call to GetStatus(), use GetServerStatus() to retrieve the error code reported by the server.

The function call returns the error code from the server as a short integer. The values of these error codes are dependent on the protocol that is being used.

GetStatus()

This function returns the status of the current load as a long integer. The GetStatus() function is only useable between the time of the call to Open() and the call to Close().

The return value is a long integer that contains a masked variable. The following are the individual components that make up the masked values and their respective meanings:

0x0000

Everything is normal.

0x0001

Netscape has requested a user name.

0x0002

Netscape has requested a user password.

0x0100

Netscape is busy; the operation can be retried.

0x0200

The server has reported an error; make a call to GetServerStatus() for the error code.

0x0400

An internal load error has occurred; the attempted contact to the server failed.

0x0800

Netscape has raised an internal error; use a call to GetErrorMessage() for the details.



GetUserName()

A call to GetUserName() returns the currently set user name as a string. Unless this value has been set by a call to SetUsername(), this function returns the null string.

IsFinished()

This function returns a Boolean value: True if the load is complete; False otherwise.

Open()

The Open() method causes Netscape to attempt to open an URL. The parameters passed to the function are as follows:

0x0

GET

0x1

POST

0x2

HEAD


The function call returns a Boolean True if the operation has been successful; False otherwise.

Read()

Read() is used to collect the data retrieved by Netscape. The arguments to the Read() function are

The Read() function returns a short integer containing the amount of data in bytes that was read from Netscape.

Resolve()

This function builds a fully qualified URL from the base and relative URLs. The following are the arguments to the Resolve() function:

The function returns a string containing the fully qualified URL.

SetFlagFancyFTP()

This function takes a single Boolean argument. True informs Netscape that the FTP file listings contain the extra FTP information; False indicates that only the filenames are listed.

SetFlagFancyNews()

The SetFlagFancyNews() function takes a single Boolean argument. True tells Netscape that it should include the newsgroup descriptions. False leaves them out.

SetFlagShowAllNews()

SetFlagShowAllNews() takes a single Boolean argument. True tells Netscape to display both read and unread news articles; False makes Netscape display only the unread articles.

SetPassword()

The SetPassword() function takes a single string argument. This password value is used by Netscape for any loads that require user name/password authentication.

SetUsername()

SetUsername() sets the user name used for authentication. The argument is passed to the function as a string.

The Methods of the Netscape.Registry.1 Class

This section discusses the methods for the Registry class. This class performs functions similar to the DDE topics WWW_RegisterViewer and WWW_RegisterProtocol.

RegisterViewer()

The RegisterViewer() method is used by an OLE Automation Server to notify Netscape that an external viewer will be handling certain MIME types. The arguments to this function include the following:

The function returns a Boolean True if the registration has been successful; it returns False if a server already is registered for that MIME type.

RegisterProtocol()

The RegisterProtocol() function acts like the RegisterViewer() function. The one difference is that RegisterProtocol() registers an OLE server to handle a specific protocol instead of a MIME type. The arguments to the RegisterProtocol() function are


Summary


By using OLE or DDE, you can add control of the user's browser into your Visual Basic application. The potential applications are as wide open as the Web itself. You could easily use OLE to use a Visual Basic program to monitor the sites a user visits during the browsing session, or to ensure that the person using the browser doesn't visit specified URLs. (Could you imagine if every boss had a list of the pages his or her employees visited?)

What's Next?


From here, we move on to harnessing the power of the Internet by using custom controls. In Chapter 4, "Using Custom Controls for WWW Programming," you'll learn about third-party tools that enable your Visual Basic application to harness the power of the Internet. Then in Chapter 5, "Retrieving Web-Based Information," we look into using the dsSocket control to retrieve Web content. In later chapters, you'll use those controls to integrate the content of the Web into our own applications.

Previous Page Page Top TOC Next Page See Page