Quick View Execution and Error Conditions

Quick View Execution and Error Conditions

The lifetime of each instance of the Quick View program consists of the following steps:

1.When the user chooses the Quick View or Print command, the shell starts an instance of QUIKVIEW.EXE for each selected file (by using the Win32 CreateProcess or WinExec function). The shell may specify a show command, and Quick View passes the command to the file viewer. The command-line argument that the shell passes to Quick View has the following options.

Option	Meaning
-f:pathname	Path of the file to view or print. Universal Naming Convention (UNC) filenames are allowed. If this option is not specified, Quick View terminates without displaying any messages.
-v	File to be opened for viewing in the file viewer. If this option is specified, Quick View ignores all of the options described below. This is the default option in the absence of both -v and -p.
-d	Quick View and the file viewer to suppress all user interface (UI) elements if -p is also specified. Quick View suppresses any error messages, and the file viewer should not display any dialog boxes for printing. Quick View ignores this option in the absence of -p.
-p	File to be opened for printing. If -v is also present, Quick View ignores this option.
-&:pathname	Printer driver to use to print the file. Quick View ignores this option in the absence of -p. If -p is present but -& is not, Quick View instructs the file viewer to use the default printer driver.

2.Quick View starts and checks for a path on the command line. If there is no path, the user has attempted to start Quick View by itself and the program immediately terminates without displaying any messages.

3.Quick View parses the filename extension from the path given in the -f option. If no filename extension is given, Quick View proceeds to stage E1 (error condition 1). Otherwise, Quick View uses the following procedure to find a file viewer class identifier associated with the given filename extension.

a.Quick View attempts to open the HKEY_CLASS_ROOT\QuickView\extension key, where extension is parsed from the path.

If the filename extension maps to a type such as HKEY_CLASS_ROOT\extension = typename and there is a registry entry with the form HKEY_CLASS_ROOT\typename\QuickView = *, Quick View looks for file viewer class identifiers under HKEY_CLASS_ROOT\QuickView\*. If a key with the HKEY_CLASS_ROOT\*\QuickView = * form exists, the system attempts to use all the viewers listed under the "*" section.

ii.

Otherwise, Quick View begins enumerating the file viewer class identifiers under the HKEY_CLASS_ROOT\QuickView\extension key. If the enumeration fails (that is, there is nothing in the registry to enumerate), Quick View closes the key and proceeds to stage E2. Otherwise, Quick View reads the first file viewer class identifier in the enumeration and proceeds to step 4.

b.If an error occurs in step 4, the enumeration continues until all file viewer class identifiers have been tried. If no file viewer is activated, Quick View closes the key from (a) and proceeds to stage E2.

4.Given a class identifier of a file viewer DLL, Quick View attempts to create an instance of a file viewer object of the given class by using the following procedure.

a.Quick View calls a function to create an instance of a file viewer object, specifying parameters that include the class identifier and the IID_IPersistFile interface identifier. This instructs OLE to load the DLL listed under the class identifier's InprocServer32 subkey, obtain an instance of the object from the DLL, and return an IPersistFile interface pointer to the object. If the instance cannot be created because of lack of memory, Quick View proceeds to stage E4. If it fails for some other reason, Quick View proceeds to stage E3. (Note that, because DLL objects are involved, any call to QueryInterface will not fail with REGDB_IID_NOTREG, which typically signals a corrupted registry. That error is generated only when LRPC proxies and stubs are involved.)

b.Given the IPersistFile interface pointer pIPersistFile, Quick View calls the Load member function of the IPersistFile interface, specifying the path of the file and the STGM_READ and STGM_SHARE_DENY_NONE values, which instruct the object to open the file for read access. If Load fails, Quick View calls the Release member function of pIPersistFile and proceeds to stage E4 if the error is due to a lack of memory. Otherwise, Quick View proceeds to stage E3.

c.Quick View obtains the file viewer object's IFileViewer interface by specifying the IID_IFileViewer interface identifier in a call to the QueryInterface member function of pIPersistFile. Quick View calls the Release member function of pIPersistFile, regardless of the outcome. If this call fails due to lack of memory, Quick View proceeds to stage E4. Otherwise, Quick View proceeds to stage E3.

