/*++

Copyright (c) 1996  Microsoft Corporation

Module Name:

    SspsIdl

Abstract:

    IDL source for SspsIdl.DLL. This in-process server (DLL)
    encapsulates the services oriented COM interfaces for the
    Smart Card Service Provider (SSP) Data Services.

Author:

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

Environment:

    Win32

Revision History:

    Mike Gallagher (a-mgalla) 1/19/1997
    Chris Dudley (cdudley) 2/15/1997

Notes:

    1. This file will be processed by the MIDL tool to produce
        the type library (SspsIdl.tlb) and marshalling code. A
        header file named SspsIdl.h will be generated by the
        MIDL compiler for the ATL CPP code to use (and any other
        C/C++ code files).

    2. Rather than create separate IDL files for the C/C++, VB
        and Java languages, the decision has been made to create
        one IDL file that can be used by any language environment
        using standardized OLE Automation types.

    3. The #define'd constants in this MIDL file will NOT be
        registered into the type library! You will need to define
        these constants in your Visual Basic, Delphi, etc. code
        as needed unless the constant is not defined as a const
        variable in this IDL file. The constants will be defined
        for Java users. And, of course, the C/C++ coders can use
        the header file generated by the MIDL compiler as described
        above.

--*/


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


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

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

interface IByteBuffer;
interface ISCardTypeConv;
interface ISCardCmd;


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 _LPBYTE_DEFINED")
    cpp_quote("#define _LPBYTE_DEFINED")
    typedef [public] BYTE *LPBYTE;
cpp_quote("#endif // !_LPBYTE_DEFINED")

cpp_quote("#ifndef _LPCBYTE_DEFINED")
    cpp_quote("#define _LPCBYTE_DEFINED")
    typedef [public] const BYTE *LPCBYTE;
cpp_quote("#endif // !_LPCBYTE_DEFINED")

cpp_quote("#ifndef _BYTEARRAY_DEFINED")
    cpp_quote("#define _BYTEARRAY_DEFINED")
    typedef [helpstring("Helpful byte array."),
             //uuid(),
             //helpcontext(),
             version(1.0)]
    struct tagBYTEARRAY {
        HGLOBAL hMem;
        DWORD dwSize;
        [size_is(dwSize)] LPBYTE pbyData;
     } BYTEARRAY;

    cpp_quote("#define _CB_BYTEARRAY_DEFINED")
    cpp_quote("#define CB_BYTEARRAY     (sizeof(BYTEARRAY))")

    cpp_quote("#define _PBYTEARRAY_DEFINED")
    typedef [public] BYTEARRAY *PBYTEARRAY;

    cpp_quote("#define _PCBYTEARRAY_DEFINED")
    typedef [public] const BYTEARRAY *PCBYTEARRAY;

    cpp_quote("#define _LPBYTEARRAY_DEFINED")
    typedef [public] BYTEARRAY *LPBYTEARRAY;

    cpp_quote("#define _LPCBYTEARRAY_DEFINED")
    typedef [public] const BYTEARRAY *LPCBYTEARRAY;
cpp_quote("#endif // _BYTEARRAY_DEFINED")

cpp_quote("#ifndef _STATSTRUCT")
    cpp_quote("#define _STATSTRUCT")
    typedef [helpstring("Stream status structure."),
             //uuid(),
             //helpcontext(),
             version(1.0)]
    struct tagSTATSTRUCT {
        LONG        type;
        LONG        cbSize;
        LONG        grfMode;
        LONG        grfLocksSupported;
        LONG        grfStateBits;
     } STATSTRUCT;

    cpp_quote("#define _CB_STATSTRUCT_DEFINED")
    cpp_quote("#define CB_STATSTRUCT    (sizeof(STATSTRUCT))")

    cpp_quote("#define _LPSTATSTRUCT_DEFINED")
    typedef [public] STATSTRUCT* LPSTATSTRUCT;
