System.Win32.Com

Support library for interacting with base Microsoft COM services and API.

Documentation

data IUnknown_ a

Instances

Variant a => Variant (IUnknown_ a)

Methods

inVariant :: ArgIn (IUnknown_ a)

inVarList :: ArgIn [IUnknown_ a]

inVarIUnknown :: ArgIn (IUnknown (IUnknown_ a))

vtEltType :: IUnknown_ a -> VARENUM

resVariant :: ArgRes (IUnknown_ a)

defaultVariant :: IUnknown_ a

resVarList :: ArgRes [IUnknown_ a]

resVarIUnknown :: ArgRes (IUnknown (IUnknown_ a))

resVarIDispatch :: ArgRes (IDispatch (IUnknown_ a))

type IUnknown a = IUnknown_ a

iidIUnknown :: IID (IUnknown ())

Representing interface pointers via IUnknown a, where a is the particular IUnknown-extended interface, e.g., IUnknown IDispatch_. If the interface pointer is just IUnknown, use IUnknown ().

Extend this to IIDs and parameterize them over the interface they represent.

interfaceNULL :: IUnknown a

interfaceNULL is the NULL interface pointer.

isNullInterface :: IUnknown a -> Bool

isNullInterface iptr returns True iff iptr is the NULL pointer.

iidNULL :: IID ()

The null interface

queryInterface :: IID (IUnknown b) -> IUnknown a -> IO (IUnknown b)

queryInterface iid iunk queries iunk if it supports the iid interface, returning it. Notice that the type parameter to the IID matches up with that of the resulting interface pointer, giving you type safety - i.e., you can only use the interface pointer with methods supported by that interface

addRef :: IUnknown a -> IO Word32

addRef iptr increases the reference count of the interface pointer iptr. Notice that interface pointers are managed and finalized when on the Haskell heap, so manual reference counting is not required (and not encouraged as it could prevent the underlying object from being properly released, should you forget to decrement the ref count with release.)

release :: IUnknown a -> IO Word32

addRef iptr decrements the reference count of the interface pointer iptr.

withQueryInterface :: IID (IUnknown b) -> IUnknown a -> (IUnknown b -> IO c) -> IO c

