/*++

Copyright (c) 1996  Microsoft Corporation

Module Name:

    SCardMgr

Abstract:

    IDL source for SCardMgr.DLL. This in-process server (DLL)
    encapsulates the hardware oriented COM interfaces for the
    Smart Card Service Provider (SSP) Manager.
    
Author:

    Michael Gallagher (a-mgalla) 10/21/1996

Environment:

    Win32

Revision History:

    Michael Gallagher (a-mgalla) 1/23/1997
    Chris Dudley (cdudley) 1/24/1997
    Chris Dudley (cdudley) 3/13/1997

Notes:

    This file will be processed by the MIDL tool to produce
    the type library (SCardMgr.tlb) and marshalling code. A
    header file named SCardMgr.h will be generated by the
    MIDL compiler for the ATL CPP code to use.

--*/


cpp_quote("//+-------------------------------------------------------------------------")
cpp_quote("//")
cpp_quote("//  Microsoft Smart Card Support")
cpp_quote("//  Copyright (C) Microsoft Corporation, 1996.")
cpp_quote("//")
cpp_quote("// File: SCardMgr.h")
cpp_quote("//")
cpp_quote("//--------------------------------------------------------------------------")


cpp_quote("")
cpp_quote("//////////////////////////////////////////////////////////////////")
cpp_quote("//")
cpp_quote("// Imports")
cpp_quote("//")

#ifndef DO_NO_IMPORTS
    import "SspsIdl.idl";
#endif

interface ISCard;
interface ISCardDatabase;
interface ISCardLocate;


cpp_quote("")
cpp_quote("//////////////////////////////////////////////////////////////////")
cpp_quote("//")
cpp_quote("// Types and Constants")
cpp_quote("//")

cpp_quote("#ifndef _NULL_DEFINED")
    cpp_quote("#define _NULL_DEFINED")
    #define NULL    0
cpp_quote("#endif // !_NULL_DEFINED")

cpp_quote("#ifndef _HSCARD_DEFINED")
    cpp_quote("#define _HSCARD_DEFINED")
    typedef [public] LONG HSCARD;
cpp_quote("#endif // !_HSCARD_DEFINED")

cpp_quote("#ifndef _LPHSCARD_DEFINED")
    cpp_quote("#define _LPHSCARD_DEFINED")
    typedef [unique] HSCARD *PHSCARD;
    typedef [unique] HSCARD *LPHSCARD;
cpp_quote("#endif // !_LPHSCARD_DEFINED")

cpp_quote("#ifndef _HSCARDCONTEXT_DEFINED")
    cpp_quote("#define _HSCARDCONTEXT_DEFINED")
    typedef [public] LONG HSCARDCONTEXT;
cpp_quote("#endif // !_HSCARDCONTEXT_DEFINED")

cpp_quote("#ifndef _LPHSCARDCONTEXT_DEFINED")
    cpp_quote("#define _LPHSCARDCONTEXT_DEFINED")
    typedef [unique] SHCARDCONTEXT *PHSCARDCONTEXT;
    typedef [unique] SHCARDCONTEXT *LPHSCARDCONTEXT;
cpp_quote("#endif // !_LPHSCARDCONTEXT_DEFINED")

cpp_quote("#ifndef _SCARD_SHARE_MODES_DEFINED")
    cpp_quote("#define _SCARD_SHARE_MODES_DEFINED")
    typedef [helpstring("SCard Share Modes"),
             //uuid(),
             //helpcontext(),
             v1_enum,   // force 32-bit transmission over RPC, if in use...
             version(1.0)]
    enum tagSCARD_SHARE_MODES {
        EXCLUSIVE = 1,
        SHARED = 2
     } SCARD_SHARE_MODES;
cpp_quote("#endif // !_SCARD_SHARE_MODES_DEFINED")

cpp_quote("#ifndef _SCARD_DISPOSITIONS_DEFINED")
    cpp_quote("#define _SCARD_DISPOSITIONS_DEFINED")
    typedef [helpstring("SCard Dispositions"),
             //uuid(),
             //helpcontext(),
             v1_enum,   // force 32-bit transmission over RPC, if in use...
             version(1.0)]
    enum tagSCARD_DISPOSITIONS {
        LEAVE = 0,
        RESET = 1,
        UNPOWER = 2,
        EJECT = 3
     } SCARD_DISPOSITIONS;
