Copyright | (c) Sigbjorn Finne sof@dcs.gla.ac.uk 1999 |
---|---|
License | BSD-style (see the file libraries/base/LICENSE) |
Maintainer | sof@forkIO.com |
Stability | provisional |
Portability | portable |
Safe Haskell | None |
Language | Haskell2010 |
Support library for interacting with base Microsoft COM services and API.
Synopsis
- data IUnknown_ a
- type IUnknown a = IUnknown_ a
- iidIUnknown :: IID (IUnknown ())
- interfaceNULL :: IUnknown a
- isNullInterface :: IUnknown a -> Bool
- iidNULL :: IID ()
- queryInterface :: IID (IUnknown b) -> IUnknown a -> IO (IUnknown b)
- addRef :: IUnknown a -> IO Word32
- release :: IUnknown a -> IO Word32
- withQueryInterface :: IID (IUnknown b) -> IUnknown a -> (IUnknown b -> IO c) -> IO c
- (#) :: a -> (a -> IO b) -> IO b
- (##) :: IO a -> (a -> IO b) -> IO b
- coRun :: IO a -> IO a
- coPerformIO :: IO a -> IO a
- coUnsafePerformIO :: IO a -> a
- coInitialize :: IO ()
- coUnInitialize :: IO ()
- data GUID
- mkGUID :: String -> GUID
- newGUID :: IO GUID
- stringToGUID :: String -> IO GUID
- guidToString :: GUID -> String
- nullGUID :: GUID
- data IID a
- mkIID :: String -> IID a
- stringToIID :: String -> IID a
- guidToIID :: GUID -> IID a
- iidToGUID :: IID a -> GUID
- castIID :: IID a -> IID b
- data CLSID
- mkCLSID :: String -> CLSID
- stringToCLSID :: String -> CLSID
- guidToCLSID :: GUID -> CLSID
- clsidToGUID :: CLSID -> GUID
- clsidToDisplayName :: CLSID -> String
- type LIBID = GUID
- mkLIBID :: String -> LIBID
- type HRESULT = Int32
- s_FALSE :: HRESULT
- s_OK :: HRESULT
- succeeded :: HRESULT -> Bool
- failed :: HRESULT -> Bool
- checkHR :: HRESULT -> IO ()
- checkBool :: Int32 -> IO ()
- returnHR :: IO () -> IO HRESULT
- coFailHR :: HRESULT -> IO a
- coFailWithHR :: HRESULT -> String -> IO a
- coAssert :: Bool -> String -> IO ()
- coOnFail :: IO a -> String -> IO a
- coFail :: String -> IO a
- isCoError :: Com_Exception -> Bool
- coGetErrorHR :: Com_Exception -> Maybe HRESULT
- coGetErrorString :: Com_Exception -> String
- hresultToString :: HRESULT -> IO String
- data ComException = ComException {}
- catchComException :: IO a -> (Com_Exception -> IO a) -> IO a
- throwIOComException :: Com_Exception -> IO a
- throwComException :: ComException -> IO a
- coCreateInstance :: CLSID -> Maybe (IUnknown b) -> CLSCTX -> IID (IUnknown a) -> IO (IUnknown a)
- coCreateObject :: ProgID -> IID (IUnknown a) -> IO (IUnknown a)
- coGetObject :: String -> IID (IUnknown a) -> IO (IUnknown a)
- coGetActiveObject :: ProgID -> IID (IUnknown a) -> IO (IUnknown a)
- coGetFileObject :: String -> ProgID -> IID (IUnknown a) -> IO (IUnknown a)
- coCreateInstanceEx :: CLSID -> Maybe (IUnknown b) -> CLSCTX -> Maybe COSERVERINFO -> IID (IUnknown a) -> IO (IUnknown a)
- data COSERVERINFO = COSERVERINFO {}
- data COAUTHIDENTITY = COAUTHIDENTITY {}
- data COAUTHINFO = COAUTHINFO {}
- 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
- type ProgID = String
- progIDFromCLSID :: CLSID -> IO ProgID
- clsidFromProgID :: ProgID -> IO CLSID
- printMessage :: Show a => a -> IO ()
- putMessage :: String -> IO ()
- messageBox :: String -> String -> Word32 -> IO ()
- outputDebugString :: String -> IO ()
- data OSVersionInfo = 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 ()
- coAlloc :: Word32 -> IO (Ptr a)
- 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
- 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
- writeGUID :: Ptr GUID -> GUID -> IO ()
- readGUID :: Bool -> Ptr GUID -> IO GUID
- copyGUID :: GUID -> IO (Ptr ())
- 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 a -> 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
- 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 ()
Documentation
Instances
Eq (IUnknown_ a) Source # | Equality of interface pointers is defined by the COM spec as being equality of IUnknown (pointers to) implementations. |
Show (IUnknown_ a) Source # | |
Variant a => Variant (IUnknown_ a) Source # | |
Defined in System.Win32.Com.Automation inVariant :: ArgIn (IUnknown_ a) Source # inVarList :: ArgIn [IUnknown_ a] Source # inVarIUnknown :: ArgIn (IUnknown (IUnknown_ a)) Source # vtEltType :: IUnknown_ a -> VARENUM Source # resVariant :: ArgRes (IUnknown_ a) Source # defaultVariant :: IUnknown_ a Source # resVarList :: ArgRes [IUnknown_ a] Source # resVarIUnknown :: ArgRes (IUnknown (IUnknown_ a)) Source # resVarIDispatch :: ArgRes (IDispatch (IUnknown_ a)) Source # |
iidIUnknown :: IID (IUnknown ()) Source #
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 IID
s and parameterize them over the interface they
represent.
interfaceNULL :: IUnknown a Source #
interfaceNULL
is the NULL
interface pointer.
isNullInterface :: IUnknown a -> Bool Source #
isNullInterface iptr
returns True
iff iptr
is the NULL pointer.
queryInterface :: IID (IUnknown b) -> IUnknown a -> IO (IUnknown b) Source #
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 Source #
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 Source #
addRef iptr
decrements the reference count of the interface pointer iptr
.
(#) :: a -> (a -> IO b) -> IO b infixl 1 Source #
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 Source #
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 Source #
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 Source #
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 Source #
coInitialize :: IO () Source #
coUnInitialize :: IO () Source #
GUID
is the Haskell representation for COM GUIDs.
stringToGUID :: String -> IO GUID Source #
stringToGUID "{00000000-0000-0000-C000-0000 0000 0046}"
translates the
COM string representation for GUIDs into an actual GUID
value.
guidToString :: GUID -> String Source #
Representation of IID
s: 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
stringToIID :: String -> IID a Source #
stringToCLSID :: String -> CLSID Source #
guidToCLSID :: GUID -> CLSID Source #
clsidToGUID :: CLSID -> GUID Source #
clsidToDisplayName :: CLSID -> String Source #
checkBool :: Int32 -> IO () Source #
checkBool mbZero
raises a COM exception if mbZero
is equal
to...zero. The last error is embedded inside the exception.
returnHR :: IO () -> IO HRESULT Source #
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
.
coFail :: String -> IO a Source #
coFail msg
raised the E_FAIL
COM exception along with
the descriptive string msg
.
isCoError :: Com_Exception -> Bool Source #
isCoError e
returns True
for COM exceptions; False
for IO exception values.
coGetErrorHR :: Com_Exception -> Maybe HRESULT Source #
coGetException ei
picks out the COM HRESULT from the exception, if any.
coGetErrorString :: Com_Exception -> String Source #
coGetException ei
returns a user-friendlier representation of the ei
exception.
hresultToString :: HRESULT -> IO String Source #
An alias to coGetErrorString
.
data ComException Source #
Instances
Show ComException Source # | |
Defined in System.Win32.Com.Base showsPrec :: Int -> ComException -> ShowS # show :: ComException -> String # showList :: [ComException] -> ShowS # | |
Exception ComException Source # | |
Defined in System.Win32.Com.Base |
catchComException :: IO a -> (Com_Exception -> IO a) -> IO a Source #
act
performs the
IO action catchComException
(ex -> hdlr ex)act
, but catches any IO or COM exceptions ex
,
passing them to the handler hdlr
.
throwIOComException :: Com_Exception -> IO a Source #
throwIOComException ex
raises/throws the exception ex
;
ex
is either an IOException
or a ComException
.
throwComException :: ComException -> IO a Source #
coCreateInstance :: CLSID -> Maybe (IUnknown b) -> CLSCTX -> IID (IUnknown a) -> IO (IUnknown a) Source #
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) Source #
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) Source #
Bind to an object via its moniker string or display name.
coGetActiveObject :: ProgID -> IID (IUnknown a) -> IO (IUnknown a) Source #
Look up and activate the given active/running object.
coGetFileObject :: String -> ProgID -> IID (IUnknown a) -> IO (IUnknown a) Source #
Get Object from File and ProgID.
coCreateInstanceEx :: CLSID -> Maybe (IUnknown b) -> CLSCTX -> Maybe COSERVERINFO -> IID (IUnknown a) -> IO (IUnknown a) Source #
data COSERVERINFO Source #
data COAUTHIDENTITY Source #
data COAUTHINFO Source #
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..)
progIDFromCLSID :: CLSID -> IO ProgID Source #
progIDFromCLSID cid
is the dual clsidFromProgID
, attempting to translate
in the other direction.
clsidFromProgID :: ProgID -> IO CLSID Source #
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 () Source #
printMessage val
shows val
in a message box.
putMessage :: String -> IO () Source #
putMessage str
displays str
in an informational message box containing an OK button.
messageBox :: String -> String -> Word32 -> IO () Source #
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 () Source #
outputDebugString str
adds an
isWindowsNT :: OSVersionInfo -> Bool Source #
isWindows95 :: OSVersionInfo -> Bool Source #
isWindows98 :: OSVersionInfo -> Bool Source #
ifaceToAddr :: IUnknown a -> Ptr b Source #
coFree :: Ptr a -> IO () Source #
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) Source #
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) Source #
unmarshallIUnknownFO :: ForeignPtr b -> IO (IUnknown a) Source #
data WideString Source #
marshallWideString :: WideString -> IO (Ptr WideString) Source #
unmarshallWideString :: Ptr a -> IO WideString Source #
writeWideString :: Ptr WideString -> WideString -> IO () Source #
readWideString :: Ptr WideString -> IO WideString Source #
freeWideString :: Ptr WideString -> IO () Source #
marshallGUID :: GUID -> IO (ForeignPtr GUID) Source #
writeGUID :: Ptr GUID -> GUID -> IO () Source #
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.
copyGUID :: GUID -> IO (Ptr ()) Source #
A version of the GUID marshaller which copies rather than hands back a pointer to the (immutable) GUID.
sizeofGUID :: Word32 Source #
marshallIID :: IID a -> IO (ForeignPtr (IID a)) Source #
marshallCLSID :: CLSID -> IO (ForeignPtr GUID) Source #
sizeofCLSID :: Word32 Source #
invokeIt :: (Ptr any -> Ptr c -> IO a) -> Int -> IUnknown b -> IO a Source #
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).
messagePump :: IO () Source #
postQuitMsg :: IO () Source #