/******************************************************************************
*
*  (C) COPYRIGHT MICROSOFT CORP., 1998-1999
*
*  TITLE:       WIA.idl
*
*  VERSION:     2.0
*
*  DATE:        6 Jan, 1998
*
*  DESCRIPTION:
*   IDL source for WIA device manager. The MIDL compiler generates
*   marshaling code and a type library from this file.
*
******************************************************************************/

interface IWiaDevMgr;
interface IWiaEventCallback;
interface IWiaDataCallback;
interface IWiaItem;
interface IWiaPropertyStorage;
interface IEnumWiaItem;
interface IEnumWIA_DEV_INFO;
interface IEnumWIA_DEV_CAPS;
interface IEnumWIA_FORMAT_INFO;
interface IStiDevice;

import "unknwn.idl";
import "oaidl.idl";
import "propidl.idl";

/*******************************************************************************
*
* Structures used by WIA
*
*******************************************************************************/

//
// Dither pattern specification structure used
// with WIA_DPS_DITHER_PATTERN_DATA
//

typedef struct _WIA_DITHER_PATTERN_DATA
{
                            LONG        lSize;
                            BSTR        bstrPatternName;
                            LONG        lPatternWidth;
                            LONG        lPatternLength;
                            LONG        cbPattern;
    [size_is(cbPattern)]    BYTE        *pbPattern;
} WIA_DITHER_PATTERN_DATA, *PWIA_DITHER_PATTERN_DATA;

typedef struct _WIA_PROPID_TO_NAME {
    PROPID      propid;
    LPOLESTR    pszName;
} WIA_PROPID_TO_NAME, *PWIA_PROPID_TO_NAME;

typedef struct _WIA_FORMAT_INFO 
{
    GUID        guidFormatID;
    LONG        lTymed;
} WIA_FORMAT_INFO, *PWIA_FORMAT_INFO;

/*******************************************************************************
*
* Import header file which contains WIA constants and globals
*
*******************************************************************************/

cpp_quote("#include \"wiadef.h\"")

/*******************************************************************************
*
* WIA Device Manager Interface
*
*******************************************************************************/

[
    object,
    uuid(5eb2502a-8cf1-11d1-bf92-0060081ed811),
    helpstring("WIA Device Manager Interface"),
    pointer_default(unique)
]

interface IWiaDevMgr : IUnknown
{
    [id(1), helpstring("Create an WIA device information enumerator")]
    HRESULT EnumDeviceInfo(
        [in]            LONG                            lFlag,
        [out, retval]   IEnumWIA_DEV_INFO               **ppIEnum);

    //
    // Creates/loads device.
    //

    [id(2), helpstring("Create an WIA device object")]
    HRESULT CreateDevice(
        [in]    BSTR                                    bstrDeviceID,
        [out]   IWiaItem                                **ppWiaItemRoot);

    //
    // Creates/loads user selected device. Client side only call.
    //

    [local]
    HRESULT SelectDeviceDlg(
        [in]            HWND                            hwndParent,
        [in]            LONG                            lDeviceType,
        [in]            LONG                            lFlags,
        [in,out]        BSTR                            *pbstrDeviceID,
        [out,retval]    IWiaItem                        **ppItemRoot);

    [id(3), call_as(SelectDeviceDlg),  helpstring("Present UI to select then create an WIA device")]
    HRESULT LocalSelectDeviceDlg(
        [in]            HWND                            hwndParent,
        [in]            LONG                            lDeviceType,
        [in]            LONG                            lFlags,
        [in,out]        BSTR                            *pbstrDeviceID,
        [out, retval]   IWiaItem                        **ppItemRoot);

    //
    // Returns the device ID of user selected device. Client side only call.
    //

    [local]
    HRESULT SelectDeviceDlgID(
        [in]            HWND                            hwndParent,
        [in]            LONG                            lDeviceType,
        [in]            LONG                            lFlags,
        [out, retval]   BSTR                            *pbstrDeviceID );

    [id(4), call_as(SelectDeviceDlgID),  helpstring("Present UI to select then create an WIA device, returns BSTR")]
    HRESULT LocalSelectDeviceDlgID(
        [in]            HWND                            hwndParent,
        [in]            LONG                            lDeviceType,
        [in]            LONG                            lFlags,
        [out, retval]   BSTR                            *pbstrDeviceID );