cpp_quote("#endif // _STATSTRUCT_DEFINED")

cpp_quote("#ifndef _ISO_APDU_TYPE")
    cpp_quote("#define _ISO_APDU_TYPE")
    typedef [helpstring("ISO 7816-4 APDU Case types."),
             //uuid(),
             //helpcontext(),
             version(1.0)]
    enum tagISO_APDU_TYPE {
        ISO_CASE_1 = 1,
        ISO_CASE_2 = 2,
        ISO_CASE_3 = 3,
        ISO_CASE_4 = 4
    } ISO_APDU_TYPE;
cpp_quote("#endif // _ISO_APDU_TYPE")


cpp_quote("")
cpp_quote("//////////////////////////////////////////////////////////////////")
cpp_quote("//")
cpp_quote("// IByteBuffer Interface")
cpp_quote("//")

cpp_quote("#ifndef _LPBYTEBUFFER_DEFINED")
cpp_quote("#define _LPBYTEBUFFER_DEFINED")
    [
        object,
        uuid(E126F8FE-A7AF-11D0-B88A-00C04FD424B9),
        dual,
        //hidden,
        //oleautomation,
        helpstring("IByteBuffer Interface"),
        pointer_default(unique)
    ]
    interface IByteBuffer : IDispatch
    {
        // Includes -

        // Pointers -
        typedef [unique] IByteBuffer* LPBYTEBUFFER;
        typedef [unique] const IByteBuffer *LPCBYTEBUFFER;

        // Properties -
        [   id(0), propget, hidden,
            helpstring("Returns a pointer to the internal IStream object.")]
            HRESULT Stream( [out, retval] LPSTREAM* ppStream );
        [   id(0), propput, hidden,
            helpstring("Sets the internal IStream pointer.")]
            HRESULT Stream( [in] LPSTREAM pStream );

        // Methods -
        [   id(1),
            helpstring("Creates a new object with its own seek pointer that references the same bytes as the original.")
        ]
        HRESULT Clone([in, out] LPBYTEBUFFER* ppByteBuffer);

        [   id(2),
            helpstring("Ensures that any changes made to an object open in transacted mode are reflected in the parent storage.")
        ]
        HRESULT Commit([in] LONG grfCommitFlags);

        [   id(3),
            helpstring("Copies a specified number of bytes from the current seek pointer in the object to the current seek pointer in another object.")
        ]
        HRESULT CopyTo( [in,out] LPBYTEBUFFER* pByteBuffer,
                        [in] LONG cb,
                        [in,out, defaultvalue(NULL)] LONG* pcbRead,
                        [in,out, defaultvalue(NULL)] LONG* pcbWritten);

        [   id(4),
            helpstring("Initializes the object. This must be called prior to calling any other methods!")]
        HRESULT Initialize( [in, defaultvalue(1)] LONG lSize,
                            [in, defaultvalue(NULL)] BYTE* pData );

        [   id(5),
            helpstring("Restricts access to a specified range of bytes in the buffer object.")
        ]
        HRESULT LockRegion( [in] LONG libOffset,
                            [in] LONG cb,
                            [in] LONG dwLockType);

        [   id(6),
            helpstring("Reads a specified number of bytes from the buffer object into memory starting at the current seek pointer.")
        ]
        HRESULT Read(   [in,out] BYTE* pByte,
                        [in] LONG cb,
                        [in, out, defaultvalue(NULL)] LONG* pcbRead);

        [   id(7),
            helpstring("Discards all changes that have been made to a transacted stream since the last IByteBuffer::Commit call.")
        ]
        HRESULT Revert ( void );

        [   id(8),
            helpstring("Changes the seek pointer to a new location relative to the beginning of the buffer, to the end of the buffer, or to the current seek pointer.")
        ]
        HRESULT Seek(   [in] LONG dLibMove,
                        [in] LONG dwOrigin,
                        [in,out, defaultvalue(NULL)] LONG* pLibnewPosition);

        [   id(9),
            helpstring("Changes the size of the stream object.")
        ]
        HRESULT SetSize([in] LONG libNewSize);

        [   id(10),
            helpstring("Retrieves the STATSTG structure for this object.")
        ]
        HRESULT Stat(   [in,out] LPSTATSTRUCT pstatstg,
                        [in] LONG grfStatFlag);
        [   id(11),
            helpstring("Removes the access restriction on a range of bytes previously restricted with IByteBuffer::LockRegion.")
        ]
        HRESULT UnlockRegion(   [in] LONG libOffset,
                                [in] LONG cb,
                                [in] LONG dwLockType);

        [   id(12),
            helpstring("Writes a specified number from bytes into the stream object starting at the current seek pointer.")
        ]
        HRESULT Write(  [in,out] BYTE* pByte,
                        [in] LONG cb,
                        [in,out] LONG* pcbWritten);
    };
