windows-xp/Source/XPSP1/NT/printscan/ui/printui/printer.hxx

/*++

Copyright (C) Microsoft Corporation, 1995 - 1998
All rights reserved.

Module Name:

    printer.hxx

Abstract:

    The printer object handles all information regarding a print
    queue (and eventually server object).  The printer is not
    concerned with UI or listviews; it takes a printer name and
    returns via callbacks any changes of the printer state.

    The remote server notifies the local printer of changes through
    either a single DWORD (downlevel connections), or full change
    information (uplevel 3.51+ connections).  The TData object
    abstracts the changes for us.

Author:

    Albert Ting (AlbertT)  10-June-1995

Revision History:

--*/

#ifndef _PRINTER_HXX
#define _PRINTER_HXX

class TPrinter;

/********************************************************************

    MPrinterClient

********************************************************************/

class MPrinterClient : public VInfoClient, public MRefCom {

    SIGNATURE( 'prc' )

public:

    MPrinterClient(
        VOID
        ) : _pPrinter( NULL )
    {   }

    VAR( TPrinter*, pPrinter );

    /********************************************************************

        Retrieve selected items.  Used when processing commands against
        items or saving and restoring the selection during a refresh.

    ********************************************************************/

    virtual
    COUNT
    cSelected(
        VOID
        ) const;

    virtual
    HITEM
    GetFirstSelItem(
        VOID
        ) const;

    virtual
    HITEM
    GetNextSelItem(
        HITEM hItem
        ) const;

    virtual
    IDENT
    GetId(
        HITEM hItem
        ) const;

    //
    // kContainerReloadItems: pPrinter has just refreshed and so the
    //     client must invalidate the old pointers and use re-enumerate
    //     new items.
    //
    // kContainerClearItems: pPrinter has just zeroed its list of items,
    //     so the client must invalidate all old pointers.
    //
    virtual
    VOID
    vContainerChanged(
        CONTAINER_CHANGE ContainerChange,
        INFO Info
        ) = 0;

    virtual
    VOID
    vItemChanged(
        ITEM_CHANGE ItemChange,
        HITEM hItem,
        INFO Info,
        INFO InfoNew
        ) = 0;

    /********************************************************************

        VInfoClient virtual defaults.

    ********************************************************************/

    virtual
    VOID
    vSaveSelections(
        VOID
        );

    virtual
    VOID
    vRestoreSelections(
        VOID
        );

    virtual
    BOOL
    bGetPrintLib(
        TRefLock<TPrintLib> &refLock
        ) const = 0;
};

/********************************************************************

    Class definitions.

********************************************************************/


class TPrinter : public MExecWork, public MDataClient {

    SIGNATURE( 'prnt' )
    SAFE_NEW

public:

    /********************************************************************

        Public constants.

    ********************************************************************/

    enum _CONSTANTS {
        kOneSecond    = 1000,
        kSleepRetry   = 30 * kOneSecond,     // 30 sec. timeout
    };

    enum _EXEC {
#ifdef SLEEP_ON_MINIMIZE
        kExecSleep              = 0x0000001,
        kExecAwake              = 0x0000002,
#endif
        kExecError              = 0x0000004, // Error: don't try re-opening.
        kExecReopen             = 0x0000008,
        kExecDelay              = 0x0000010, // GetLastError set to error.
        kExecClose              = 0x0000020,
        kExecRequestExit        = 0x0000040,

        kExecNotifyStart        = 0x0000100,
        kExecRegister           = 0x0000200,
        kExecNotifyEnd          = 0x0000400,

        kExecRefresh            = 0x0001000,
        kExecRefreshContainer   = 0x0002000,
        kExecRefreshItem        = 0x0004000,
        kExecRefreshAll         = 0x0007000,

        kExecCommand            = 0x0010000,
    };

    enum EJobStatusString {
        kMultipleJobStatusString,           // Prepend job status string information
        kSingleJobStatusString,             // Don't prepend job status string information
    };
public:

    //
    // The sub-object that abstracts the type of remote printer from us.
    // (May have the polling notifications, single DWORD notifications,
    // or full information notifications.)
    //
    VAR( VData*, pData );
    VAR( TRefLock<TPrintLib>, pPrintLib );

    //
    // Initialized once, then read only; no guarding needed.
    // OR called by UI thread.
    //
    VAR( DWORD,  dwAccess );
    VAR( EJobStatusString, eJobStatusStringType );

    BOOL
    bValid(
        VOID
        ) const
    {
        return VALID_OBJ( PrinterGuard._strPrinter );
    }

    /********************************************************************

        Don't use the standard ctr and dtr to create and destroy these
        objects; instead, use these member functions.

        pNew - Returns a new printer object.

        vDelete - Request that the printer destroy itself when all
            pending commands (pausing printer, jobs, etc.) have completed.

    ********************************************************************/

    static
    TPrinter*
    pNew(
        MPrinterClient* pPrinterClient,
        LPCTSTR pszPrinter,
        DWORD dwAccess
        );

    VOID
    vDelete(
        VOID
        );

    const TString&
    strPrinter(
        VOID
        ) const
    {
        return PrinterGuard._strPrinter;
    }

    BOOL
    bSyncRefresh(
        VOID
        );