    //
    // Creates/loads user selected device and gets image. Client side only call.
    //

    [local]
    HRESULT GetImageDlg(
        [in]            HWND                            hwndParent,
        [in]            LONG                            lDeviceType,
        [in]            LONG                            lFlags,
        [in]            LONG                            lIntent,
        [in]            IWiaItem                        *pItemRoot,
        [in]            BSTR                            bstrFilename,
        [in,out]        GUID                            *pguidFormat);
        
    [id(5), call_as(GetImageDlg), helpstring("Get an image to file")]
    HRESULT LocalGetImageDlg(
        [in]            HWND                            hwndParent,
        [in]            LONG                            lDeviceType,
        [in]            LONG                            lFlags,
        [in]            LONG                            lIntent,
        [in]            IWiaItem                        *pItemRoot,
        [in]            BSTR                            bstrFilename,
        [in,out]        GUID                            *pguidFormat);

    [id(6), helpstring("register application launch")]
    HRESULT RegisterEventCallbackProgram(
        [in]            LONG                            lFlags,
        [in]            BSTR                            bstrDeviceID,
        [in]            const GUID                      *pEventGUID,
        [in]            BSTR                            bstrCommandline,
        [in]            BSTR                            bstrName,
        [in]            BSTR                            bstrDescription,
        [in]            BSTR                            bstrIcon);

    [id(7), helpstring("Registers a WIA Event Callback")]
    HRESULT RegisterEventCallbackInterface(
        [in]            LONG                            lFlags,
        [in]            BSTR                            bstrDeviceID,
        [in]            const GUID                      *pEventGUID,
        [in,unique]     IWiaEventCallback               *pIWiaEventCallback,
        [out]           IUnknown                        **pEventObject);

    [id(8), helpstring("Registers a WIA Event Callback")]
    HRESULT RegisterEventCallbackCLSID(
        [in]            LONG                            lFlags,
        [in]            BSTR                            bstrDeviceID,
        [in]            const GUID                      *pEventGUID,
        [in,unique]     const GUID                      *pClsID,
        [in]            BSTR                            bstrName,
        [in]            BSTR                            bstrDescription,
        [in]            BSTR                            bstrIcon);      

    //
    // add either a non-pnp local Wia device or a network device
    //

    [id(9), helpstring("Present UI to add a WIA device")]
    HRESULT AddDeviceDlg(
        [in]            HWND                            hwndParent,
        [in]            LONG                            lFlags);

};

/*******************************************************************************
*
* WIA Device Information Enumeration Interface
*
*******************************************************************************/

[
    object,
    uuid(5e38b83c-8cf1-11d1-bf92-0060081ed811),
    helpstring("WIA Device Information Enumeration Interface"),
    pointer_default(unique)
]

interface IEnumWIA_DEV_INFO : IUnknown
{
    [local]
    HRESULT Next(
        [in]                                          ULONG                 celt,
        [out,size_is(celt), length_is(*pceltFetched)] IWiaPropertyStorage   **rgelt,
        [in,out,unique]                               ULONG*                pceltFetched);
        
    [id(1), call_as(Next), helpstring("Gets the next device information IWiaPropertyStorage object")]
    HRESULT RemoteNext(
        [in]                                          ULONG                 celt,
        [out,size_is(celt), length_is(*pceltFetched)] IWiaPropertyStorage   **rgelt,
        [in,out,unique]                               ULONG*                pceltFetched);

    [id(2), helpstring("Skips the next device information IWiaPropertyStorage object")]
    HRESULT Skip(
        [in]            ULONG                           celt);

    [id(3), helpstring("Resets to first device information IWiaPropertyStorage object")]
    HRESULT Reset(void);

    [id(4), helpstring("Clones this IEnumWIA_DEV_INFO object")]
    HRESULT Clone(
        [out]           IEnumWIA_DEV_INFO               **ppIEnum);

    [id(5), helpstring("Returns the number of elements stored by this enumerator")]
    HRESULT GetCount(
        [out]            ULONG                          *celt);
}


/**************************************************************************\
*
*   IWiaEventCallback Interface
*
*
*
*
*
*
* History:
*
*    2/11/1998 Mark Enstrom [marke]
*
\**************************************************************************/