d1.If the -v option was present or both the -v and -p options were absent, Quick View calls the ShowInitialize member function of pIFileViewer, which instructs the file viewer to load the file and perform any preshowing initialization that is prone to failure (including the creation of windows, the loading of resources, and so on). This is the file viewer's one chance to fail. If it fails, Quick View proceeds to stage E4 if the error is due to lack of memory or to stage E3 otherwise. If ShowInitialize succeeds, Quick View calls the Show member function of pIFileViewer, specifying the show command that was passed to Quick View's WinMain function. Show does not return until the user closes the file viewer, and it always returns NOERROR in that case. If Show is called before ShowInitialize, it returns E_UNEXPECTED.

d2.If the -p option was present (and the -v option was absent), Quick View calls the PrintTo member function of pIFileViewer specifying the path of the printer driver provided in the -& option (or NULL if -& was absent) and a value indicating if the -d option was present on the command line (UI suppression flag). PrintTo does not return until printing is complete or an error occurs. If an error occurs, the file viewer is responsible for notifying the user if the UI suppression flag is FALSE.

e.When Show or PrintTo returns (whichever was called in steps d1 or d2), Quick View calls the Release member function of pIFileViewer, regardless of the return value. If the file viewer successfully executed the IFileViewer::ShowInitialize member function, the Release member function will not fail. Release fails only if it is called before ShowInitialize. If PrintTo fails but the -d option was not specified on the command line, Quick View assumes that the file viewer displayed a message to indicate printing failed, and Quick View fails without displaying a message in that case. In any case, Quick View proceeds to step 5.

5.Quick View releases any interface pointers it may have had and calls OleUninitialize. Quick View then terminates normally.

Quick View may encounter these four error conditions (stages E1 through E4) during the lifetime of an instance.

E1.If Quick View fails to associate the path with a file viewer class identifier (using a filename extension), it displays this message.

There are no viewers for this type of file. Would you like to try the default viewers.

If the user clicks No, Quick View terminates. If the user clicks Yes, Quick View displays the Searching dialog box, enumerates all registered file viewers (regardless of file type or filename extension ), and attempts to have each one load and display the file. Quick View tries each file viewer of a given class identifier once. If no file viewer successfully displays the file, Quick View removes the Searching dialog box and displays this message.

Error opening or reading file.

When the user closes the dialog box, Quick View terminates.

E2. If Quick View successfully determines the file type but fails to enumerate any file viewers associated with the filename extension, it displays the Searching dialog box and attempts to have each registered viewer display the file, trying each file viewer class identifier once. If that fails, the Quick View removes the Searching dialog box and displays this message.

There are no viewers capable of viewing <human-readable document type> files.

When the user closes the dialog box, Quick View terminates.

E3.If Quick View successfully locates an initial file viewer but fails to view the file for any reason other than an out of memory condition, Quick View displays the Searching dialog box and continues enumerating viewers under the class identifier or filename extension key currently in use (steps 3d or 4c). If Quick View tries all viewers registered for the type unsuccessfully, processing continues as in stage E2 by trying all registered viewers regardless of registered type.

E4.If an out of memory condition occurs for one file viewer, it is likely that other viewers will not succeed either. In that case, Quick View displays a dialog box (using MB_ICONEXCLAMATION) with this message.

There is not enough memory to view or print <filename>. Quit one or more files or programs, and then try again.

A file viewer can return a number of error values to Quick View. When Quick View receives an error value, it displays an error message. Quick View recognizes the following error values.

FV_E_BADFILE ((HRESULT)0x8534E102L)
FV_E_EMPTYFILE((HRESULT)0x8534E108L)
FV_E_FILEOPENFAILED((HRESULT)0x8534E105L)
FV_E_INVALIDID((HRESULT)0x8534E106L)
FV_E_MISSINGFILES((HRESULT)0x8534E104L)
FV_E_NOFILTER((HRESULT)0x8534E100L)
FV_E_NONSUPPORTEDTYPE((HRESULT)0x8534E101L)
FV_E_NOVIEWER ((HRESULT)0x8534E10AL)
FV_E_OUTOFMEMORY((HRESULT)0x8534E107L)
FV_E_PROTECTEDFILE((HRESULT)0x8534E109L)
FV_E_UNEXPECTED((HRESULT)0x8534E103L)