Node:COM Client Predicates, Next:, Previous:Terminology, Up:COM Client


COM Client Predicates


comclient_is_object(+Object)

Succeeds if Object "looks like" an object. It does not check that the object is (still) reachable from SICStus, see comclient_valid_object/1. Currently an object looks like '$comclient_object'(stuff) where stuff is some prolog term. Do not rely on this representation!

comclient_valid_object(+Object)

Succeeds if Object is an object that is still available to SICStus.

comclient_create_instance(+CLSID/ProgID, -Object)

Create an instance of the Class identified by CLSID (or ProgID). 

comclient_create_instance('Excel.Application', App)
Corresponds to CoCreateInstance.
comclient_get_active_object(+CLSID/ProgID, -Object)

Retrieves a running object of the Class identified by CLSID (or ProgID). 

comclient_get_active_object('Excel.Application', App)
An exception is thrown if there is no suitable running object. Corresponds to GetActiveObject.
comclient_invoke_put(+Object, +CallSpec, +ComInArg)

Set the property denoted by CallSpec to ComValue. Example: comclient_invoke_put(App, visible, 1)

comclient_invoke_method_proc(+Object, +CallSpec)

Call a method that does not return a value. See the desciption of CallSpec above for an example.

comclient_invoke_method_fun(+Object, +CallSpec, -ComValue)

Call a method that returns a value. Also use this to get the value of properties. See the desciption of CallSpec above for an example.

comclient_release(+Object)

Release the object and free the datastructures used by SICStus to keep track of this object. After releasing an object the term denoting the object can no longer be used to access the object (any attempt to do so will raise an exception). Please note: The same COM-object can be represented by different prolog terms. A COM object is not released from SICStus until all such representations have been released, either explicitly by calling comclient_release/1 or by calling comclient_garbage_collect.

You cannot use Obj1 == Obj2 to determine if two COM-objects are in fact identical. Instead use comclient_equal/2.

comclient_equal(+Object1, +Object2)

Succeeds if Object1 and Object2 are the same object. (It succeeds if their IUnknown interfaces are identical)

comclient_garbage_collect

Release Objects that are no longer reachable from SICStus. To achieve this the predicate comclient_garbage_collect/0 performs an atom garbage collection, i.e. garbage_collect_atoms/0, so it should be used sparingly.

comclient_is_exception(+ExceptionTerm)

Succeeds if ExceptionTerm is an exception raised by the comclient module. 

catch(<some code>,
      Exception,
      ( comclient_is_exception(E) ->
         handle_com_related_errors(E)
      ; otherwise -> % Pass other exceptions upwards
         throw(E)
      ))

comclient_exception_code(+ExceptionTerm, -ErrorCode)
comclient_exception_culprit(+ExceptionTerm, -Culprit)
comclient_exception_description(+ExceptionTerm, -Description)

Access the various parts of a comclient exception. The ErrorCode is the HRESULT causing the exception. Culprit is a term corresponding to the call that gave an exception. Description, if available, is either a term 'EXCEPINFO'(...) corresponding to an EXCEPINFO structure or 'ARGERR'(MethodName, ArgNumber).

The EXCEPINFO has six arguments corresponding to, and in the same order as, the arguments of the EXCEPINFO struct.

comclient_clsid_from_progid(+ProgID, -CLSID).

Obtain the CLSID corresponding to a particular ProgID. Uses the Win32 routine CLSIDFromProgID. You rarely need this since you can use the ProgID directly in most cases.

comclient_progid_from_clsid(+CLSID, -ProgID).

Obtain the ProgID corresponding to a particular CLSID. Uses the Win32 routine ProgIDFromCLSID. Rarely needed. The ProgID returned will typically have the version suffix appended.

Example, to determine what version of Excel.Application is installed: 

| ?- comclient_clsid_from_progid('Excel.Application, CLSID),
     comclient_progid_from_clsid(CLSID, ProgID).
CLSID = '{00024500-0000-0000-C000-000000000046}',
ProgID = 'Excel.Application.8' ?

comclient_iid_from_name(+IName, -IID)

Look in the registry for the IID corresponding to a particular Interface. Currently of little use. 

| ?- comclient_iid_from_name('IDispatch', IID).
IID = '{00020400-0000-0000-C000-000000000046}' ?

comclient_name_from_iid(+IID, -IName)

Look in the registry for the name corresponding to a particular IID. Currently of little use.