[
    object,
    uuid(ae6287b0-0084-11d2-973b-00a0c9068f2e),
    helpstring("WIA Event callback"),
    pointer_default(unique)
]

interface IWiaEventCallback : IUnknown
{
    //
    // WIA event notification
    //

    HRESULT ImageEventCallback(
        [in]            const GUID                      *pEventGUID,
        [in]            BSTR                            bstrEventDescription,
        [in]            BSTR                            bstrDeviceID,
        [in]            BSTR                            bstrDeviceDescription,
        [in]            DWORD                           dwDeviceType,
        [in, out]       ULONG                           *pulEventType,
        [in]            ULONG                           ulReserved);
}

/**************************************************************************\
*
* WIA_DATA_CALLBACK_HEADER
*
*   lSize           - size of this structure
*   lFormat         - format of image
*   lBufferSize     - size of buffer needed for complete data transfer
*   lPageCount      - zero based count of total pages transfered
*
* History:
*
*   10/29/98
*
\**************************************************************************/

typedef struct _WIA_DATA_CALLBACK_HEADER{
    LONG        lSize;
    GUID        guidFormatID;
    LONG        lBufferSize;
    LONG        lPageCount;
}WIA_DATA_CALLBACK_HEADER,*PWIA_DATA_CALLBACK_HEADER;


/**************************************************************************\
*
*  IWiaDataCallback interface
*
*
*
*
*
* History:
*
*    10/29/1998 Original Version
*
\**************************************************************************/

[
    object,
    uuid(a558a866-a5b0-11d2-a08f-00c04f72dc3c),
    helpstring("WIA data callback"),
    pointer_default(unique)
]

interface IWiaDataCallback : IUnknown
{
    //
    // image transfer status
    //

    [local]
    HRESULT BandedDataCallback(
        [in]                      LONG        lMessage,
        [in]                      LONG        lStatus,
        [in]                      LONG        lPercentComplete,
        [in]                      LONG        lOffset,
        [in]                      LONG        lLength,
        [in]                      LONG        lReserved,
        [in]                      LONG        lResLength,
        [in,size_is(lResLength)]  BYTE        *pbBuffer);

    [id(1), call_as(BandedDataCallback) ,helpstring(" client data callback")]
    HRESULT RemoteBandedDataCallback(
        [in]                            LONG        lMessage,
        [in]                            LONG        lStatus,
        [in]                            LONG        lPercentComplete,
        [in]                            LONG        lOffset,
        [in]                            LONG        lLength,
        [in]                            LONG        lReserved,
        [in]                            LONG        lResLength,
        [in,size_is(lResLength),unique] BYTE        *pbBuffer);
}


/**************************************************************************\
*
* WIA_DATA_TRANSFER_INFO
*
*   ulSize           - Size of this structure
*   ulSection        - Section provided by the client, otherwise NULL
*   ulBufferSize     - Size of the buffer used in data transfer
*   bDoubleBuffer    - Indicate whether the client want to use double buffer
*   ulReserved1      - Must be ZERO
*   ulReserved2      - Must be ZERO
* History:
*
*   10/29/98
*
\**************************************************************************/

typedef struct _WIA_DATA_TRANSFER_INFO {
    ULONG       ulSize;
    ULONG       ulSection;
    ULONG       ulBufferSize;
    BOOL        bDoubleBuffer;
    ULONG       ulReserved1;
    ULONG       ulReserved2;
    ULONG       ulReserved3;
} WIA_DATA_TRANSFER_INFO, *PWIA_DATA_TRANSFER_INFO;


/**************************************************************************\
*
* IWiaDataTransfer - Interface to use shared memory to transfer an image
*
*
*
*
*
*
*
* History:
*
*    4/1/1998 Mark Enstrom [marke]
*
\**************************************************************************/

[
    object,
    uuid(a6cef998-a5b0-11d2-a08f-00c04f72dc3c),
    helpstring("WIA Data Transfer Interface"),
    pointer_default(unique)
]

interface IWiaDataTransfer : IUnknown
{
    [local]
    HRESULT idtGetData(
        [out]           LPSTGMEDIUM                     pMedium,
        [in,unique]     IWiaDataCallback               *pIWiaDataCallback);