cpp_quote("#endif // !_SCARD_DISPOSITIONS_DEFINED")

cpp_quote("#ifndef _SCARD_STATES_DEFINED")
    cpp_quote("#define _SCARD_STATES_DEFINED")
    typedef [helpstring("SCard States"),
             //uuid(),
             //helpcontext(),
             v1_enum,   // force 32-bit transmission over RPC, if in use...
             version(1.0)]
    enum tagSCARD_STATES {
        ABSENT = 1,
        PRESENT = 2,
        SWALLOWED = 3,
        POWERED = 4,
        NEGOTIABLEMODE = 5,
        SPECIFICMODE = 6
     } SCARD_STATES;
cpp_quote("#endif // !_SCARD_STATES_DEFINED")

cpp_quote("#ifndef _SCARD_PROTOCOLS_DEFINED")
    cpp_quote("#define _SCARD_PROTOCOLS_DEFINED")
    typedef [helpstring("SCard Protocols"),
             //uuid(),
             //helpcontext(),
             v1_enum,   // force 32-bit transmission over RPC, if in use...
             version(1.0)]
    enum tagSCARD_PROTOCOLS {
        T0 = 0x01,  // T=0 is the active protocol.
        T1 = 0x02,  // T=1 is the active protocol.
        RAW = 0xff  // Raw is the active protocol.
     } SCARD_PROTOCOLS;
cpp_quote("#endif // !_SCARD_PROTOCOLS_DEFINED")


cpp_quote("#ifndef _SCARD_INFO")
    cpp_quote("#define _SCARD_INFO")
    typedef [helpstring("FindCard returned information structure."),
             //uuid(),
             //helpcontext(),
             version(1.0)]
    struct tagSCARDINFO {
        HSCARD  hCard;
        HSCARDCONTEXT hContext;
        SCARD_PROTOCOLS ActiveProtocol;
        SCARD_SHARE_MODES ShareMode;
        LONG hwndOwner;
        LONG lpfnConnectProc;
        LONG lpfnCheckProc;
        LONG lpfnDisconnectProc;
        //
        // Do we want to include any of the following???
        //
        //   1. card state (i.e., disposition)
        //   2. process ID, thread ID (...a DWORD)
        //   3. card GUID
        //   4. GUID of class factory
        //
      } SCARDINFO;

    cpp_quote ("#define _LPSCARDINFO")      
    typedef [unique] SCARDINFO *PSCARDINFO, *LPSCARDINFO;

cpp_quote ("#endif //_SCARD_INFO")

cpp_quote("")
cpp_quote("//////////////////////////////////////////////////////////////////")
cpp_quote("//")
cpp_quote("// ISCard Interface")
cpp_quote("//")