(#) :: a -> (a -> IO b) -> IO b infixl 1

The # operator permits OO-style method application with do syntax:

 obj # method arg1 arg2

is equivalent to method arg1 arg2 obj, so this assumes that the COM method wrappers takes the this pointer as the last argument. Which the HDirect generated wrappers do and the various base method provided by this COM+Automation library.

(##) :: IO a -> (a -> IO b) -> IO b infixl 0

A variation on (#) where the this pointer is an action returning an object reference rather than the reference itself. Sometimes useful when you create one-off objects and call methods on them:

   (createObject arg1) ## startUp arg2

instead of the wieldier,

   obj <- createObject arg1
   obj # startUp arg2          or createObject arg1 >>= (startUp arg2)

coRun :: IO a -> IO a

coRun act is the toplevel action combinator to wrap up your COM actions in. Takes care of calling coInitialize (and un-initialize) for you.

coPerformIO :: IO a -> IO a

coPerformIO act runs act within an exception handler that catches and displays any COM API errors in a message box. For debugging purposes, mostly.

coUnsafePerformIO :: IO a -> a

coInitialize :: IO ()

coUnInitialize :: IO ()

data GUID

GUID is the Haskell representation for COM GUIDs.

Instances

Eq GUID

Methods

(==) :: GUID -> GUID -> Bool

(/=) :: GUID -> GUID -> Bool

Show GUID

Methods

showsPrec :: Int -> GUID -> ShowS

show :: GUID -> String

showList :: [GUID] -> ShowS

mkGUID :: String -> GUID

newGUID :: IO GUID

newGUID generates a new unique GUID.

stringToGUID :: String -> IO GUID

stringToGUID "{00000000-0000-0000-C000-0000 0000 0046}" translates the COM string representation for GUIDs into an actual GUID value.

guidToString :: GUID -> String

nullGUID :: GUID

data IID a

Representation of IIDs: Give the interface identifier a type parameter, so that when we come to define the Haskell type of IUnknown.QueryInterface() we can rely on the type checker to ensure that the IID passed to QueryInterface agrees with the interface at which we're using the interface pointer that's returned

Instances

Eq (IID a)

Methods

(==) :: IID a -> IID a -> Bool

(/=) :: IID a -> IID a -> Bool

Show (IID a)

Methods

showsPrec :: Int -> IID a -> ShowS

show :: IID a -> String

showList :: [IID a] -> ShowS

mkIID :: String -> IID a

stringToIID :: String -> IID a

guidToIID :: GUID -> IID a

iidToGUID :: IID a -> GUID

castIID :: IID a -> IID b

data CLSID

Instances

Eq CLSID

Methods

(==) :: CLSID -> CLSID -> Bool

(/=) :: CLSID -> CLSID -> Bool

Show CLSID

Methods

showsPrec :: Int -> CLSID -> ShowS

show :: CLSID -> String

showList :: [CLSID] -> ShowS

mkCLSID :: String -> CLSID

stringToCLSID :: String -> CLSID

guidToCLSID :: GUID -> CLSID

clsidToGUID :: CLSID -> GUID

clsidToDisplayName :: CLSID -> String

type LIBID = GUID

Type libraries are identified by a GUID, the LIBID.

mkLIBID :: String -> LIBID

type HRESULT = Int32

s_FALSE :: HRESULT

s_OK and s_FALSE are the boolean values encoded as HRESULTs.

s_OK :: HRESULT

s_OK and s_FALSE are the boolean values encoded as HRESULTs.

succeeded :: HRESULT -> Bool

failed :: HRESULT -> Bool

checkHR :: HRESULT -> IO ()

checkBool :: Int32 -> IO ()

checkBool mbZero raises a COM exception if mbZero is equal to...zero. The last error is embedded inside the exception.

returnHR :: IO () -> IO HRESULT

returnHR act runs the IO action act, catching any COM exceptions. Success or failure is then mapped back into the corresponding HRESULT. In the case of success, s_OK.

coFailHR :: HRESULT -> IO a

coFailWithHR :: HRESULT -> String -> IO a

coAssert :: Bool -> String -> IO ()

coOnFail :: IO a -> String -> IO a

coFail :: String -> IO a

coFail msg raised the E_FAIL COM exception along with the descriptive string msg.

isCoError :: Com_Exception -> Bool

isCoError e returns True for COM exceptions; False for IO exception values.

coGetErrorHR :: Com_Exception -> Maybe HRESULT

coGetException ei picks out the COM HRESULT from the exception, if any.

coGetErrorString :: Com_Exception -> String

coGetException ei returns a user-friendlier representation of the ei exception.

hresultToString :: HRESULT -> IO String

An alias to coGetErrorString.

data ComException

Constructors

ComException

Fields

• comException :: ComError
• comExceptionMsg :: String

Instances

Show ComException

Methods

showsPrec :: Int -> ComException -> ShowS

show :: ComException -> String

showList :: [ComException] -> ShowS

Exception ComException

Methods

toException :: ComException -> SomeException

fromException :: SomeException -> Maybe ComException

displayException :: ComException -> String

catchComException :: IO a -> (Com_Exception -> IO a) -> IO a

act catchComException (ex -> hdlr ex) performs the IO action act, but catches any IO or COM exceptions ex, passing them to the handler hdlr.

throwIOComException :: Com_Exception -> IO a

throwIOComException ex raises/throws the exception ex; ex is either an IOException or a ComException.

throwComException :: ComException -> IO a

coCreateInstance :: CLSID -> Maybe (IUnknown b) -> CLSCTX -> IID (IUnknown a) -> IO (IUnknown a)

coCreateInstance is the basic COM way of creating components. It takes a CLSID, an interface to aggregate on, a process context and an IID to create an object:

  coCreateInstance clsidAgentServer interfaceNULL LocalProcess iidIAgent

coCreateObject :: ProgID -> IID (IUnknown a) -> IO (IUnknown a)

createObject creates an object from its progID: createObject Agent.Server. getObject creates an object from its progID and initializes it with a given file: getObject "spreadsheet.exl" Excel.Application. If the filename is empty, getObject calls getActiveObject. getActiveObject tries to connect to an already running instance of the component: getActiveObject Word.Application. getFileObject opens a file or url and loads the associated or persistent object in it: getFileObject "spreadsheet.spd". coCreateInstance is the basic com way of creating components. It takes a CLSID, process context and IID to create an object: coCreateInstance clsidAgentServer Nothing LocalProcess iidIAgent.

NOTE: prepend co to specify the initial IID, otherwise iidIDispatch is used (see Automation for more).

coGetObject :: String -> IID (IUnknown a) -> IO (IUnknown a)

Bind to an object via its moniker string or display name.

coGetActiveObject :: ProgID -> IID (IUnknown a) -> IO (IUnknown a)

Look up and activate the given active/running object.

coGetFileObject :: String -> ProgID -> IID (IUnknown a) -> IO (IUnknown a)

Get Object from File and ProgID.

coCreateInstanceEx :: CLSID -> Maybe (IUnknown b) -> CLSCTX -> Maybe COSERVERINFO -> IID (IUnknown a) -> IO (IUnknown a)

data COSERVERINFO

Constructors

COSERVERINFO

Fields

• dwReserved1 :: DWORD
• pwszName :: WideString
• pAuthInfo :: Maybe COAUTHINFO
• dwReserved2 :: DWORD

data COAUTHIDENTITY

Constructors

COAUTHIDENTITY

Fields

• user :: String
• domain :: String
• password :: String
• flags :: ULONG

data COAUTHINFO

Constructors

COAUTHINFO

Fields

• dwAuthnSvc :: DWORD
• dwAuthzSvc :: DWORD
• pwszServerPrincName :: WideString
• dwAuthnLevel :: DWORD
• dwImpersonationLevel :: DWORD
• pAuthIdentityData :: Maybe COAUTHIDENTITY
• dwCapabilities :: DWORD

withObject :: IUnknown a -> [IUnknown a -> IO b] -> IO [b]

withObject_ :: IUnknown a -> [IUnknown a -> IO b] -> IO ()

withMethod :: (a -> IUnknown b -> IO c) -> [a] -> IUnknown b -> IO [c]

withMethod_ :: (a -> IUnknown b -> IO c) -> [a] -> IUnknown b -> IO ()

data CLSCTX

The CLSCTX enumeration is used by comCreateInstance to specify execution context in which we'd like to component to be created (just use AnyProcess if you're not too fussed..)

Constructors

CLSCTX_INPROC_SERVER

CLSCTX_INPROC_HANDLER

CLSCTX_LOCAL_SERVER

CLSCTX_INPROC_SERVER16

CLSCTX_REMOTE_SERVER

CLSCTX_INPROC_HANDLER16

CLSCTX_INPROC_SERVERX86

CLSCTX_INPROC_HANDLERX86

LocalProcess

InProcess

ServerProcess

AnyProcess

Instances

Enum CLSCTX

Methods

succ :: CLSCTX -> CLSCTX

pred :: CLSCTX -> CLSCTX

toEnum :: Int -> CLSCTX

fromEnum :: CLSCTX -> Int

enumFrom :: CLSCTX -> [CLSCTX]

enumFromThen :: CLSCTX -> CLSCTX -> [CLSCTX]

enumFromTo :: CLSCTX -> CLSCTX -> [CLSCTX]

enumFromThenTo :: CLSCTX -> CLSCTX -> CLSCTX -> [CLSCTX]

Show CLSCTX

Methods

showsPrec :: Int -> CLSCTX -> ShowS

show :: CLSCTX -> String

showList :: [CLSCTX] -> ShowS

type ProgID = String

ProgIDs are represented in Haskell as mere strings

progIDFromCLSID :: CLSID -> IO ProgID

progIDFromCLSID cid is the dual clsidFromProgID, attempting to translate in the other direction.

clsidFromProgID :: ProgID -> IO CLSID

clsidFromProgID progid looks up a ProgID and tries to translate it into its registered CLSID. Raises an IO exception if the ProgID isn't known.

printMessage :: Show a => a -> IO ()

printMessage val shows val in a message box.

putMessage :: String -> IO ()

putMessage str displays str in an informational message box containing an OK button.

messageBox :: String -> String -> Word32 -> IO ()

messageBox msg title flg displays a message box with the given title and content. The flg parameter is the bit pattern that makes up the MB_* settings you want to use (cf. underlying Win32 API documentation for MessageBox.)

outputDebugString :: String -> IO ()

outputDebugString str adds an

data OSVersionInfo

Constructors

OSVersionInfo Word32 Word32 Word32

isWindowsNT :: OSVersionInfo -> Bool

isWindows95 :: OSVersionInfo -> Bool

isWindows98 :: OSVersionInfo -> Bool

versionInfo :: OSVersionInfo

ifaceToAddr :: IUnknown a -> Ptr b

enumNext :: Word32 -> (Ptr any -> IO a) -> Word32 -> IUnknown b -> IO [a]

enumNextOne :: Word32 -> (Ptr any -> IO a) -> IUnknown b -> IO (Maybe a)

enumClone :: IUnknown a -> IO (IUnknown b)

enumReset :: IUnknown a -> IO ()

enumSkip :: Word32 -> IUnknown a -> IO ()

data BSTR

marshallBSTR :: String -> IO (Ptr String)

unmarshallBSTR :: Ptr String -> IO String

readBSTR :: Ptr (Ptr String) -> IO String

writeBSTR :: Ptr String -> String -> IO ()

freeBSTR :: Ptr a -> IO ()

type LPSTR = String

coFree :: Ptr a -> IO ()

coFree ptr releases storage that has been allocated via the COM task allocator; explicitly via coAlloc or indirectly via the APIs that handed the pointer to your code.

coAlloc :: Word32 -> IO (Ptr a)

coAlloc sz allocates sz bytes from the COM task allocator, returning a pointer. The onus is on the caller to constrain the type of that pointer to capture what the allocated memory points to.

marshallIUnknown :: IUnknown a -> IO (ForeignPtr b)

unmarshallIUnknown :: Bool -> Ptr b -> IO (IUnknown a)

readIUnknown :: Bool -> Ptr b -> IO (IUnknown a)

writeIUnknown :: Bool -> Ptr (Ptr (IUnknown b)) -> IUnknown a -> IO ()

unmarshallIUnknownFO :: ForeignPtr b -> IO (IUnknown a)

castIface :: IUnknown a -> IUnknown b

castIface obj performs a type

data WideString

marshallWideString :: WideString -> IO (Ptr WideString)

unmarshallWideString :: Ptr a -> IO WideString

writeWideString :: Ptr WideString -> WideString -> IO ()

readWideString :: Ptr WideString -> IO WideString

sizeofWideString :: Word32

freeWideString :: Ptr WideString -> IO ()

marshallGUID :: GUID -> IO (ForeignPtr GUID)

unmarshallGUID :: Bool -> Ptr GUID -> IO GUID

unmarshallGUID finalize ptr unpacks a pointer to an incoming GUID, wrapping it up as a Haskell GUID. If finalize is True, the GUID is assumed allocated via the COM task allocator and will be freed/finalized when the GUID becomes garbage.

writeGUID :: Ptr GUID -> GUID -> IO ()

writeGUID ptr g packs the Haskell GUID into the pointer; that is, it writes a pointer to the GUID value to ptr -- no copying of underlying structure.

readGUID :: Bool -> Ptr GUID -> IO GUID

copyGUID :: GUID -> IO (Ptr ())

A version of the GUID marshaller which copies rather than hands back a pointer to the (immutable) GUID.

sizeofGUID :: Word32

marshallIID :: IID a -> IO (ForeignPtr (IID a))

unmarshallIID :: Bool -> Ptr (IID a) -> IO (IID a)

writeIID :: Ptr (IID a) -> IID a -> IO ()

readIID :: Bool -> Ptr (Ptr (IID a)) -> IO (IID a)

sizeofIID :: Word32

copyIID :: IID t -> IO (Ptr ())

marshallCLSID :: CLSID -> IO (ForeignPtr GUID)

unmarshallCLSID :: Bool -> Ptr CLSID -> IO CLSID

writeCLSID :: Ptr CLSID -> CLSID -> IO ()

readCLSID :: Bool -> Ptr (Ptr CLSID) -> IO CLSID

sizeofCLSID :: Word32

copyCLSID :: CLSID -> IO (Ptr ())

invokeAndCheck :: (Ptr any -> Ptr b -> IO HRESULT) -> Int -> IUnknown a -> IO ()

invokeIt :: (Ptr any -> Ptr c -> IO a) -> Int -> IUnknown b -> IO a

invokeIt ( methPtr ip -> action) offset obj sets up a vtbl-indexed COM call, unmarshalling and indexing obj before passing it along to the method argument. The first argument is typically an FFI wrapped call to a function pointer (methPtr here).

loadTypeLib :: String -> IO (IUnknown a)

loadTypeLibEx :: String -> Bool -> IO (IUnknown a)

loadRegTypeLib :: GUID -> Int -> Int -> Int -> IO (IUnknown a)

queryPathOfRegTypeLib :: GUID -> Word16 -> Word16 -> IO String

createTypeLib :: String -> IO (IUnknown a)

type LCID = Word32

messagePump :: IO ()

postQuitMsg :: IO ()

Orphan instances

Eq (IUnknown_ a)

Equality of interface pointers is defined by the COM spec as being equality of IUnknown (pointers to) implementations.

Methods

(==) :: IUnknown_ a -> IUnknown_ a -> Bool

(/=) :: IUnknown_ a -> IUnknown_ a -> Bool

Show (IUnknown_ a)

Methods

showsPrec :: Int -> IUnknown_ a -> ShowS

show :: IUnknown_ a -> String

showList :: [IUnknown_ a] -> ShowS