    [id(1), call_as(idtGetData), helpstring("IDataObject style data transfer with progress callback")]
    HRESULT idtGetDataEx(
        [out]           LPSTGMEDIUM                     pMedium,
        [in,unique]     IWiaDataCallback               *pIWiaDataCallback);

    [local]
    HRESULT idtGetBandedData(
        [in,unique]     PWIA_DATA_TRANSFER_INFO         pWiaDataTransInfo,
        [in,unique]     IWiaDataCallback               *pIWiaDataCallback);

    [id(2), call_as(idtGetBandedData), helpstring("transfer image into a buffer")]
    HRESULT idtGetBandedDataEx(
        [in,unique]     PWIA_DATA_TRANSFER_INFO         pWiaDataTransInfo,
        [in,unique]     IWiaDataCallback               *pIWiaDataCallback);

    [id(3), helpstring("Check if format is supported")]
    HRESULT idtQueryGetData(
        [in,unique]     WIA_FORMAT_INFO*                pfe);

    [id(4), helpstring("Create format enumerator")]
    HRESULT idtEnumWIA_FORMAT_INFO(
        [out]           IEnumWIA_FORMAT_INFO            **ppEnum);
}

/*******************************************************************************
*
* IWiaItem Interface
*
*******************************************************************************/

[
    object,
    uuid(4db1ad10-3391-11d2-9a33-00c04fa36145),
    helpstring("WIA Device Item Interface"),
    pointer_default(unique)
]

interface IWiaItem : IUnknown
{
    [id(1), helpstring("Get item type")]
    HRESULT GetItemType(
        [out]   LONG                    *pItemType);

    [id(2), helpstring("Analyze an item")]
    HRESULT AnalyzeItem(
        [in]    LONG                    lFlags);

    [id(3), helpstring("Get item enumerator")]
    HRESULT EnumChildItems(
        [out]   IEnumWiaItem            **ppIEnumWiaItem);

    [id(4), helpstring("Delete an item")]
    HRESULT DeleteItem(
        [in]    LONG                    lFlags);

    [id(5), helpstring("Create a new child item")]
    HRESULT CreateChildItem(
        [in]    LONG                    lFlags,
        [out]   IWiaItem                **ppIWiaItem);

    [id(7), helpstring("Enumerate event info")]
    HRESULT EnumRegisterEventInfo(
        [in]    LONG                    lFlags,
        [in]    const GUID              *pEventGUID,
        [out]   IEnumWIA_DEV_CAPS       **ppIEnum);

    [id(8), helpstring("search for item by name")]
    HRESULT FindItemByName(
        [in]    LONG                    lFlags,
        [in]    BSTR                    bstrFullItemName,
        [out]   IWiaItem                **ppIWiaItem);

    // Client side only call.
    [local]
    HRESULT DeviceDlg(
        [in]    HWND                    hwndParent,
        [in]    LONG                    lFlags,
        [in]    LONG                    lIntent,
        [out]   LONG                    *plItemCount,
        [out]   IWiaItem                ***ppIWiaItem);

    [id(9), call_as(DeviceDlg), helpstring("Display device data acquistion UI")]
    HRESULT LocalDeviceDlg(
        [in]    HWND                    hwndParent,
        [in]    LONG                    lFlags,
        [in]    LONG                    lIntent,
        [out]   LONG                    *plItemCount,
        [out]   IWiaItem                ***pIWiaItem);

    [id(10), helpstring("Issue a device command")]
    HRESULT DeviceCommand(
        [in]            LONG            lFlags,
        [in]            const GUID      *pCmdGUID,
        [in, out]       IWiaItem        **pIWiaItem);

    [id(11), helpstring("Get device root item")]
    HRESULT GetRootItem(
        [out]           IWiaItem        **ppIWiaItem);

    [id(12), helpstring("Enumerate device events and commands")]
    HRESULT EnumDeviceCapabilities(
        [in]    LONG                    lFlags,
        [out]   IEnumWIA_DEV_CAPS       **ppIEnumWIA_DEV_CAPS);

    [id(13), helpstring("Dump private item data, debug only")]
    HRESULT DumpItemData(
        [out]           BSTR            *bstrData);

