//+-------------------------------------------------------------------------
//
// Microsoft Windows
//
// Copyright (C) Microsoft Corporation, 1995 - 1996
//
// File: overview.hxx
//
//--------------------------------------------------------------------------
/*++
Overview of printui structure
=============================
Client usage:
-------------
The print user interface is a separate library that can be linked
into either shell32.dll or printui.exe for independent and quick
testing.
To use this library, the user simply loads the dll. In
DllEntryPoint routine, the library is intializes itself.
To create a print queue window, the client calls:
VOID
vQueueCreate(
LPCTSTR pszPrinter,
INT nCmdShow
)
Note that this all does not fail: it occurs asynchronously. If base
initialization fails, then a message box is put up immediately with
an error.
If the printer fails to open for whatever reason (such as unknown
printer), then the window is left open and shows an error message
in both the title and status bar.
Note: this is the only public interface to creating a queue.
Programming goals:
------------------
There goals in order of priority are:
1. Correctness (no bugs, robust)
2. Maintainability (clean architecture, readable, extensible)
3. Portable (should run on win9x)
4. Responsive (UI should never hang)
5. Small working set
6. Fast
Naming conventions:
-------------------
As a general rule, hungarian notation is used. Also, the nouns
a placed before the verbs (PrinterCreate rather than CreatePrinter).
Class names are prefixed with the following characters:
Type Inheritance
---- -----------
V - Virtual 0 or 1 (Types|Virtual), 0 or more Mix-ins.
T - Type 0 or 1 (Types|Virtual), 0 or more Mix-ins.
M - Mix-in 0 or more Mix-ins.
Multiple inheritance is allowed, but this structure prevents
cycles from appearing.
Macros:
-------
ALWAYS_VALID - indicates the object is always valid, and creates
an inline bValid( VOID ) function that returns TRUE.
SIGNATURE( '1234' ) - Places a signature in an object. The bytes
are reversed so that a dc displays the name correctly. Also
creates an inline function bSigCheck() that ensures the object
matches the signature.
VAR( Type, name ); - Creates the field variable (prefixed by '_')
and 'get' function (Type name();) that retrieves the variable.
DLINK_BASE( Type, name, linkname ); - Creates the head base pointer
for double-linked list.
DLINK( Type, name ); - Creates a dlink entry and inline functions
to manipulate the link (functions prefixed with "name_.")
REF_LOCK( Type, name ); - Create a reference lock that acquires
and releases a VRef object. The reference count is appropriately
incremented and decremented.
( Debug macros )
SINGLETHREAD( dwThreadId ); - The first time this is called,
initializes dwThreadId to the current thread. Subsequent
calls assert that the current thread is the same as dwThreadId
(this first one).
Library intialization:
----------------------
When the dll is loaded, the window classes are registered and the
libraries are initialized.
Queue Creation:
---------------
When the user calls vQueueCreate the following occurs:
Internal structure notes:
-------------------------
There are three main classes:
TQueue: The highest level queue object
This maintains the listview and user interface elements.
It maintains a reference to a TPrinter.
TPrinter: Single interface to printer objects
This handles retrieving printer data and sending
asynchronous printer commands.
VData: Abstracts client notifications and information retrieval.
There are two types of notifications: notification that
something changed, and actual data. This class presents
a uniform interface to TPrinter, and holds all job information.
Given that virtually everything executes asynchronously, (including
commands), destruction of queues must be handled carefully:
TPrintLib: This is referenced counted, and once all print queues
have been destroyed, this object deletes itself.
Each queue holds a ref count. When all queues are destroyed,
the ref count reaches zero and vRefZeroed() is called.
At this point we tell TThreadM to start shutting down by
calling TThreadM::vDelete.
TQueue: Since this is tied to the user interface, it only lives
while the UI window is open, or there it is processing
a notification (there is a refcount).
It notifies the its TPrinter that the UI is going away, so
that the TPrinter does not notify the queue.
TPrinter: This receives it's notification to delete via vDelete().
It disassociates itself from the TQueue then queues itself
with commands to close then delete.
After all other commands are processed, it deletes the TData
object.
VData: This is simply a data repository, so it does not require
any special shutdown code.
The following classes are used by the print folder to retrieve info
about printers on a server.
TFolder: Analagous to TQueue for print queues. It will have
either (1 TConnectionNotify, 1 TDSServer, 0+ TDSConnection)
or (1 TDSServer). The former case represents the local
print folder where we must watch local printers + connections +
check if any connections are added or deleted. The latter
represents a remote printer folder (we don't need to
watch connections).
VDataSource: A single source of printers.
TDSConnection: derived from VDataSource. Represents a single
printer connection (always enumerates and returns one printer.)
TDSServer: derived from VDataSource. Represents a server, which
may have multiple printers.
TConnectionNotify: Watches the registry to see if printer
connections are added or removed.
Printer States:
The printer state is represented with a by a DWORD--the top
three bits. Each action can modify the bits to transition to
a new state.
EXEC_AWAKE
Print queue was restored (from iconized state), so
notifications should start up again.
EXEC_SLEEP
Print queue minimized; shut down notifications.
?? Even in the minimized state, it should show whether
the printer is paused. But if notifications are shut
down, how will it update this? We could reduce notification
level just to status, which would cut down on traffic but
still give us Paused informations.
EXEC_ERROR
An error occurred such that the TPrinter should not be
re-opened until the user explicitly hits refresh. This
occurs when the printer name is invalid, or access is
denied.
EXEC_REOPEN
Open printer with maximal access.
From states:
ALL
EXEC_DELAY
GetLastError() must be valid!
Sleep for a while when there's an error. It will decrement
_uFailCount in case it wants to retry a second time before
giving up.
This will also create an event in case the user tries to
refresh while it's sleeping.
From states:
ALL
EXEC_CLOSE
Closes printer object.
From states:
ALL
EXEC_REQUESTEXT
Request that the printer shut down.
From states:
ALL
EXEC_NOTIFYSTART
Begin the notification process--calls VData.svNotifyStart.
From states:
NOTIFYEND, EXEC_REOPEN (printer must be valid)
EXEC_NOTIFYEND
Ends the notification--calls VData.svNotifyEnd. When the
user minimizes the printer, we will close the notification
so that we won't eat network bandwidth when no one's looking.
From states:
NOTIFYSTART, REFRESH, COMMAND
EXEC_REFRESH
Refresh the object.
From states:
COMMAND, NOTIFYSTART
EXEC_REFRESH_PRINTER
EXEC_REFRESH_JOBS
Extra state bits used for TDataRefresh only.
EXEC_COMMAND
Execute a command.
From states:
Columns vs. Indicies
--------------------
A column is the UI ListView column, while an index is an index
into the TData information.
Column: Index:
DOCUMENT DOCUMENT
STATUS_STRING STATUS_STRING
USER_NAME USER_NAME
STATUS <- specific to Index only.
Sequence of notifications
-------------------------
The data notifications are abstracted into the VData object.
Full refresh
In the downlevel case, no information is sent back with
a notification, so the entire queue must be refreshed.
Partial refresh
For uplevel, data is sent back, and single jobs are changed.
The following describes how a notification is processed. There
are two main issues that result this complex system: first,
the data must be processed in the UI thread so that we don't
deal with dangling data. Second, we want to keep the TPrinter,
TQueue, TData and TData* classes as separate as possible.
1. Notification system signals event, indicating something
changed and we must be updated.
2. Notify thread (there is a single thread for all printers
(unless there are > 63 queues, in which case multiple
threads are used)) picks up the changed event and
MNotifyWork::vProcessNotifyWork is called. This must
process the request very quickly, since other printers
use this thread too.
a. For TDataRefresh, this routine adds a refresh job
that will be executed in a separate thread.
b. For TDataNotify, FindNextPrinterChangeNotification
is called to retrieve the update. Since FFPCN does
not hit the network, it executes quickly.
3. If there is data available from the notification, the
thread calls Printer.vRequestBlockProcess which cals
the Queue object with the request. The data block is
totally encapsulated in the hBlock.
4. The Queue object posts a message to the queue, allows the
message to be processed synchronously in the UI thread.
All data is accessed from the UI thread. The message
indicates whether state (which jobs are selected, which
has focus) should be saved.
5. When the message is received by the UI thread, it is
sent to TQueue.
a. If the state must be preserved the JobIds are saved.
b. The TData* is sent the Block which must be
processed.
1. If a job must be modified, it updates the data then
notifies the Queue that the job must be repainted.
2. If a new job has come in, it is added to the data
structure, then the Queue is notified that a job
must be inserted into the list view.
3. If a job is deleted, the Queue is notified before the
item is deleted, since the list view may reference
the job data.
c. If necessary, the state is restored (generally done
if the list view was reconstructed).
6. The data block is freed.
Singleton class
-------------------------
A Sington class is a class which can have only one instance during the life of the
program, however, it may have multiple referenced to this class. TPrinterDriverSetup is
singleton class. This class is used to allow acccess to the DriverSetup information.
The DriverSetup information is expensive to create and does not change during the life of
the program. The TPrinterDriverSetup::bInstance function is a static function which is used
by users of this class to obtain a reference to it. bInstance takes one argument the address
where to return a reference to the singlton class and returns a boolean if a valid instance is
returned. TPrinterDriverSetup::vDelete() is used to release an instance of the singleton class.
There should be a matching number of bInstance() and vDelete() calls, to insure proper cleanup
of the singleton class.
--*/