windows-server-2003/printscan/wia/core/server/drvwrap.h

/*******************************************************************************
*
*  (C) COPYRIGHT MICROSOFT CORP., 2000
*
*  TITLE:       drvwrap.h
*
*  VERSION:     1.0
*
*  AUTHOR:      ByronC
*
*  DATE:        6 Nov, 2000
*
*  DESCRIPTION:
*   Declarations and definitions for the WIA driver wrapper class.
*   It faciliates JIT loading/unloading of drivers and provides an extra layer
*   of abstraction for WIA server components - they don't deal directly with
*   driver interfaces.  This is to make us more robust and implement smart
*   driver handling.
*
*******************************************************************************/

//
// Device types, Copied from stipriv.h
//
#define HEL_DEVICE_TYPE_WDM          1
#define HEL_DEVICE_TYPE_PARALLEL     2
#define HEL_DEVICE_TYPE_SERIAL       3

//
// "Internal" device states.  This is used to mark what state we think the device 
//  is in, mainly to tell the difference between active and inactive devices.
//  We need to mark this state in case it changes, so we can generate the
//  appropriate event (e.g. if state changes from inactive to active, we'd want to
//  generate a connect event).
//  NOTE:  If any flags get added here, be sure to update the 
//  MapCMStatusToDeviceState(..) function in wiadevman.cpp to carry over any needed
//  bits from the old state to the new one.
//
#define DEV_STATE_DISABLED              0x00000001
#define DEV_STATE_REMOVED               0x00000002
#define DEV_STATE_ACTIVE                0x00000004
#define DEV_STATE_CON_EVENT_WAS_THROWN  0x00000008

//
// "Internal" device types.  Notice that mass storage cameras are represented 
//  differently to other mass storage devices.  These "normal" mass storage
//  devices (like card readers), are marked with the INTERNAL_DEV_TYPE_VOL
//  flag, whereas the MSC cameras are marked with INTERNAL_DEV_TYPE_MSC_CAMERA.
//
#define INTERNAL_DEV_TYPE_REAL          0x00000001
#define INTERNAL_DEV_TYPE_VOL           0x00000002
#define INTERNAL_DEV_TYPE_INTERFACE     0x00000004
#define INTERNAL_DEV_TYPE_WIA           0x00000010
#define INTERNAL_DEV_TYPE_LOCAL         0x00000020
#define INTERNAL_DEV_TYPE_MSC_CAMERA    0x00000040

//
//  This struct is a member of CDrvWrapper object
//
typedef struct _DEVICE_INFO {
    // Indicates whether the information in this struct is valid.  For example,
    // if we failed to read wszPortName, we would mark this as invalid.
    // wszDeviceInternalName is always assumed to be valid.
    BOOL            bValid;

    // PnP ID for this device
    //WCHAR*          wszPnPId;

    // Alternate Device ID, e.g. for volumes, it will be the mount point.  For most
    // real WIA devices, this will be NULL.
    WCHAR*          wszAlternateID;

    // State of the device to indicate enabled/disabled, plugged in/unplugged etc.
    DWORD           dwDeviceState;

    // Type of the hardware imaging device
    STI_DEVICE_TYPE DeviceType;

    // Internal Device type
    DWORD           dwInternalType;

    // Lock Holding Time - Only used for those drivers who want "cached" locking
    DWORD           dwLockHoldingTime;

    // Poll Interval
    DWORD           dwPollTimeout;

    // User disable notifications
    DWORD           dwDisableNotifications;

    // Set of capabilities flags
    STI_USD_CAPS    DeviceCapabilities;

    // This includes bus type
    DWORD           dwHardwareConfiguration;

    // Device identifier for reference when creating device object
    WCHAR*          wszUSDClassId;

    // Device identifier for reference when creating device object
    WCHAR*          wszDeviceInternalName;

    // Remote Device identifier for reference when creating remote device object for WIA
    WCHAR*          wszDeviceRemoteName;

    // Vendor description string
    WCHAR*          wszVendorDescription;

    // Device description , provided by vendor
    WCHAR*          wszDeviceDescription;

    // String , representing port on which device is accessible.
    WCHAR*          wszPortName;

    // Control panel propery provider
    WCHAR*          wszPropProvider;

    // Local specific ("friendly") name of the device, mainly used for showing in the UI
    WCHAR*          wszLocalName;

    // Name of server for this device - WIA only entry
    WCHAR*          wszServer;

    // Baud rate - Serial devices only
    WCHAR*          wszBaudRate;

    // UI CLSID
    WCHAR*          wszUIClassId;

    // SP_DEVINFO_DATA which uniquely identifies this device in WIA dev man's info set
    //  Instead of storing this, we could store interface name instead?
    SP_DEVINFO_DATA spDevInfoData;

    // SP_DEVICE_INTERFACE_DATA which uniquely identifies this device in WIA dev man's info set
    //  Same as above, except for interfaces devices instead of devnoe devices
    SP_DEVICE_INTERFACE_DATA    spDevInterfaceData;

} DEVICE_INFO, *PDEVICE_INFO;