cpp_quote("#ifndef _LPSCARD_DEFINED")
cpp_quote("#define _LPSCARD_DEFINED")
    [
        object,
        uuid(1461AAC3-6810-11D0-918F-00AA00C18068),
        dual,
        helpstring("ISCard Interface"),
        //hidden,
        //restricted,       // prevent macro programming?
        version(1.0),
        pointer_default(unique)
    ]
    interface ISCard : IDispatch
    {
        // Includes -

        import "SspsIdl.idl";
        
        // Pointer(s) -

        typedef [unique] ISCard* LPSCARD;
        typedef [unique] LPSCARD LPSMARTCARD;

        // Properties -

        [id(0), propget,
         helpstring("Retrieve the ATR string for the Smart Card")]
        HRESULT Atr([out,retval] LPBYTEBUFFER *ppAtr);

        [id(1), propget,
         helpstring("Retrieve the current card handle.")]
        HRESULT CardHandle([out,retval] HSCARD *pHandle);

        [id(2), propget,
         helpstring("Retrieve the current context handle.")]
        HRESULT Context([out,retval] HSCARDCONTEXT *pContext);

        [id(3), propget,
         helpstring("Retrieve the protocol in use on the Smart Card")]
        HRESULT Protocol([out,retval] SCARD_PROTOCOLS *pProtocol);

        [id(4), propget,
         helpstring("Retrieve the current state that the Smart Card is in")]
        HRESULT Status([out,retval] SCARD_STATES *pStatus);

        // Methods -

        [id(5),
         helpstring("Attach an open SCard handle to this object")]
        HRESULT AttachByHandle([in] HSCARD hCard);

        [id(6),
         helpstring("Open a connection to a card in the named reader")]
        HRESULT AttachByReader([in] BSTR bstrReaderName,
                               [in,defaultvalue(EXCLUSIVE)]
                                    SCARD_SHARE_MODES ShareMode,
                               [in,defaultvalue(T0)]
                                    SCARD_PROTOCOLS PrefProtocol);
        
        [id(7),
         helpstring("Close a connection to an open card")]
        HRESULT Detach([in,defaultvalue(LEAVE)]
                            SCARD_DISPOSITIONS Disposition);
        
        [id(8),
         helpstring("Acquire exclusive access and use of the open Smart Card")]
        HRESULT LockSCard(void);

        [id(9),
         helpstring("Reattach an existing connection to an in use Smart Card ")]
        HRESULT ReAttach([in,defaultvalue(EXCLUSIVE)]
                                SCARD_SHARE_MODES ShareMode,
                         [in,defaultvalue(LEAVE)]
                                SCARD_DISPOSITIONS InitState);
        
        [id(10),
         helpstring("Execute a card transaction with a card command interface")]
        HRESULT Transaction([in,out] LPSCARDCMD *ppCmd);

        [id(11),
         helpstring("Release the exclusive access lock on the Smart Card")]
        HRESULT UnlockSCard([in,defaultvalue(LEAVE)]
                            SCARD_DISPOSITIONS Disposition);
    };
cpp_quote("#endif // !_LPSCARD_DEFINED")


cpp_quote("")
cpp_quote("//////////////////////////////////////////////////////////////////")
cpp_quote("//")
cpp_quote("// ISCardDatabase Interface")
cpp_quote("//")

cpp_quote("#ifndef _LPSCARDDATABASE_DEFINED")
cpp_quote("#define _LPSCARDDATABASE_DEFINED")
    [
        object,
        uuid(1461AAC8-6810-11D0-918F-00AA00C18068),
        dual,
        helpstring("ISCardDatabase Interface"),
        //hidden,
        //restricted,       // prevent macro programming?
        version(1.0),
        pointer_default(unique)
    ]
    interface ISCardDatabase : IDispatch
    {
        // Includes -

        import "SspsIdl.idl";

        // Pointer(s) -

        typedef [unique] ISCardDatabase* LPSCARDDATABASE;

        // Methods -

        [id(0),
         helpstring("Retrieve the provider ID for the named card")]
        HRESULT GetProviderCardId([in] BSTR bstrCardName,
                                  [out,retval] LPGUID *ppguidProviderId);

        [id(1),
         helpstring("Retrieve a list of the interfaces (GUIDs) for the named card")]
        HRESULT ListCardInterfaces([in] BSTR bstrCardName,
                                   [out,retval] LPSAFEARRAY *ppInterfaceGuids); // BSTR

        [id(2),
         helpstring("Retrieve a list of the names of the defined cards")]
        HRESULT ListCards([in,defaultvalue(NULL)] LPBYTEBUFFER pAtr,
                          [in,defaultvalue(NULL)] LPSAFEARRAY pInterfaceGuids,  // BSTR
                          [in,lcid,defaultvalue(0x0409)] long localeId,
                          [out,retval] LPSAFEARRAY *ppCardNames);                       // BSTR

        [id(3),
         helpstring("Retrieve a list of the names of the defined card reader groups")]
        HRESULT ListReaderGroups([in,lcid,defaultvalue(0x0409)] long localeId,
                                 [out,retval] LPSAFEARRAY *ppReaderGroups);     // BSTR
                        
        [id(4),
         helpstring("Retrieve a list of the names of the defined card readers")]
        HRESULT ListReaders([in,lcid,defaultvalue(0x0409)] long localeId,
                            [out,retval] LPSAFEARRAY *ppReaders);       // BSTR
    };