cpp_quote("#endif //_LPBYTEBUFFER_DEFINED")

cpp_quote("")
cpp_quote("//////////////////////////////////////////////////////////////////")
cpp_quote("//")
cpp_quote("// ISCardTypeConv Interface Definition")
cpp_quote("//")

cpp_quote("#ifndef _LPSCARDTYPECONV_DEFINED")
cpp_quote("#define _LPSCARDTYPECONV_DEFINED")
    [
        object,
        uuid(53B6AA63-3F56-11D0-916B-00AA00C18068),
        dual,
        helpstring("ISCardTypeConv Interface"),
        //hidden,
        //restricted,       // prevent macro programming?
        version(1.0),
        pointer_default(unique)
    ]
    interface ISCardTypeConv : IDispatch
    {
        // Includes:

        import "oaidl.idl";

        // Pointer(s);

        typedef [unique] ISCardTypeConv *LPSCARDTYPECONV;

        // Methods:

        [id(0), helpstring("Convert an array of bytes to an IByteBuffer")]
        HRESULT ConvertByteArrayToByteBuffer(
                    [in] LPBYTE pbyArray,
                    [in] DWORD dwArraySize,
                    [out,retval] LPBYTEBUFFER *ppbyBuffer);

        [id(1), helpstring("Convert an IByteBuffer to an array of bytes")]
        HRESULT ConvertByteBufferToByteArray(
                    [in] LPBYTEBUFFER pbyBuffer,
                    [out,retval] LPBYTEARRAY *ppArray);

        [id(2), helpstring("Convert an IByteBuffer to a SAFEARRAY(unsigned char)")]
        HRESULT ConvertByteBufferToSafeArray(
                    [in] LPBYTEBUFFER pbyBuffer,
                    [out,retval] LPSAFEARRAY *ppbyArray);

        [id(3), helpstring("Convert a SAFEARRAY(unsigned char) to an IByteBuffer")]
        HRESULT ConvertSafeArrayToByteBuffer(
                    [in] LPSAFEARRAY pbyArray,
                    [out,retval] LPBYTEBUFFER *ppbyBuff);

        [id(4), helpstring("Create an array of bytes")]
        HRESULT CreateByteArray(
                    [in] DWORD dwAllocSize,
                    [out,retval] LPBYTE *ppbyArray);

        [id(5), helpstring("Create an IByteBuffer object")]
        HRESULT CreateByteBuffer(
                    [in] DWORD dwAllocSize,
                    [out,retval] LPBYTEBUFFER *ppbyBuff);

        [id(6), helpstring("Create a SAFEARRAY(unsigned char)")]
        HRESULT CreateSafeArray(
                    [in] UINT nAllocSize,
                    [out,retval] LPSAFEARRAY *ppArray);

        [id(7), helpstring("Free a pointer to the memory block managed by the IStream")]
        HRESULT FreeIStreamMemoryPtr(
                    [in] LPSTREAM pStrm,
                    [in] LPBYTE pMem);

        [id(8), helpstring("Get a pointer to the memory block managed by the IStream")]
        HRESULT GetAtIStreamMemory(
                    [in] LPSTREAM pStrm,
                    [out,retval] LPBYTEARRAY *ppMem);

        [id(9), helpstring("How many bytes are in the given IStream")]
        HRESULT SizeOfIStream(
                    [in] LPSTREAM pStrm,
                    [out,retval] ULARGE_INTEGER* puliSize);
    };
