00386: DDE topics and items for web browsers
Title:
DDE topics and items for web browsers
Description:
Generic Verbs
Since this is a platform-independent specification, all details about the semantics and parameters of individual verbs are provided in this section. Any details unique to a given platform and/or transport mechanism can be found in the appropriate section.
Each verb in the API is listed by name and direction (is it sent TO or FROM the Web browser), along with a list of its arguments, return value (if any), and a description of its semantics. Optional arguments are enclosed in [square brackets]. For ease of reference, verbs are grouped into four categories. Verbs in the first two categories, basic and utility, are all sent TO the Web browser. The third category comprises messages FROM the Web browser, which are sent only if you register to receive them. The fourth category comprises progress messages, which can be sent TO or FROM Web browsers.
Basic Verbs
The basic functionality that an external application usually requires from the Web browser is to retrieve and/or render Web documents.
OpenURL ( TO Web browser )
URL,
[FileSpec],
WindowID,
Flags,
[FormData],
[MIMEType],
[ProgressApp],
[ResultApp]
Returns: TransactionID
Retrieves URL off the Web, either to dump to a file (FileSpec) or display in a given WindowID. Passing OpenURL a WindowID of 0 tells the Web browser to open a new window. WindowID -1 refers to the front window. Valid Flags settings include any combination of the following:
1. Ignore the document cache
2. Ignore the image cache
4. Operate in background mode
Additional options allow for the posting of forms (FormData) of a given MIMEType. If specified, ProgressApp can be named to handle the user interface for progress messages.
Immediately returns a unique TransactionID. When the requested URL has been accessed and all associated documents loaded, the Web browser will issue an OpenURLResult to the ResultApp. If ResultApp is empty, it indicates that the application does not care about the return value, and therefore, no OpenURLResult will be issued.
A TransactionID of 0 means that the requested URL is already in the document window, -1 means that the data was not of an appropriate MIME type to display in a Web browser window, and -2 means that the application should consider the operation to have succeeded (Super-ACK). In all three cases, no OpenURLResult will be issued.
A TransactionID of -3 means that an invalid URL was specified, -4 means that an invalid output filename was specified, and -5 means that an invalid protocol was specified. In all three cases, the operation failed and no OpenURLResult will be issued.
OpenURLResult ( FROM Web browser )
TransactionID,
ActualWindowID
This verb is issued when all Web browser processing initiated by the OpenURL associated with TransactionID has completely finished.
Indicates the ActualWindowID the document was displayed in, where a value of 0 means that the operation failed, and -1 means that the data was not of an appropriate MIME type to display in a Web browser window.
ShowFile ( TO Web browser )
FileSpec,
MIMEType,
WindowID,
URL,
[ResultApp]
Returns: TransactionID
Passes FileSpec containing data of a given MIMEType to be rendered in a given WindowID. Also specified is a URL which allows this document to be reloaded if needed.
Immediately returns a unique TransactionID. When the requested URL has been accessed and all associated documents loaded, the Web browser will issue an ShowFileResult to the ResultApp. If ResultApp is empty, it indicates that the application does not care about the return value, and therefore, no ShowFileResult will be issued.
A TransactionID of 0 means that the requested URL is already in the document window, -1 means that the data was not of an appropriate MIME type to display in a Web browser window, and -2 means that the application should consider the operation to have succeeded (Super-ACK). In all three cases, no ShowFileResult will be issued.
A TransactionID of -3 means that an invalid URL was specified. In this case, the operation failed and no ShowFileResult will be issued.
ShowFileResult ( FROM Web browser )
TransactionID,
ActualWindowID
This verb is issued when all Web browser processing initiated by the ShowFile associated with TransactionID has completely finished.
Indicates the ActualWindowID the document was displayed in, where a value of 0 means that the operation failed, and -1 means that the data was not of an appropriate MIME type to display in a Web browser window.
CancelTransaction ( TO Web browser )
TransactionID
Returns: Success
Tells the Web browser to cancel a TransactionID in progress which the application had initiated via an OpenURL or ShowFile command. Applications can only cancel transactions which they have initiated.
Immediately returns a Success flag. Success = TRUE means that the transaction will be canceled and no OpenURLResult or ShowFileResult (as appropriate) will be issued. Success = FALSE means that the requested TransactionID cannot be cancelled by this application.
Utility Verbs
These are some additional utility verbs which may be useful to Web browser-aware applications.
QueryVersion ( TO Web browser )
VersionMajor,
VersionMinor
Returns: BrowserVersionMajor, BrowserVersionMinor, UserAgent
Tells the Web browser that an application which wishes to communicate with it supports a specific Version (Major . Minor) of this SDI specification.
Returns the maximum BrowserVersion (Major . Minor) supported by this Web browser (subject to the constraint that BrowserVersion is less than or equal to Version). A BrowserVersion of 0.0 means that no common version is available. Also reports the browser’s HTTP UserAgent information.
Activate ( TO Web browser )
WindowID,
Flags
Returns: ActualWindowID
Tells the Web browser to bring itself to the front and show WindowID. Flags are reserved for future expansion, and should be set to 0.
Upon completion, returns ActualWindowID, where a value of 0 means that the operation failed.
ListWindows ( TO Web browser )
Returns: (list of WindowID’s)
Returns a list of WindowID’s for each window currently being used by the Web browser. These WindowIDs are synthetic, and do not necessarily have any platform-specific significance.
GetWindowInfo ( TO Web browser )
WindowID
Returns: (list of Window info)
Returns a list of Window info items for WindowID, namely the URL and window Title.
ParseAnchor ( TO Web browser )
MainURL,
RelativeURL
Returns: URL
Combines a base URL (MainURL) and a relative URL (RelativeURL) to produce a fully-specified URL.
Exit ( TO Web browser )
Tells the Web browser to shut down and exit. Used by scripting applications which want to control the Web browser as a slave process. Generally not needed.
Registered Verbs
A tighter level of integration between the Web browser and other applications can be achieved if there is a two-way flow of information back and forth between the applications.
Messages are sent FROM the Web browser only if you register to receive them, via the RegisterProtocol, RegisterViewer, RegisterURLEcho, RegisterWindowClose, or RegisterAppClose verbs. Verbs sent FROM the Web browser are listed between the relevant Register and UnRegister events.
Applications which have registered to receive messages from the Web browser must unregister when they are shut down. The Web browser will not automatically unregister viewers, protocol handlers, etc.
RegisterNow ( FROM Web browser )
BrowserApp,
TransactionID
Returns: Timeout
Tells applications which wish to register themselves that BrowserApp is a Web browser which can now be communicated with via this interface. Passes a unique TransactionID to be used by the matching RegisterDone message, if any.
Returns a Timeout value, indicating the amount of time (in seconds) the application will need to register itself. If the application does not send a RegisterDone message within Timeout seconds, the Web browser will assume that the registration has failed. A Timeout of 0 means that the application will not register itself.
RegisterDone ( TO Web browser )
TransactionID,
Result
This verb is issued when all application processing initiated by the RegisterNow associated with TransactionID has finished.
Indicates the Result of the operation, where a value of 0 means that the operation failed, and a value of 1 means that the operation succeeded. A value of 2 means that the operation ran out of time. At the Web browser’s discretion, another RegisterNow operation may then be started.
RegisterProtocol ( TO Web browser )
Application,
Protocol
Returns: Success
Notifies the Web browser that Application is ready to handle all URLs for a given Protocol, such as MAILTO, NEWS, etc.
If multiple apps attempt to register a given protocol, only the first one succeeds (Success = TRUE).
OpenURL ( FROM Web browser )
URL,
[FileSpec],
WindowID,
Flags,
[FormData],
[MIMEType],
[ProgressApp],
[ResultApp]
Returns: TransactionID
Passes URL for this protocol application to handle. The FileSpec and WindowID are made available to be passed back to the Web browser as part of a nested ShowFile call. The FormData and MIMEType fields can either be used by the application and/or passed back to the Web browser as part of a nested OpenURL call. Flags are reserved for future expansion. If specified, ProgressApp can be named to handle the user interface for progress messages.
Immediately returns a unique TransactionID. When the requested URL has been accessed and all associated documents loaded, the application will issue an OpenURLResult to the ResultApp. If ResultApp is empty, it indicates that the Web browser does not care about the return value, and therefore, no OpenURLResult will be issued.
A TransactionID of 0 means that the requested URL is already in the document window, -1 means that the data was not of an appropriate MIME type to display in a Web browser window, and -2 means that the application should consider the operation to have succeeded (Super-ACK). In all three cases, no OpenURLResult will be issued.
A TransactionID of -3 means that an invalid URL was specified, and -4 means that an invalid output filename was specified. In both cases, the operation failed and no OpenURLResult will be issued.
OpenURLResult ( TO Web browser )
TransactionID,
ActualWindowID
This verb is issued when all protocol application processing initiated by the OpenURL associated with TransactionID has completely finished.
Indicates the ActualWindowID the document was displayed in, where a value of 0 means that the operation failed, and -1 means that the data was not of an appropriate MIME type to display in a Web browser window.
CancelTransaction ( FROM Web browser )
TransactionID
Returns: Success
Tells the protocol application to cancel a TransactionID in progress which the Web browser had initiated via an OpenURL command. Web browsers can only cancel transactions which they have initiated.
Immediately returns a Success flag. Success = TRUE means that the transaction will be canceled and no OpenURLResult will be issued. Success = FALSE means that the requested TransactionID cannot be cancelled by this Web browser.
UnRegisterProtocol ( TO Web browser )
Application,
Protocol
Notifies the Web browser that Application no longer wishes to receive Protocol URLs.
————————————————————————
RegisterViewer ( TO Web browser )
Application,
MIMEType,
Flags
Returns: Success
Notifies the Web browser that Application is ready to handle all MIMEType documents. The Flags may be any of the following values:
1. Save to a temporary file and use platform-specific OpenDocument event
2. Use QueryViewer
4. Always use ViewDocFile
8. Always use ViewDocData
If multiple apps attempt to register a given MIMEType, only the first one succeeds (Success = TRUE). RegisterViewer dynamically overrides any relevant user- or OEM-configured viewers.
QueryViewer ( FROM Web browser )
URL,
MIMEType
Returns: FileSpec
Asks the application handling MIMEType documents where it wants a temporary copy of the document associated with URL to be stored. The reply should be provided in FileSpec.
This allows the application to handle deletion of unused tempfiles, so that the Web browser doesn’t delete them out from under it.
If the application does not specify a FileSpec in response to a specific QueryViewer message, then the Web browser will handle the creation and/or deletion of a tempfile for that URL as appropriate, and the application must not delete the file passed to it in the subsequent ViewDocFile message.
ViewDocCache ( FROM Web browser )
URL,
WindowID
Returns: Success
Asks a registered viewer if has a copy of URL in its own internal cache. If so, the application is expected to immediately render the document and then return Success = TRUE). If not, return Success = FALSE so that the Web Browser or another registered viewer can process the URL.
The WindowID attribute is passed along to let the application know which Web browser window generated this request. This allows the application to pass the same WindowID back to the Web browser in related requests.
Note that this message may get sent to multiple registered viewers, at the discretion of the Web browser.
ViewDocData ( FROM Web browser )
URL,
MIMEType,
WindowID,
(actual data)
Tells the application handling MIMEType documents to render the (actual data) which was obtained from URL. The WindowID attribute is passed along to let the application know which Web browser window generated this request. This allows the application to pass the same WindowID back to the Web browser in related requests.
ViewDocFile ( FROM Web browser )
FileSpec,
URL,
MIMEType,
WindowID
Tells the application handling MIMEType documents to render the data in FileSpec which was obtained from URL. The WindowID attribute is passed along to let the application know which Web browser window generated this request. This allows the application to pass the same WindowID back to the Web browser in related requests.
UnRegisterViewer ( TO Web browser )
Application,
MIMEType
Notifies the Web browser that Application no longer wishes to receive MIMEType documents.
————————————————————————
RegisterURLEcho ( TO Web browser )
Application
Returns: Success
Notifies the Web browser that Application would like to receive URLEcho events for all windows.
Multiple apps can be concurrently registered to receive URLEcho events.
URLEcho ( FROM Web browser )
URL,
MIMEType,
WindowID,
[ReferrerURL]
Tells the application that the Web browser just loaded a URL of a given MIMEType to WindowID. Also mentions the ReferrerURL it was launched from, for use by mapping apps.
In certain cases, such as when a URL is processed by another application, the MIMEType may be unknown, and thus will be represented as an empty string. A WindowID of -1 means that the Web browser didn’t wind up displaying the URL in one of its own windows.
UnRegisterURLEcho ( TO Web browser )
Application
Notifies the Web browser that Application no longer wishes to receive URLEcho events.
————————————————————————
RegisterWindowClose ( TO Web browser )
Application,
WindowID
Returns: ActualWindowID
Notifies the Web browser that Application would like to receive WindowClose events from WindowID. Upon completion, returns ActualWindowID, where a value of 0 means that the operation failed.
WindowClose ( FROM Web browser )
WindowID,
Exiting
Tells the application that WindowID just closed. Also indicates whether this happened because the Web browser is Exiting (value = TRUE), or because of user interface operations.
Since WindowIDs are unique, and not reused when a window is closed, the Web browser will also perform an automatic UnRegisterWindowClose for that WindowID.
UnRegisterWindowClose ( TO Web browser )
Application,
WindowID
Notifies the Web browser that Application no longer wishes to receive WindowClose events from WindowID.
————————————————————————
RegisterAppClose ( TO Web browser )
Application
Returns: Success
Notifies the Web browser that Application would like to receive an AppClose event. Upon completion, returns Success, where a value of 0 means that the operation failed.
AppClose ( FROM Web browser )
Tells the application that the Web browser is exiting.
UnRegisterAppClose ( TO Web browser )
Application
Notifies the Web browser that Application no longer wishes to receive an AppClose event from the Web browser.
Progress Verbs
The application that handles the processing of a given URL may be different from the application which handles the user interface for presenting the results of that processing. Thus, it will sometimes be necessary to delegate the handling of progress indicators such as message lines, progress thermometers, spinning globes, etc. to another application. The following messages can be used to delegate the user interface handling of progress indicators for a specific transaction to a specific window in another application.
This family of messages can potentially be sent either TO or FROM the Web browser during processing of the relevant OpenURL event.
BeginProgress ( TO or FROM Web browser )
TransactionID,
Message
Returns: Success
Initializes a progress indicator for an existing OpenURL TransactionID with an initial Message.
If multiple apps attempt to control the same progress indicator, only the first one succeeds (Success = TRUE).
SetProgressRange ( TO or FROM Web browser )
TransactionID,
Max
Sets a Max value for the progress indicator associated with TransactionID. The range begins at 0 and extends upwards. Setting a Max value of 0 hides the progress indicator.
MakingProgress ( TO or FROM Web browser )
TransactionID,
Message,
Current
Returns: Cancel
Updates the progress indicator associated with TransactionID to reflect the Current value. Will also change the Message displayed, unless that field contains an empty string, in which case the current message is preserved.
Returns a flag indicating whether the user wishes to Cancel the transaction. Upon receipt of Cancel = TRUE, the application which sent this message should abort processing and then send an EndProgress message. Progress-monitoring applications which don’t allow users to interrupt lengthy transactions will always return Cancel = FALSE.
EndProgress ( TO or FROM Web browser )
TransactionID
Notifies the application that the progress indicator associated with TransactionID is no longer needed.
Last Modified: 03/31/1998 Product: Visual PRO/5 Operating System: Windows
BASIS structures five components of their technology into the BBx Generations.