//
// This class is a wrapper for the USD (a similar idea to IStiDevice on STI 
//  client-side).  This provides a layer of abstraction for the higher level
//  classes, so that they don't deal with direct USD Insterfaces.  There are 
//  several advantages to this:
//  1.  It provides for greater stability.  If the driver goes away, we
//  cannot always notify components that rely on talking to the USD that
//  it is no longer present or valid.  However, by making all USD access go 
//  through this wrapper, we are guaranteed that when the USD is gone,
//  all components which attempt to use it will get the appropriate
//  error retunred by the wrapper.
//  2.  It provides greater flexibility.  For example, this class can 
//  load/unload the corresponding USD on the fly, providing for JIT
//  loading.  The higher level classes don't worry about such details;
//  they simply use the wrapper.  The wrapper will then check whether the
//  driver is already loaded, and if not, will take the appropriate steps.
//
class CDrvWrap : public IUnknown {
public:
    CDrvWrap();
    ~CDrvWrap();

    HRESULT Initialize();

    //
    //  IUnknown methods.  Note:  this class is not a real COM object!  It does not
    //  follow any of the COM rules for life-time control (e.g. it will not destroy itself
    //  if ref count is 0).
    //

    HRESULT _stdcall QueryInterface(
        const IID& iid, 
        void** ppv);
    ULONG   _stdcall AddRef(void);
    ULONG   _stdcall Release(void);

    HRESULT LoadInitDriver(HKEY hKeyDeviceParams = NULL);   // This will load and initialize the driver
                                                            //  enabling it for use
    HRESULT UnLoadDriver();                                 // This releases the USD interface pointers
                                                            //  and unloads the driver
    BOOL    IsValid();          // Valid means that we call makes calls down to driver. 
                                //  This may still be true even if driver is not loaded.  It will
                                //  only be false if we know that driver calls will fail even if
                                //  driver was loaded (e.g. USB device was unplugged)
    BOOL    IsDriverLoaded();   // Indicates whether the driver is loaded and initialized
    BOOL    IsWiaDevice();      // Indicates whether this driver is WIA capable
    BOOL    IsWiaDriverLoaded();// Indicates whether this driver's IWiaMiniDrv interface is valid
    BOOL    IsPlugged();        // Indicates whether the device is currently plugged in
    BOOL    IsVolumeDevice();   // Indicates whether this is one of our volume devices
    BOOL    PrepForUse(                     // This method is called before calling down to the driver.  It      
                BOOL        bForWiaCall,    //  ensures the driver is loaded and initalized appropriately.       
                IWiaItem    *pItem = NULL); //  TDB: pItem parameter is no longer needed 
        
    //
    //  Accessor methods
    //
    WCHAR*          getPnPId();
    WCHAR*          getDeviceId();
    DWORD           getLockHoldingTime();
    DWORD           getGenericCaps();
    DWORD           getPollTimeout();
    DWORD           getDisableNotificationsValue();
    DWORD           getHWConfig();
    DWORD           getDeviceState();
    HRESULT         setDeviceState(DWORD dwNewState);
    DEVICE_INFO*    getDevInfo();
    HRESULT         setDevInfo(
        DEVICE_INFO *pInfo);
    ULONG           getInternalType();

    VOID            setJITLoading(BOOL bJITLoading);
    BOOL            getJITLoading();
    LONG            getWiaClientCount();

    BOOL            wasConnectEventThrown();
    VOID            setConnectEventState(BOOL bEventState);

    //
    //  Wrapper methods for IStiUSD
    //

    HRESULT STI_Initialize(
        IStiDeviceControl   *pHelDcb,
        DWORD               dwStiVersion,
        HKEY                hParametersKey);
    HRESULT STI_GetCapabilities(
        STI_USD_CAPS        *pDevCaps);
    HRESULT STI_GetStatus(
        STI_DEVICE_STATUS   *pDevStatus);
    HRESULT STI_GetNotificationData(
        STINOTIFY           *lpNotify);
    HRESULT STI_SetNotificationHandle(
        HANDLE              hEvent);
    HRESULT STI_DeviceReset();
    HRESULT STI_Diagnostic(
        STI_DIAG    *pDiag);
    HRESULT STI_LockDevice();
    HRESULT STI_UnLockDevice();
    HRESULT STI_Escape( 
        STI_RAW_CONTROL_CODE    EscapeFunction,
        LPVOID                  lpInData,
        DWORD                   cbInDataSize,
        LPVOID                  pOutData,
        DWORD                   dwOutDataSize,
        LPDWORD                 pdwActualData);

    //
    //  Wrapper methods for IWiaMiniDrv
    //

    HRESULT WIA_drvInitializeWia(
        BYTE        *pWiasContext,
        LONG        lFlags,
        BSTR        bstrDeviceID,
        BSTR        bstrRootFullItemName,
        IUnknown    *pStiDevice,
        IUnknown    *pIUnknownOuter,
        IWiaDrvItem **ppIDrvItemRoot,
        IUnknown    **ppIUnknownInner,
        LONG        *plDevErrVal);