    [id(14), helpstring("Dump private driver item data, debug only")]
    HRESULT DumpDrvItemData(
        [out]           BSTR            *bstrData);

    [id(15), helpstring("Dump private tree item data, debug only")]
    HRESULT DumpTreeItemData(
        [out]           BSTR            *bstrData);
};

/*******************************************************************************
*
* IWiaPropertyStorage Interface
*
*******************************************************************************/

[
    object,
    uuid(98B5E8A0-29CC-491a-AAC0-E6DB4FDCCEB6),
    helpstring("WIA Property Storage Interface"),
    pointer_default(unique)
]

interface IWiaPropertyStorage : IPropertyStorage
{
    [id(1), helpstring("Get property attribute information.")]
    HRESULT GetPropertyAttributes(
        [in]                    ULONG                   cpspec,
        [in, size_is(cpspec)]   PROPSPEC                rgpspec[],
        [out, size_is(cpspec)]  ULONG                   rgflags[],
        [out, size_is(cpspec)]  PROPVARIANT             rgpropvar[]);    
            
    [id(2), helpstring("Returns the current number of properties in this property storage.")]
    HRESULT GetCount(
        [out]                   ULONG                   *pulNumProps);

    [id(3), helpstring("Get an items property stream")]
    HRESULT GetPropertyStream(
        [out]   IStream                **ppIStream);

    [id(4), helpstring("Set an items property stream")]
    HRESULT SetPropertyStream(
        [in]    IStream                *pIStream);
};

/*******************************************************************************
*
* IEnumWiaItem Interface
*
*******************************************************************************/

[
    object,
    uuid(5e8383fc-3391-11d2-9a33-00c04fa36145),
    helpstring("WIA Device Class Item Enumeration Interface"),
    pointer_default(unique)
]

interface IEnumWiaItem : IUnknown
{
    [local]
    HRESULT Next(
        [in]                                           ULONG      celt,
        [out, size_is(celt), length_is(*pceltFetched)] IWiaItem **ppIWiaItem,
        [in, out, unique]                              ULONG     *pceltFetched);

    [id(1), call_as(Next), helpstring("Gets the next IWiaItem object")]
    HRESULT RemoteNext(
        [in]                                           ULONG      celt,
        [out, size_is(celt), length_is(*pceltFetched)] IWiaItem **ppIWiaItem,
        [in, out, unique]                              ULONG     *pceltFetched);

    [id(2), helpstring("Skips the next IWiaItem object")]
    HRESULT Skip(
        [in]    ULONG                   celt);

    [id(3), helpstring("Resets to first IWiaItem object")]
    HRESULT Reset(void);

    [id(4), helpstring("Clone IEnumWiaItem object")]
    HRESULT Clone(
        [out]   IEnumWiaItem            **ppIEnum);

    [id(5), helpstring("Returns the number of elements stored by this enumerator")]
    HRESULT GetCount(
        [out]   ULONG                   *celt);

}

/*******************************************************************************
*
*  WIA_DEV_CAP
*
*   WIA_DEV_CAP structure returns event and command information
*   for the IEnumWIA_DEV_CAPS Interface
*
*******************************************************************************/

typedef struct _WIA_DEV_CAP {
        GUID            guid;
        ULONG           ulFlags;   // Indicate the handler is default, etc
        BSTR            bstrName;
        BSTR            bstrDescription;
        BSTR            bstrIcon;
} WIA_DEV_CAP, *PWIA_DEV_CAP, WIA_EVENT_HANDLER, *PWIA_EVENT_HANDLER;

/*******************************************************************************
*
* IEnumWIA_DEV_CAPS Interface
*
*******************************************************************************/

[
    object,
    uuid(1fcc4287-aca6-11d2-a093-00c04f72dc3c),
    helpstring("WIA_DEV_CAPS Enumeration Interface"),
    pointer_default(unique)
]

interface IEnumWIA_DEV_CAPS : IUnknown
{
    [local]
    HRESULT Next(
        [in]                                                      ULONG           celt,
        [out, size_is(celt), length_is(*pceltFetched)]            WIA_DEV_CAP     *rgelt,
        [in,out,unique]                                           ULONG           *pceltFetched);

