10.13.3 Predicate Reference

comclient_garbage_collect

Release Objects that are no longer reachable from SICStus Prolog. 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_object(+Object)

Succeeds if Object "looks like" an object. It does not check that the object is (still) reachable from SICStus Prolog, 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 Prolog.

comclient_equal(+Object1, +Object2)

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

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.

comclient_create_instance(+ID, -Object)

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

comclient_create_instance('Excel.Application', App)

Corresponds to CoCreateInstance.

comclient_get_active_object(+ID, -Object)

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

comclient_get_active_object('Excel.Application', App)

An exception is thrown if there is no suitable running object. Corresponds to GetActiveObject.

comclient_invoke_method_fun(+Object, +CallSpec, -ComValue)

Call a method that returns a value. Also use this to get the value of properties.

comclient_invoke_method_proc(+Object, +CallSpec)

Call a method that does not return a value.

comclient_invoke_put(+Object, +CallSpec, +ComInArg)

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

comclient_release(+Object)

Release the object and free the data structures used by SICStus Prolog 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 Prolog until all such representations have been released, either explicitly by calling comclient_release/1 or by calling comclient_garbage_collect/0.

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

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.