cpp_quote("#endif // _LPSCARDTYPECONV_DEFINED")


cpp_quote("")
cpp_quote("//////////////////////////////////////////////////////////////////")
cpp_quote("//")
cpp_quote("// ISCardCmd Interface Definition")
cpp_quote("//")

cpp_quote("#ifndef _LPSCARDCMD_DEFINED")
cpp_quote("#define _LPSCARDCMD_DEFINED")
    [
        object,
        uuid(D5778AE3-43DE-11D0-9171-00AA00C18068),
        dual,
        helpstring("ISCardCmd Interface"),
        //hidden,
        //restricted,       // prevent macro programming?
        version(1.1),
        pointer_default(unique)
    ]
    interface ISCardCmd : IDispatch
    {
        // Includes -

        import "oaidl.idl";

        // Pointer(s) -

        typedef [unique] ISCardCmd *LPSCARDCMD;

        // Properties -

        [id(0), propget/*, defaultcollelem*/,
         helpstring("Get the raw ISO 7816 APDU string")]
        HRESULT Apdu([out,retval] LPBYTEBUFFER *ppApdu);

        [id(0), propput/*, defaultcollelem*/,
         helpstring("Copy a new APDU over the current one")]
        HRESULT Apdu([in] LPBYTEBUFFER pApdu);

        [id(1), propget/*, defaultcollelem*/,
         helpstring("Get the byte count (size) of the raw ISO 7816 APDU string")]
        HRESULT ApduLength([out,retval] LONG* plSize);

        [id(2), propget/*, defaultcollelem*/,
         helpstring("Get the raw reply ISO 7816 APDU string")]
        HRESULT ApduReply([out,retval] LPBYTEBUFFER *ppReplyApdu);

        [id(2), propput/*, defaultcollelem*/,
         helpstring("Set the raw reply ISO 7816 APDU string")]
        HRESULT ApduReply([in] LPBYTEBUFFER pReplyApdu);

        [id(3), propget/*, defaultcollelem*/,
         helpstring("Get the byte count (size) of the raw reply ISO 7816 APDU string")]
        HRESULT ApduReplyLength([out,retval] LONG* plSize);

        [id(3), propput/*, defaultcollelem*/,
         helpstring("Set the byte count (size) of the raw reply ISO 7816 APDU string")]
        HRESULT ApduReplyLength([in] LONG lSize);

        [id(4), propget/*, defaultcollelem*/,
         helpstring("Get the current class ID of the ISO 7816 APDU header")]
        HRESULT ClassId([out,retval] BYTE* pbyClass);

        [id(4), propput/*, defaultcollelem*/,
         helpstring("Assign a new class ID in the ISO 7816 APDU header")]
        HRESULT ClassId([in,defaultvalue(0)] BYTE byClass);

        [id(5), propget/*, defaultcollelem*/,
         helpstring("Get the current data portion of the ISO 7816 APDU string")]
        HRESULT Data([out,retval] LPBYTEBUFFER *ppData);

        [id(5), propput/*, defaultcollelem*/,
         helpstring("Assign a new data portion of the ISO 7816 APDU string")]
        HRESULT Data([in] LPBYTEBUFFER pData);

        [id(6), propget/*, defaultcollelem*/,
         helpstring("Get the current instruction ID of the ISO 7816 APDU header")]
        HRESULT InstructionId([out,retval] BYTE* pbyIns);

        [id(6), propput/*, defaultcollelem*/,
         helpstring("Assign a new instruction ID in the ISO 7816 APDU header")]
        HRESULT InstructionId([in] BYTE byIns);

        [id(7), propget/*, defaultcollelem*/,
         helpstring("Get the Le parameter (expected length of reply data) of the ISO 7816 APDU")]
        HRESULT LeField([out,retval] LONG* plSize);

        [id(8), propget/*, defaultcollelem*/,
         helpstring("Get the first parameter of the ISO 7816 APDU header")]
        HRESULT P1([out,retval] BYTE* pbyP1);

        [id(8), propput/*, defaultcollelem*/,
         helpstring("Assign a new first parameter in the ISO 7816 APDU header")]
        HRESULT P1([in] BYTE byP1);

        [id(9), propget/*, defaultcollelem*/,
         helpstring("Get the second parameter of the ISO 7816 APDU header")]
        HRESULT P2([out,retval] BYTE* pbyP2);

        [id(9), propput/*, defaultcollelem*/,
         helpstring("Assign a new second parameter in the ISO 7816 APDU header")]
        HRESULT P2([in] BYTE byP2);

        [id(10), propget/*, defaultcollelem*/,
         helpstring("Get the third parameter of the ISO 7816 APDU header")]
        HRESULT P3([out,retval] BYTE* pbyP3);

        [id(11), propget/*, defaultcollelem*/,
         helpstring("Get the reply status word")]
        HRESULT ReplyStatus([out,retval] LPWORD pwStatus);

        [id(11), propput/*, defaultcollelem*/,
         helpstring("Set (save) the reply status word")]
        HRESULT ReplyStatus([in] WORD wStatus);

        [id(12), propget/*, defaultcollelem*/,
         helpstring("Get the reply status SW1 byte.")]
        HRESULT ReplyStatusSW1([out,retval] BYTE* pbySW1);

        [id(13), propget/*, defaultcollelem*/,
         helpstring("Get the reply status SW2 byte.")]
        HRESULT ReplyStatusSW2([out,retval] BYTE* pbySW2);

        [id(14), propget/*, defaultcollelem*/,
         helpstring("Get the current ISO 7816-4 type of the encapsulated APDU.")]
        HRESULT Type([out,retval] ISO_APDU_TYPE* pType);

        [id(18), propget/*, defaultcollelem*/,
         helpstring("Get the T=1 Node Address")]
        HRESULT Nad([out,retval] LPBYTE pbNad);

        [id(18), propput/*, defaultcollelem*/,
         helpstring("Set (save) the T=1 Node Address")]
        HRESULT Nad([in] BYTE bNad);

        [id(19), propget/*, defaultcollelem*/,
         helpstring("Get the T=1 Reply Node Address")]
        HRESULT ReplyNad([out,retval] LPBYTE pbNad);

        [id(19), propput/*, defaultcollelem*/,
         helpstring("Set (save) the T=1 Reply Node Address")]
        HRESULT ReplyNad([in] BYTE bNad);

        // Methods -

        [id(15),
         helpstring("Build a valid ISO 7816 APDU string")]
        HRESULT BuildCmd([in] BYTE byClassId,
                         [in] BYTE byInsId,
                         [in,defaultvalue(0)] BYTE byP1,
                         [in,defaultvalue(0)] BYTE byP2,
                         [in,defaultvalue(NULL)] LPBYTEBUFFER pbyData,
                         [in,defaultvalue(NULL)] LONG* plLe);

        [id(16),
         helpstring("Clear the current APDU data")]
        HRESULT Clear(void);

        [id(17),
         helpstring("Encapsulate onother APDU into this one as data")]
        HRESULT Encapsulate([in] LPBYTEBUFFER pApdu,
                            [in] ISO_APDU_TYPE ApduType);
    };
cpp_quote("#endif //!_LPSCARDCMD_DEFINED")