    [id(1), call_as(Next), helpstring("Gets the next WIA_DEV_CAPS")]
    HRESULT RemoteNext(
        [in]                                                      ULONG           celt,
        [out, size_is(celt), length_is(*pceltFetched)]            WIA_DEV_CAP     *rgelt,
        [in,out,unique]                                           ULONG           *pceltFetched);


    [id(2), helpstring("Skips the next WIA_DEV_CAPS")]
    HRESULT Skip(
        [in]                            ULONG                   celt);

    [id(3), helpstring("Resets to first WIA_DEV_CAPS")]
    HRESULT Reset(void);

    [id(4), helpstring("Clone IEnumWIA_DEV_CAPS object")]
    HRESULT Clone(
        [out]                           IEnumWIA_DEV_CAPS       **ppIEnum);

    [id(5), helpstring("Returns the number of elements stored by this enumerator")]
    HRESULT GetCount(
        [out]                           ULONG                   *pcelt);

}

/*******************************************************************************
*
* IEnumWIA_FORMAT_INF Interface
*
*******************************************************************************/

[
    object,
    uuid(81BEFC5B-656D-44f1-B24C-D41D51B4DC81),
    helpstring("WIA_FORMAT_INFO Enumeration Interface"),
    pointer_default(unique)
]

interface IEnumWIA_FORMAT_INFO : IUnknown
{
    [local]
    HRESULT Next(
        [in]                                                    ULONG           celt,
        [out, size_is(celt), length_is(*pceltFetched)]          WIA_FORMAT_INFO *rgelt,
        [in,out,unique]                                         ULONG           *pceltFetched);
    
    [id(1), call_as(Next), helpstring("Gets the next WIA_FORMAT_INFO")]
    HRESULT RemoteNext(
        [in]                                                    ULONG           celt,
        [out, size_is(celt), length_is(*pceltFetched)]          WIA_FORMAT_INFO *rgelt,
        [in,out,unique]                                         ULONG           *pceltFetched);

    [id(2), helpstring("Skips the next WIA_FORMAT_INFO")]
    HRESULT Skip(
        [in]                            ULONG                   celt);

    [id(3), helpstring("Resets to first WIA_FORMAT_INFO")]
    HRESULT Reset(void);

    [id(4), helpstring("Clone IEnumWIA_FORMAT_INFO object")]
    HRESULT Clone(
        [out]                           IEnumWIA_FORMAT_INFO    **ppIEnum);

    [id(5), helpstring("Returns the number of elements stored by this enumerator")]
    HRESULT GetCount(
        [out]                           ULONG                   *pcelt);

}

/*******************************************************************************
*
* WIA Logging Interface
*
*******************************************************************************/

[
    object,
    uuid(A00C10B6-82A1-452f-8B6C-86062AAD6890),
    helpstring("WIA Logging Interface"),
    pointer_default(unique)
]

interface IWiaLog : IUnknown
{
    [id(1), helpstring("Initialize Logging object")]
    HRESULT InitializeLog(
        [in]            LONG                            hInstance);
        
    [id(2), helpstring("Write ERRROR Information to log file, Translating HRESULT to error string")]
    HRESULT hResult(
        [in]            HRESULT                         hResult);
                    
    [id(3), helpstring("Write TRACE,ERROR,WARNING, etc.. Information to log file, using service Resource ID")]
    HRESULT Log(
        [in]            LONG                            lFlags,
        [in]            LONG                            lResID,
        [in]            LONG                            lDetail,
        [in]            BSTR                            bstrText);
};

/*******************************************************************************
*
*               C O M P O N E N T    D E S C R I P T I O N S
*
*******************************************************************************/

[
    uuid(99f74582-8cf1-11d1-bf92-0060081ed811),
        version(1.0),
    helpstring("WIA Type Library")
]

library WiaDevMgr
{  
        importlib("stdole32.tlb") ;

        // WIA Device Manager
        [
        uuid(a1f4e726-8cf1-11d1-bf92-0060081ed811),
        helpstring("WIA Device Manager")
        ]

    coclass WiaDevMgr
        {
        [default] interface IWiaDevMgr;
        };

        // WIA Logging
        [
        uuid(A1E75357-881A-419e-83E2-BB16DB197C68),
        helpstring("WIA Logging")
        ]
        
    coclass WiaLog
        {
        interface IWiaLog;
        };        
};