    HRESULT WIA_drvGetDeviceErrorStr(
        LONG     lFlags,
        LONG     lDevErrVal,
        LPOLESTR *ppszDevErrStr,
        LONG     *plDevErr);

    HRESULT WIA_drvDeviceCommand(
        BYTE        *pWiasContext,
        LONG        lFlags,
        const GUID  *plCommand,
        IWiaDrvItem **ppWiaDrvItem,
        LONG        *plDevErrVal);

    HRESULT WIA_drvAcquireItemData(
        BYTE                      *pWiasContext,
        LONG                      lFlags,
        PMINIDRV_TRANSFER_CONTEXT pmdtc,
        LONG                      *plDevErrVal);

    HRESULT WIA_drvInitItemProperties(
        BYTE *pWiasContext,
        LONG lFlags,
        LONG *plDevErrVal);

    HRESULT WIA_drvValidateItemProperties(
        BYTE           *pWiasContext,
        LONG           lFlags,
        ULONG          nPropSpec,
        const PROPSPEC *pPropSpec,
        LONG           *plDevErrVal);

    HRESULT WIA_drvWriteItemProperties(
        BYTE                      *pWiasContext,
        LONG                      lFlags,
        PMINIDRV_TRANSFER_CONTEXT pmdtc,
        LONG                      *plDevErrVal);

    HRESULT WIA_drvReadItemProperties(
        BYTE           *pWiasContext,
        LONG           lFlags,
        ULONG          nPropSpec,
        const PROPSPEC *pPropSpec,
        LONG           *plDevErrVal);

    HRESULT WIA_drvLockWiaDevice(
        BYTE *pWiasContext,
        LONG lFlags,
        LONG *plDevErrVal);

    HRESULT WIA_drvUnLockWiaDevice(
        BYTE *pWiasContext,
        LONG lFlags,
        LONG *plDevErrVal);

    HRESULT WIA_drvAnalyzeItem(
        BYTE *pWiasContext,
        LONG lFlags,
        LONG *plDevErrVal);

    HRESULT WIA_drvDeleteItem(
        BYTE *pWiasContext,
        LONG lFlags,
        LONG *plDevErrVal);

    HRESULT WIA_drvFreeDrvItemContext(
        LONG lFlags,
        BYTE *pSpecContext,
        LONG *plDevErrVal);

    HRESULT WIA_drvGetCapabilities(
        BYTE            *pWiasContext,
        LONG            ulFlags,
        LONG            *pcelt,
        WIA_DEV_CAP_DRV **ppCapabilities,
        LONG            *plDevErrVal);

    HRESULT WIA_drvGetWiaFormatInfo(
        BYTE            *pWiasContext,
        LONG            lFlags,
        LONG            *pcelt,
        WIA_FORMAT_INFO **ppwfi,
        LONG            *plDevErrVal);

    HRESULT WIA_drvNotifyPnpEvent(
        const GUID *pEventGUID,
        BSTR       bstrDeviceID,
        ULONG      ulReserved);

    HRESULT WIA_drvUnInitializeWia(
        BYTE *pWiasContext);

private:

    HRESULT CreateDeviceControl();  // This method attempts to create a new IStiDevice control to
                                    //  hand down to the driver.  This object is released in
                                    //  UnloadDriver
    HRESULT InternalClear();        // This method clears and frees internal data members, so that the
                                    //  state of the object is the same as if it was just created and initialized
    HRESULT ReportMiniDriverError(  // This method translates the a driver error code into an error string
        LONG        lDevErr,        //  and writes it to the log.
    LPOLESTR        pszWhat);

    HINSTANCE           m_hDriverDLL;       //  Handle to driver's DLL, so we can manually unload
    HANDLE              m_hInternalMutex;   //  Internal sync object - currently unused
    DEVICE_INFO         *m_pDeviceInfo;     //  Internal Device information cache
    IUnknown            *m_pUsdIUnknown;    //  USD's IUnknown
    IStiUSD             *m_pIStiUSD;        //  USD's IStiUSD
    IWiaMiniDrv         *m_pIWiaMiniDrv;    //  USD's IWiaMiniDrv
    IStiDeviceControl   *m_pIStiDeviceControl;  // Device control handed down to USD during initialize
    BOOL                m_bJITLoading;          // Indicates whether driver should be loaded JIT
    LONG                m_lWiaTreeCount;        // Keeps track of outstanding App. Item trees (i.e. app. 
                                                //  connections).  Useful for JIT.
    BOOL                m_bPreparedForUse;      // Indicates whether driver is ready for use
    BOOL                m_bUnload;              // Indicates whether driver should be unloaded.  Used for JIT, 
                                                //  and is set when it has been determined that the driver is no 
                                                //  longer in use (inside WIA_drvUnInitializeWia and is checked
                                                //  by WIA_drvUnlockWiaDevice).
};