cpp_quote("#endif // !_LPSCARDDATABASE_DEFINED")


cpp_quote("")
cpp_quote("//////////////////////////////////////////////////////////////////")
cpp_quote("//")
cpp_quote("// ISCardLocate Interface")
cpp_quote("//")

cpp_quote("#ifndef _LPSCARDLOCATE_DEFINED")
cpp_quote("#define _LPSCARDLOCATE_DEFINED")

    [
        object,
        uuid(1461AACD-6810-11D0-918F-00AA00C18068),
        dual,
        helpstring("ISCardLocate Interface"),
        //hidden,
        //restricted,       // prevent macro programming?
        version(1.0),
        pointer_default(unique)
    ]
    interface ISCardLocate : IDispatch
    {
        // Includes -

        import "SspsIdl.idl";

        // Pointer(s) -

        typedef [unique] ISCardLocate* LPSCARDLOCATE;
        typedef [unique] LPSCARDLOCATE LPSCARDLOC;

        // Type(s) -

        // Methods -

        [id(0),
         helpstring("Configure the search based on the card GUIDs")]
        HRESULT ConfigureCardGuidSearch(
                        [in] LPSAFEARRAY pCardGuids,                        // BSTR
                        [in,defaultvalue(NULL)] LPSAFEARRAY pGroupNames,    // BSTR
                        [in,defaultvalue("")] BSTR bstrTitle,
                        [in,defaultvalue(1)] LONG lFlags);

        [id(1),
         helpstring("Configure the search based on card names")]
        HRESULT ConfigureCardNameSearch(
                        [in] LPSAFEARRAY pCardNames,                        // BSTR
                        [in,defaultvalue(NULL)] LPSAFEARRAY pGroupNames,    // BSTR
                        [in,defaultvalue("")] BSTR bstrTitle,
                        [in,defaultvalue(1)] LONG lFlags);

        [id(2),
         helpstring("Find and open a connection to the named Smart Card")]
        HRESULT FindCard([in,defaultvalue(EXCLUSIVE)]
                            SCARD_SHARE_MODES ShareMode,
                         [in,defaultvalue(T0)]
                            SCARD_PROTOCOLS Protocols,
                         [in,defaultvalue(1)] LONG lFlags,
                         [out,retval] LPSCARDINFO *ppCardInfo);
    };

    cpp_quote("#define CB_SCARDINFO     (sizeof(SCARDINFO))")
cpp_quote("#endif // !_LPSCARDLOCATE_DEFINED")


cpp_quote("")
cpp_quote("//////////////////////////////////////////////////////////////////")
cpp_quote("//")
cpp_quote("// SCardMgr Type Library")
cpp_quote("//")

[
    uuid(1461AAC1-6810-11D0-918F-00AA00C18068),
    version(1.0),
    //hidden,
    //lcid(0x0409),     // general language
    helpstring("SCardMgr 1.0 Type Library")
]
library SCardMgrLib
{
    // NOTE: must include stdole2.tlb due to problems with the Alpha stdole32.tlb.
    // This will generate warnings during build, but compile is successful.
    #ifdef _ALPHA_
    importlib("stdole2.tlb");
    #else
    importlib("stdole32.tlb");
    #endif
    importlib("SCardDat.tlb");

    [
        uuid(1461AAC7-6810-11D0-918F-00AA00C18068),
        helpstring("SCard Class"),
        //hidden,
        //licensed,
        aggregatable
    ]
    coclass CSCard
    {
        [default] interface ISCard;
    };

    [
        uuid(1461AACC-6810-11D0-918F-00AA00C18068),
        helpstring("SCardDatabase Class"),
        //hidden,
        //licensed,
        aggregatable
    ]
    coclass CSCardDatabase
    {
        [default] interface ISCardDatabase;
    };

    [
        uuid(1461AAD1-6810-11D0-918F-00AA00C18068),
        helpstring("SCardLocate Class"),
        //hidden,
        //licensed,
        aggregatable
    ]
    coclass CSCardLocate
    {
        [default] interface ISCardLocate;
    };

};