    /********************************************************************

        UI interface routines: the UI client calls through these
        functions for services.

        vCommandQueue - Allocate a command object and put it into the
            command queue (commands execute serially in a separate
            thread).

        vCommandRequested - Call when a new command has been added that
            requires a sleeping printer to re-awake.  This allows a
            refresh to take place even if the printer is sleeping in
            poll mode.

        vProcessData - Call when synchronous data must be processed.

    ********************************************************************/

    VOID
    vCommandQueue(
        TSelection* pSelection
        );

    VOID
    vCommandRequested(
        VOID
        );

    VOID
    vProcessData(
        DWORD dwParam,
        HBLOCK hBlock
        );

    LPTSTR
    pszPrinterName(
        LPTSTR pszPrinterBuffer
        ) const;

    LPTSTR
    pszServerName(
        LPTSTR pszServerBuffer
        ) const;

    /********************************************************************

        Generic exported services.

    ********************************************************************/

    static
    STATUS
    sOpenPrinter(
        LPCTSTR pszPrinter,
        PDWORD pdwAccess,
        PHANDLE phPrinter
        );

private:

    class TPrinterClientRef {
    public:

        TPrinterClientRef(
            const TPrinter* pPrinter
            );
        ~TPrinterClientRef(
            VOID
            );

        BOOL
        bValid(
            VOID
            ) const
        {
            return _pPrinterClient != NULL;
        }

        MPrinterClient*
        ptr(
            VOID
            )
        {
            return _pPrinterClient;
        }

    private:

        MPrinterClient* _pPrinterClient;
    };

    //
    // Guarded by TExec: one thread processing TPrinter at a time,
    // and/or guarded by state machine.
    //
    struct _EXEC_GUARD {

        VAR( HANDLE, hPrinter );

    } ExecGuard;

    //
    // All field in this structure guarded by gpCritSec.
    //
    struct PRINTER_GUARD {

        //
        // Written by Exec threads only; guarding not needed from
        // reading from ExecGuard places.
        //
        VAR( TString, strPrinter );
        VAR( TString, strServer );
        VAR( HANDLE, hEventCommand );
        VAR( DWORD, dwError );

        //
        // Only changed in UIThread.
        //
        VAR( MPrinterClient*, pPrinterClient );

        //
        // Linked list of commands to execute.
        //
        DLINK_BASE( TSelection, Selection, Selection );

    } PrinterGuard;

    /********************************************************************

        Ctr, dtr declared private so that clients are forced to use
        pNew, vDelete.

    ********************************************************************/

    TPrinter(
        MPrinterClient* pPrinterClient,
        LPCTSTR pszPrinter,
        DWORD dwAccess
        );

    ~TPrinter(
        VOID
        );

    /********************************************************************

        Status reporting.

    ********************************************************************/

    VOID
    vErrorStatusChanged(
        DWORD dwStatus
        );

    VOID
    vConnectStatusChanged(
        CONNECT_STATUS ConnectStatus
        );

    /********************************************************************

        Define virtual funcs for MExecWork:

        svExecute - A job is ready to execute and should run now in the
            current thread.

        vExecFailedAddJob - This printer object tried to add a job,
            but the add failed and we need to put up a suitable
            error message.

        vExecExitComplete - We requested an EXIT job and we are finally
            processing it now (the exit will wait until the currently
            pending job has completed).  This routine will delete
            the object.

    ********************************************************************/

    STATEVAR
    svExecute(
        STATEVAR StateVar
        );
    VOID
    vExecFailedAddJob(
        VOID
        );
    VOID
    vExecExitComplete(
        VOID
        );

    /********************************************************************

        Called by worker threads only; these operations may hit
        the network and therefore take a long time to complete.

    ********************************************************************/

#ifdef SLEEP_ON_MINIMIZE
    STATEVAR
    svAwake(
        STATEVAR StateVar
        );
#endif

    STATEVAR
    svSleep(
        STATEVAR StateVar
        );

    STATEVAR
    svRefresh(
        STATEVAR StateVar
        );
    STATEVAR
    svReopen(
        STATEVAR StateVar
        );
    STATEVAR
    svDelay(
        STATEVAR StateVar
        );
    STATEVAR
    svClose(
        STATEVAR StateVar
        );

    STATEVAR
    svRequestExit(
        STATEVAR StateVar
        );

    STATEVAR
    svNotifyStart(
        STATEVAR StateVar
        );
    STATEVAR
    svNotifyEnd(
        STATEVAR StateVar
        );
    STATEVAR
    svCommand(
        STATEVAR StateVar
        );


    /********************************************************************

        MDataClient virtual definitions.

    ********************************************************************/

    VOID
    vContainerChanged(
        CONTAINER_CHANGE ContainerChange,
        INFO Info
        );
    VOID
    vItemChanged(
        ITEM_CHANGE ItemChange,
        HITEM hItem,
        INFO Info,
        INFO InfoNew
        );

    VOID
    vSaveSelections(
        VOID
        );
    VOID
    vRestoreSelections(
        VOID
        );

    BOOL
    bGetPrintLib(
        TRefLock<TPrintLib> &refLock
        ) const;

    VDataNotify*
    pNewNotify(
        MDataClient* pDataClient
        ) const;

    VDataRefresh*
    pNewRefresh(
        MDataClient* pDataClient
        ) const;

    HANDLE
    hPrinter(
        VOID
        ) const;
    HANDLE
    hPrinterNew(
        VOID
        ) const;

    friend TPrinterClientRef;
};

#endif // ifndef _PRINTER_HXX