Allegro OLE Reference

add-connection-point cpc iid &key (limit 1) agent (cookie 1)
Function
Calling this function creates a new connection-point object and adds it to an existing connection-point-container, making interfaces for the specified IID available from that container. It is an error to try to add a second connection-point for an iid that is already available from the connection-point-container.
cpc
The connection-point-container object to support the new IID.
iid
The lisp-guid for the IID to be added.
limit
The maximum number of open connections to be allowed at one time.
agent
The agent to handle connection-events for this connection.
cookie
The initial cookie value to be provided for connections.

add-document doc container
Method: primary (document-mixin frame-mixin)
Adds a document object to a container object.
 add-inproc-factory factory
Function
Record factory for serving inproc OLE requests. Requests for its component-classid will be honored and a server interface returned to the caller.
 add-ref object
Generic Function
This function is called to announce the creation of a new reference to object. It gets called on the xxx-server interface when a client or OLE calls the AddRef for that interface.
add-ref obj
Method: primary (IUnknown)
Increments (ref-count obj).
add-ref ifc
Method: primary (IUnknown-client)
This method just calls the foreign pInterface's AddRef method, returning the integer that comes back from that method.
add-ref obj
Method: after (connection-point)
Adding a reference to a connection point also adds a reference to its container. The container shouldn't die until all its connection points are gone.
add-ref obj
Method: after (connection-point-enumerator)
Bumps the ref-count on the connection-point-container object.
add-ref obj
Method: after (connection-enumerator)
Does an add-ref on the connection-point object, as well.
add-ref obj
Method: after (advise-enumerator)
Bumps the ref-count on the adviser object.
 add-registry-key root path &optional (value nil value-p)
Function
This ensures the existance of the registry key that is reached by following path from the existing open root, creating the key if necessary, and optionally setting the default value of that key to value.
 add-registry-structure root structure
Function
This function creates registry structure subordinate to the open registry key root. The structure to be built is specified by the list structure. Each element in list must be a list specifying a key and value to be attached to root or a subkey and its structure. A key-and-value entry for root is represented as a list of the form (:value name value), where name is a string. A subkey and its structure is represented as a list of the form (key [value] . structure). In this element, the key entry is a string naming the subkey and the optional value, if present, becomes the default value associated with that subkey. The trailing portion of the entry, structure recursively describes the structure to be built for this new subkey, if any.
 add-site site doc
Method: primary (site-mixin document-mixin)
Adds a control site to a document object.
add-site site frame
Method: primary (site-mixin frame-mixin)
Adds a control site directly to a frame object.
 advise-connection object sink
Generic Function
Asks a ConnectionPoint object to accept a sink interface. Returns the cookie if the request was honored, otherwise it returns two values, NIL and an error code.
advise-connection ifc sink
Method: primary (IConnectionPoint-client t)
Invokes IConnectionPoint.Advise and returns the cookie or error code
advise-connection cp ifc-iunk
Method: primary (connection-point t)
If cp's current active connection count exceeds its limit, then this function releases ifc-iunk and returns two values, nil and CONNECT_E_ADVISELIMIT. If ifc-iunk doesn't support the interface that cp offers, then ifc-iunk is released and this function returns the two values nil and CONNECT_E_CANNOTCONNECT. Otherwise the request is valid. In this case ifc-iunk is released and the specified interface is added to cp's active connection set. Process-connection-event is called and this function returns cp's next cookie value.
 application-classid appname
Function
This function looks up an application in the registry and returns the associated classid. The appname must be a string naming an application that serves OLE objects. The function looks first for HKEY_CLASSES_ROOT/appname/CLSID. If that doesn't exist, it tries HKEY_CLASSES_ROOT/appname/CurVer to find an alternate name for the application. If either lookup provides a classid, then that is returned as a lisp-guid. Otherwise the function returns nil.
 ask-for-autotool source context &optional class &rest inits
Function
This function calls create-instance to ask for a new object and gets an IDispatch interface for it. The source and context arguments are passed to create-instance.
A successful result from create-instance results in the creation of a remote-autotool object that can be used to drive the IDispatch interface. This remote-autotool object is returned from ask-for-autotool. If the create-instance call fails, ask-for-autotool returns nil.
The class of the autotool object defaults to remote-autotool, but can be specified using the optional class argument. If specified, the class argument must name a subclass of remote-autotool, and the remaining arguments must be keywords and values specifying initialization arguments for that class.
 auto-getf tool prop &rest indices
Generic Function
Retrieves the value of a named property via an IDispatch interface.
tool
A remote-autotool object controlling a remote object.
prop
a string or symbol naming the property to access.
indices
Any additional values needed to specify a unique property value.
The form (auto-getf ...) is setf-able.
auto-getf tool prop &rest indices
Method: primary (remote-autotool t)
This primary method implements auto-getf for instances of remote-autotool. It should not be overridden for subclasses of remote-autotool; :before, :after and :around methods should be used to customize behavior.
auto-getf obj dispid &rest indices
Method: primary (IDispatch t)
This default method just returns a keyword that will be interpreted as an error. It should be overridden by a more specific method.
auto-getf obj dispid &rest indices
Method: primary (automaton t)
This method uses the dispids from the slot defs.
(setf auto-getf) value obj dispid &rest indices
Method: primary (t automaton t)
This method uses the dispids from the slot defs.
 automaton
Class
This is the base class for classes that support IDispatch for remote clients.
 automaton-class
Class
The metaclass that allows the use of the :dispid keyword in defclass slot definitions.
 auto-method tool method-name &rest args
Generic Function
Invokes a named method via IDispatch.
tool
A remote-autotool instance controlling a remote object.
method-name
a string or symbol naming the method to be invoked.
args
values to be passed as positional arguments followed by keywords and values designating named arguments. The first occurrence of a keyword symbol in the args list ends the positional arguments and provides the name of the first named argument. From that point on the args list must consist of alternating keywords and values.
Example 

   (auto-method loo-tool :fortify 12 "xxx" :agency 19 :part "a")
invokes the method named fortify with 4 arguments, two positional and two named agency and part.
The invoked OLE xxx.Invoke method returns its result in a Variant record whose contents are converted to Lisp and returned as the result of auto-method.
auto-method tool method-name &rest args &aux named-args args-rev
Method: primary (remote-autotool t)
This primary method implements auto-method for instances of remote-autotool. It should not be overridden for subclasses of remote-autotool; :before, :after and :around methods should be used to customize behavior.
auto-method obj dispid &rest args
Method: primary (IDispatch t)
This default method just returns a keyword that will be interpreted as an error. It should be overridden by a more specific method.
 binary-guid cpointer &optional (offset 0)
Function
This function accepts a reference to a foreign binary guid and returns the lisp-guid representing it. The cpointer argument addresses a block of foreign data that contains the 16-byte binary guid starting at offset bytes within the block.
 bool
Foreign Type
A C boolean, i.e., 0 => false, non-zero => true.
 bstr
Foreign Type
The OLE BSTR type.
 bstr-string bstr &optional release
Function
This function accepts a reference to a foreign bstr object and returns a lisp string containing the same data. If the optional release argument is non-nil, the bstr will be freed by a call on SysFreeString.
 check-return form &optional excepinfo
Macro
Expands to code that evaluates form and checks the result for OLE success. If the result indicates OLE failure, then ole-error is called, passing it the failure result and the excepinfo, if any.
 class-factory
Class
Instances of this class supply a Lisp wrapper for OLE object creation. The important slots are:
component-classid
a guid that OLE will use to request the services of this class factory. It is specified by the :classid keyword arg when a class-factory instance is created, and it remains constant for the life of the class-factory instance.
registration-code
an integer supplied by OLE when the class is registered.
locked
a status that can be read with lockedp.
children
a list of active objects created by this factory.
product-class
the symbol naming the Lisp class of objects manufactured by this class-factory object. The product-class will be a descendant of manufactured-object. It is specified by the :product-class initialization keyword when a class-factory instance is created, and it remains constant for the life of the class-factory instance.
allow-aggregation
a boolean that specifies whether clients can create instances with an outer-iunknown. The default is nil, meaning no outer-iunknown is allowed. The initialization keyword :allow-aggregation can be used to specify a non-default value.

close-control control &optional mode
Method: primary (ur-control)
This method, applicable to controls, closes the control and releases associated resources. The mode argument can be one of :nosave, :save-if-dirty, or :promptsave, or one of the associated numeric codes which are 1, 0, and 2, respectively, and defaults to :nosave
 close-registry-key rkey
Generic Function
Called to close the open registry key rkey.
close-registry-key k
Method: primary (registry-key)
This releases the OLE resources associated with the key and changes the argument's class so that it cannot again be used as a registry key. Closing an already closed key or one of the root registry keys (rkey-...) is legal and has no effect.
 code-guid d &optional (w1 0) (w2 0) (w3 49152) (l 70)
Function
This function accepts integer arguments defining the components of a guid and returns the associated lisp-guid. The arguments specify the components as they appear in the standard string representation, roughly "{d-w1-w2-w3-l}". The defaults allow compact expression of the common Microsoft IIDs, e.g., IID_IUnknown can be designated by (code-guid 0 0 0 #xc000 #x0046) or as (code-guid 0).
 compute-himetric-conversion c
Function
Call to initialize the *pixel-xxx-himetric* globals from the argument's DC
 connect-event-channel this &key event-interface-class
Method: primary (access-to-ole-control)
This method opens the event channel for the control argument. If the event-interface-class argument is present and non-nil, it names the interface class to use, otherwise the object's event-interface-class slot specifies the class to request. In either case the class must be one of those legal for the object.
 connection-enumerator
Class
Supports the IEnumConnections interface for a ConnectionPoint object.
 connection-point
Class
Instances of this class represent connection points to which external clients can attach via the OLE IConnectionPoint interface. A connection-point might support more than one connection simultaneously, or might be limited to one connection at a time, but it provides just one kind of interface to its clients. Connection-point objects are attached to an owning connection-point-container object at creation time.
 connection-point-container
Class
This OCX class supports the IConnectionPointContainer-server interface. Each instance holds some set of IconnectionPoint objects that are ready to support AdviseConnection calls.
 connection-point-enumerator
Class
This class provides IEnumConnectionPoints support for the connection-point-container class.
 connect-site site
Method: primary (site-mixin)
This method makes sure the OCX server for the control installed in this site is actually running and the object active.
 connect-to-server this &key inplace
Method: primary (access-to-ole-control)
This method makes sure the control argument (this) is being served. It stamps the object with the *dumplisp-generation-tick* when it makes the connection, and won't redo the connection unless called in a lisp with a different value of *dumplisp-generation-tick*
 container-mixin
Class
The mixin class to get container-specific behavior
 control
Class
This class specializes remote-autotool to run an OCX control object in a container.
 create-instance what iid &key
Generic Function
Asks for a new instance or connection to an existing instance, and returns the client interface object that results, if successful. If unsuccessful, returns a first value of nil and possibly other values describing the reason for failure.
what
an interface for a class factory object, a lisp-guid for a server, or a string naming a server.
iid
A lisp-guid specifying the IID of the interface desired
outer
an IUnknown interface object to be used as the controlling IUnknown for the new object. If omitted or nil the new object is independent.
context
The class context (:local, :inproc, :active) desired for the server.

create-instance clsid iid &key outer context
Method: primary (lisp-guid t)
Asks for instance creation via CoCreateInstance or for an interface to an active object via GetActiveObject. Returns the client interface object that results, if successful. If unsuccessful, returns two values: nil and the HRESULT from the attempted creation.
create-instance appname iid &key outer context
Method: primary (string t)
Asks for instance creation via CoCreateInstance. The classid is obtained from the registry entry for appname. Returns the client interface object that results, if successful. If unsuccessful, returns two values: nil and either the HRESULT from the attempted creation or a string describing the error.
create-instance ifc iid &key outer context
Method: primary (IClassFactory-client t)
Asks for instance creation via IClassFactory.CreateInstance. Returns the client interface object that results, if successful. If unsuccessful, returns two values: nil and the HRESULT from the attempted creation. The context keyword argument is ignored.
create-instance obj iid &key outer
Method: primary (class-factory t)
If the arguments are valid then a new instance of obj's product-class is created and queried for the interface specified by iid.
 cy
Foreign Type
The OLE CY (currency) type, a 64-bit integer, the represented value scaled by 10**4.
 date
Foreign Type
The high-precision windows DATE type, a double-float.
 def-automethod method ((arg-obj class) (arg-dispid dispid) &rest more) &body body
Macro
This macro expands into code that defines an IDispatch method, a specialization of auto-method.
method
The name of the method, as exported via Dispid mapping.
arg-obj
The symbol naming the object parameter to auto-method, for use in the method body.
class
A subclass of automaton which is to support this method.
arg-dispid
The symbol naming the dispid parameter to auto-method, for use in the method body.
dispid
The (integer) dispid that is to invoke this method.
more
Should be &rest somename to match the generic function definition.
body
The body of the method. Whatever value it computes will be returned as the result of the IDispatch method invocation.

def-client-interface iname &optional (documentation "Client interface class.") &key direct (release-heap :never) (release-heap-when-ok nil) (release-heap-never nil) (release-heap-always nil) (package (symbol-package iname))
Macro
This macro expands into the code needed to
  1. define all the client-side linkage functions for the named interface;
  2. load the client library code for the base interface, if any;
  3. define the CLOS class for the client interfaces;
  4. initialize the iid global symbol, if any.
Symbols created for methods and classes will be interned in the package of iname, the symbol naming the interface.
If the :direct keyword is specified, it provides a list of methods in the interface that are to be declared :call-direct.
The :release-heap-always, :release-heap-never and :release-heap-when-ok keywords specify which methods use which calling paradigm. The values are lists of method names to get the specified treatment.
The :release-heap keyword specifies the release-heap value to be used in the foreign-call definitions of all methods not named explicitly in one of :release-heap-never, :release-heap-always, or :release-heap-when-ok. The default is :never.
 defiid name &optional d (w1 0) (w2 0) (w3 49152) (l 70)
Macro
The form (defiid name) is used to declare that name is a global symbol whose value is an iid, but which is given a value in some other place. When specified with one or more values the defiid form expands to code that sets the variable's value to a lisp-guid for the specified iid. The value can be specified as a string, as in 

(defiid IID_IClassFactory "{00000001-0000-0000-C000-000000000046}")

Or numerically, as in the equivalent 

(defiid IID_IClassFactory 1 0 0 #xc000 #x0046)

The w1, w2, w3 and l arguments all default to the most common values for Microsoft iid's, so that the last could be specified as 

(defiid IID_IClassFactory 1)

This macro is rarely used, since the def-ole-interface macro includes this facility.
 def-ocx-class name supers slots &rest rest
Macro
This macro is an extended and specialized defclass. The extension is that supers, the list of superclasses, can contain the keyword :interfaces. If it does, the keyword is removed from the list of superclasses as far as the defclass is concerned. The names after the :interfaces keyword are interpreted as interface names, and code is generated to require the associated server library code for each one. Each entry after the :interfaces keyword can be an interface name or a list of interface names. If the entry is a list, then it means the ocx-class will support all the interfaces named in the list, but will actually provide an interface of the first class named in the list when asked for any of the other interfaces in that list. The list of interfaces need not explicitly include IUnknown as IUnknown is a superclass of every interface.
The specialization is that lisp-ole-object is always added as a last super-class before the interface classes. The effect is that the defined class supports IUnknown and its methods, and can build server side interfaces for all the named interface classes and for all their ancestral interface classes.
 def-ole-interface iname &rest methods-and-stuff
Macro
This macro provides a definition for an OLE interface. This definition is entered in a database that is available to the compiler when it processes def-client-interface and def-server-interface macros. Iname is the interface name, e.g., IUnknown or ITypeLib. The first entries after iname are keywords and (keyword value) pairs that affect the interface as a whole. After these come method definitions. The keywords and keyword-value entries can appear in any order, but none can be duplicated in the same def-ole-interface form. These keywords are:
:enumerator
Specifies that this interface is an enumerator, inheriting from the standard enumerator interface. Cannot be combined with the :base keyword.
(:base symbol)
Specifies the interface from which this interface inherits. The base interface must already be defined, but not necessarily loaded; the compiler will attempt to load needed definitions from the OLE definition library. The default base interface is IUnknown, which is almost always the right value. Specifying nil means there is no base interface, which would only be appropriate for the IUnknown interface. This keyword cannot be specified if the :enumerator keyword is present.
(:iid ...)
Specifies the interface id for this interface. The id can be specified in string form, as (:iid "{009541a0-3b81-101c-92f3-040224009c02}") or as a set of integer components, as (:iid #x300 0 0 #xc000 #x0046). In the latter case, elements after the first default to 0, 0, #xc000 and #x0046, in order, the most common entries for Microsoft OLE. For example, the short entry for IClassFactory would be (:iid 1).
(:iidname symbol)
Specifies a symbol to be made a global variable whose value is the (Lisp) guid structure for this iid. The default is to prefix IID_ in front of the interface name, as in IID_IUnknown. A non-nil symbol named here replaces the default symbol. Specifying nil suppresses the creation vof a global symbol holding the guid.
(:client-class symbol)
Specifies the name of the CLOS class whose instances are clients for this interface. The default is to suffix -client after the interface name, as in IClassFactory-client.
(:server-class symbol)
Specifies the name of the CLOS class whose instances are servers for this interface. The default is to suffix -server after the interface name, as in IClassFactory-server.
(:for-library boolean)
This entry controls whether the interface definition is to be part of the output of this compilation (:for-library t) or just used while compiling this file (:for-library nil). The (:for-library t) case is appropriate when the only thing in the source file is the def-ole-interface form (and probably an in-package form). The def-client-interface and/or def-server-interface forms would then appear in other files and the compiler would need to load the def-ole-interface data to process them. The (:for-library nil) case is the default and is appropriate when the def-client-interface and/or def-server-interface form(s) appear in the same file as the def-ole-interface form.

 def-ole-linkage package &rest keys-and-values
Macro
This macro loads a typelib specified by the keyword arguments and expands into a form that defines the lisp linkage to the objects described in that typelib. The form defines a package whose name is given as the package. Symbols exported from that package name classes and methods corresponding to the elements of the typelib's objects.
 def-server-interface name &key (mixin-class name) (mixin-class-documentation "Allegro Active mixin class.") (interface-class-documentation "Server interface class.") (package (symbol-package name)) (method-transforms nil)
Macro
This macro expands into code that
  1. defines the Vtable needed to serve this interface;
  2. initializes the global iid symbol, if any
  3. loads the server library code for the base interface, if any;
  4. defines the CLOS class for the server interfaces;
  5. defines the mixin class for Allegro active objects that wish to provide this interface.
Symbols created for methods and classes will be interned in the package of name, the symbol naming the interface.
The vtable for an object served by Allegro is a vector of pointers to linkage functions, one for each method in the interface. These linkage functions always receive the pInterface value for the interface as their first argument. The default action for any linkage function is to call a function with the same name as the method and return the result to the external caller. The arguments used in this call are, first, the unique server interface object associated with the incoming pInterface value, and then the integer values coming in as arguments to the linkage function. With no extra programmer effort the linkage function for IUnknown.AddRef will evaluate 

    (AddRef (find-the-server-interface-for pInterface))
It is often convenient to have the worker function call something other than the default function. Name clashes can make this desirable, for example. It is also often the case that an argument coming in to the linkage function is a pointer to data rather than an integer value. An example is a pointer to a guid coming in to the QueryInterface method. In this case it might be useful to perform some conversion in the linkage function and pass Lisp data to the worker function.
The :method-transforms keyword allows specialized linkage to be defined for any of the interface's methods. The value after the :method-transforms keyword must be a list of lists, each one modifying one of the methods defined for the interface. Each of these modification entries consists of a list of two elements, the symbol naming the method and a specification of the transform to be applied.
This transformation is specified as a list, the first element being the worker function to call and the remainder defining how to treat each incoming argument after the first. No specification is needed or possible for the first since it is always converted from a pInterface value to a Lisp server-interface object. The argument order is not changed by the transform. Instead, each argument after the first is either passed to the worker function unchanged or is transformed before being passed to the worker function. Each argument's treatment is specified as a form in which the symbol * represents the value actually received for that argument. So a * by itself says to pass that argument unchanged (foo *) says to call foo on that argument value and pass the result to the worker function. Any Lisp form can appear. (not (eql * 0)), for example, would convert a c-style boolean to a Lisp boolean.
Another example: 

(def-server-interface IUnknown
   :method-transforms
   ((QueryInterface (bxg-fad (binary-guid *) *))))
says that only the QueryInterface method for IUnknown-server objects is nonstandard. Its foreign-callable linkage function calls bxg-fad with three arguments. The first argument to bxg-fad is, of course, the xxx-server object associated with the incoming pInterface value. The second argument to bxg-fad is computed by calling binary-guid on the second argument coming in to the worker function. The third argument to bxg-fad is just the incoming third argument, unmodified.
In either case, whether the default method or a transform is used, the (integer) value returned from the function is passed on back to the caller.
By default, the mixin class has the same name as the interface, but this can be overridden with the :mixin-class keyword. Any Allegro active class that inherits from a server interface mixin class will automatically be able to respond to QueryInterface calls for the corresponding IID.
Note: currently, the :mixin-class keyword cannot be used to change the name of the mixin class.
 delete-registry-value key name &optional path
Generic Function
This function removes a specified name and its value from a specified registry entry. The registry entry is designated by giving a starting key, key, and an optional path. The path argument can be a string or a list of strings. If omitted or nil it causes the key argument to be the registry entry to search. If the named value is found in that registry entry then the name and associated value are removed from the registry.
 destroy-safearray v
Function
The argument v can be a lisp-safearray or an OLE safearray reference. If the latter, the argument is freed via a call to OLE's SafeArrayDestroy. If the former, the associated OLE safearray is destroyed and the lisp-safearray is marked as empty.
 disconnect access-to-control
Generic Function
Releases all OLE resources supporting the argument.
disconnect this
Method: primary (access-to-ole-control)
This method disconnects the object's event channels and releases the object's main interface.
disconnect channel
Method: primary (control-event-channel)
This method unadvises the associated connection point, then releases it.
 dispid-names object lcid
Generic Function
This function is called to get the mapping data that converts names to dispids. Each subclass of IDispatch should provide a primary method that returns a list of the following form, possibly taking into account the locale specified by lcid:
The mapping must be a list of lists. The first element of each sublist is a string or symbol naming an operation or property; the second element must be the integer dispid for that named operation or property. Subsequent elements, if any, provide the from argument names to dispids for that particular operation. For example, entry in the list that looks like this 
(decode 123 (rehash 9) (flights 27))
says that the decode operation has dispid 123 and that when used with decode, the names rehash and flights are represented by dispids 9 and 27, respectively. Note that the same name may represent different dispids when used as an argument name for different operations.
dispid-names obj lcid
Method: primary (IDispatch t)
If nothing more specific applies, there is no mapping information.
dispid-names obj lcid
Method: primary (automaton t)
The default for an automaton supplies the dispids from the slot defs when lcid is LOCALE_SYSTEM_DEFAULT, nil otherwise.
 do-as-process (&key (suppress-start-stop nil) (ide (find-package :ide)) (name '(format nil "ole-process-~d" (incf ole-process-name-counter))) (gate-symbol (gensym))) &rest body
Macro
This macro expands into code to run the forms of body in a separate process, releasing the client interfaces created by that process. The process executing the form will wait until the separate process completes. The do-as-process form evaluates to nil. Unless suppress-start-stop is specified and non-nil, the body forms will be preceded by a call to start-ole and followed by a call to stop-ole. If the form is expanded in an ide environment and the ide argument is not specified as nil, then the separate process will have initial bindings to allow the ide debugger to be invoked for errors. The name argument can be used to specify a form to evaluate (in the macro's environment) to get a name for the process. It defaults to a numbered generic name. The macro expansion allocates a gate for synchronization. The gate-symbol argument, if specified, must be a symbol that will be bound to the gate while the body forms are evaluated.
document-mixin
Class
This class is a superclass of all OLE document objects. Document objects correspond to application forms that can hold embeddable objects or controls. See the Allegro ActiveX documentation for details.
do-registry-subkey-names (var keyform &optional retform) &body body
Macro
This macro expands to code that loops over the subkeys of a registry key, evaluating the body with the loop variable bound to each subkey name in turn. The key whose subkeys are to be scanned is specified by the keyform, which must evaluate to a registry key that is open for reading. The body forms are evaluated with the var symbol let-bound to the name (a string) of each subkey in turn. When there are no more subkeys left, the retform is evaluated and the result returned as the value of the do-registry-subkey-names form.
var
a symbol naming the variable to be let-bound during the iteration
keyform
a form evaluating to a registry key open for reading
retform
a form to be evaluated when there are no more subkey names
body
an implicit loop body to be evaluated once for each iteration

do-registry-value-names (var keyform &optional retform) &body body
Macro
This macro expands to code that loops over the values of a registry key, evaluating the body with the loop variable bound to a description of each value in turn. The key whose values are to be scanned is specified by the keyform, which must evaluate to a registry key that is open for reading. The body forms are evaluated with the var symbol let-bound to a list of the name (a string) and the type (a keyword) of each value in turn. When there are no more values left, the retform is evaluated and the result returned as the value of the do-registry-value-names form.
var
a symbol naming the variable to be let-bound during the iteration
keyform
a form evaluating to a registry key open for reading
retform
a form to be evaluated when there are no more subkey names
body
an implicit loop body to be evaluated once for each iteration

enumerate-connection-points object
Generic Function
Returns an enumerator for the connection points of the connection point container object.
enumerate-connection-points ifc
Method: primary (IConnectionPointContainer-client)
Returns an IEnumConnectionPoints-client enumerator interface for ifc.
 enumerate-connections object
Generic Function
Returns an enumerator for the connection point object
enumerate-connections ifc
Method: primary (IConnectionPoint-client)
Invokes IConnectionPoint.EnumConnections to acquire a connection enumerator for ifc.
enumerate-connections cp
Method: primary (connection-point)
Returns a connection-enumerator for cp.
 enumerator-clone object
Generic Function
Returns a clone of the current state of the argument enumerator. This function gets called to deal with IEnumxxx.Clone method calls for classes that inherit from IEnumxxx. An appropriate method must exist for each subclass of IEnumxxx.
enumerator-clone ifc
Method: primary (IEnumxxx-client)
This invokes the x.Clone method on the client interface, then creates a new instance of the enumerator's class to hold the resulting pInterface, returning that Lisp object.
enumerator-clone enum
Method: primary (connection-point-enumerator)
Clone code for connection-point-enumerator objects.
enumerator-clone enum
Method: primary (connection-enumerator)
Clone code for connection-enumerator objects.
enumerator-clone enum
Method: primary (advise-enumerator)
Clone code for advise-enumerator objects.
 enumerator-interface-iid enumerator
Generic Function
This generic function is called to obtain the IID associated with an enumerator object. Methods must be provided so that this function responds correctly for instances of every subclass of IEnumxxx-server.
 enumerator-next interface reqct outbuffer
Generic Function
This function asks the enumerator available via interface to copy up to reqct items into the outbuffer. The destination buffer should be in foreign space or on the stack, but if a binary-element Lisp vector is supplied, and doesn't move during the function call, that is acceptable, too. The function returns the number of elements actually placed in the buffer.
enumerator-next ifc reqct outbuffer
Method: primary (IEnumxxx-client t t)
This method invokes ifc's x.Next method to retrieve the requested data.
 enumerator-reset object
Generic Function
This function is called to reset the enumerator available via object back to its initial state. An appropriate method must exist for each subclass of IEnumxxx.
enumerator-reset ifc
Method: primary (IEnumxxx-client)
This just invokes the x.Reset method on the client interface ifc.
 enumerator-skip object count
Generic Function
This function is called to have the enumerator object skip past the next count elements without returning them.
enumerator-skip ifc reqct
Method: primary (IEnumxxx-client t)
This just invokes the x.Skip method on the client interface object.
enumerator-skip obj skipct
Method: primary (IEnumxxx t)
This method invokes enumerator-step with NULL (0) pointers to inhibit copying data.
 enumerator-step enumerator cpointer
Generic Function
This function is called by pieces of the IEnumxxx system to process the next element of the enumeration. The first argument is the enumerator object in question, an instance of some subclass of IEnumxxx. The cpointer argument is either 0 or an address where data is to be placed. Each subclass of IEnumxxx must define a method for this GF specializing on the type of the enumerator argument. The method must return the length, in bytes, of the next element in the enumeration, or 0 if there are no more elements to be enumerated. If the return value is non-zero and the cpointer is non-zero then the method must also place the appropriate representation of the element in the area addressed by cpointer. Finally, the method must adjust the internal state of the enumerator to skip over the element returned, so that the next call will return the element after it.
There are no default methods for this generic function; each subclass of IEnumxxx must define its own method.
 event-tracing control &optional interface
Generic Function
Setf-able. Defaults to nil. Can be set on individual event channels to get low-level event tracing.
event-tracing this &optional interface
Method: primary (access-to-ole-control)
Applied to an object that represents a control; interface can be omitted, or the name of an interface, e.g. xxx:DWebBrowser2. When reading the state, the control must have a unique channel or interface must specify one of those attached to the object. When setting the state, omitting interface directs the function to set the state of all the object's channels.
(setf event-tracing) val this &optional interface
Method: primary (t access-to-ole-control)
Set the event-tracing attribute of either the specified channel, when interface is present, or all event channels, when interface is omitted.
 excepinfo
Foreign Type
The OLE EXCEPINFO structure.
 exception-info
Class
An object of this class carries excepinfo data
 execution-error
Class
A class of errors signaled by OLE code, a subclass of error
 extended-incoming-error
Class
An error class associated with bad HRESULT codes returned from OLE calls, and carrying excepinfo data. A subclass of incoming-error and exception-info.
 factory-idle factory
Generic Function
Called when the last child of a factory is released and the factory is not locked.
factory-idle factory
Method: primary (class-factory)
The default method does nothing.
 failure hr
Macro
Expands to code that evaluates the form hr and tests the (integer) result, returning true if and only if it is an OLE failure code.
 file-is-storage-p s
Function
Accepts a string naming a file. Returns non-nil if and only if the file is formatted as a storage.
 find-connection-point object iid
Generic Function
Returns the connection point that object provides for the interface identified by iid. The iid argument must be a lisp-guid object. If object does not provide a connection point of the requested type, this function returns nil.
find-connection-point ifc guid
Method: primary (IConnectionPointContainer-client t)
Uses IConnectionPointContainer.FindConnectionPoint to obtain a connection point. If there is one, this method returns an IConnectionPoint-client interface for it, otherwise it returns nil.
 format-idl outfilename &optional (typelib (car loaded-typelibs))
Function
This function writes an idl file for a typelib internalized by lisp. The outfilename argument is a string naming the place to write the idl file. The typelib argument is a lisp-typelib, the result of, for example, a call to load-typelib. If typelib is omitted, the last loaded typelib is the source for the generated idl.
 frame-mixin
Class
This class is a superclass of all OLE container objects. Container objects correspond to applications that use embeddable objects or controls. See the Allegro ActiveX documentation for details.
free-bstr bstr
Function
The argument to free-bstr must be a reference (address) to a bstr object allocated by string-bstr or obtained from some external source. Unless the reference is the NULL pointer 0, SysFreeString is called to free the foreign data.
 free-unicode c
Function
The argument must be a unicode item allocated by string-unicode. Its memory is freed. Do not call free-unicode on data allocated using with-foreign-data or with-unicode-argument.
 get-class-object classid context iid
Function
Calls CoGetClassObject to ask for access to an OLE component. The component is identified by its classid and context, the desired interface by its IID. If the CoGetClassObject call is successful then the new client interface object is returned; otherwise the function returns two values: nil and the HRESULT from the CoGetClassObject call.
classid
The guid for the desired class. Can be specified as a lisp-guid, a binary guid (in foreign space, i.e., by address), or a string in the standard format, i.e., {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}.
context
one or more of the following values or'ed together:
  • CLSCTX_INPROC_SERVER
  • CLSCTX_INPROC_HANDLER
  • CLSCTX_LOCAL_SERVER
  • CLSCTX_REMOTE_SERVER
iid
A lisp-guid specifying the desired interface on the object.

get-connection-container object
Generic Function
Returns the connection point container that owns object.
get-connection-container ifc
Method: primary (IConnectionPoint-client)
Invokes IConnectionPoint.GetConnectionPointContainer to return an IConnectionPointContainer-client interface.
 get-connection-interface object
Generic Function
Returns the lisp-guid object for the iid offered by the argument.
get-connection-interface ifc
Method: primary (IConnectionPoint-client)
Invokes IConnectionPoint.GetConnectionInterface and returns the unique lisp-guid corresponding to the result.
get-connection-interface cp
Method: primary (connection-point)
Returns the lisp-guid for cp.
 get-type-attr ifc &key use-registry check-native displaced-guid
Method: primary (ITypeInfo-client)
Calls several ITypeInfo methods and returns a lisp-typeinfo structure that holds the retrieved information.
 get-type-info object index &key locale
Generic Function
Asks for the indexed entry in the object's typeinfo structure. Signals an error if the entry does not exist. The index value must be less than the number returned from get-type-info-count.
get-type-info ifc i &key locale
Method: primary (IDispatch-client t)
This method uses ifc's IDispatch.GetTypeInfo method to construct an ITypeInfo-client interface for ifc's i-th typeinfo element.
get-type-info tool i &key locale
Method: primary (remote-autotool t)
This is reflected to tool's IDispatch interface.
 get-type-info-count object
Generic Function
Returns the number of TypeInfo entries available for object
get-type-info-count ifc
Method: primary (IDispatch-client)
Calls IDispatch.GetTypeInfoCount and returns the result.
get-type-info-count tool
Method: primary (remote-autotool)
This is reflected to tool's IDispatch interface.
get-type-info-count obj
Method: primary (automaton)
The default method for automatons says there's no type info.
 guid
Foreign Type
The OLE guid type in foreign space.
 guid-binary lisp-guid
Function
Returns a reference to (i.e., integer address of) the foreign-allocated binary form of the lisp-guid argument.
 guid-name lisp-guid
Function
Returns a Lisp string containing the standard human-readable form of the lisp-guid argument.
 guid-p object
Function
Returns true if and only if the argument is a lisp-guid object.
 guid-typeinfo ifc guid
Method: primary (ITypeLib-client t)
Calls ITypeLib.GetTypeInfoOfGuid, returning the ITypeInfo-client interface if the call is successful, nil otherwise.
 guid-typelib guid &key (major-version 1) (minor-version 0) (locale *ole-locale*) (error-ret nil errorp)
Function
Returns an ITypeLib-client interface for the registered typelibrary with the given guid, versions, and locale. If the specified library is not available, then an error is signaled unless the error-ret keyword argument is specified, in which case the error-ret value is returned.
 h f
Macro
Expands into code to evaluate f and return the OLE 'handle' associated with the result. Typically the value of f is an interface object and (h f) is the associated pInterface value.
 hresult obj
Generic Function
Returns the hresult value associated with an error object.
hresult (obj incoming-error)
Method: nil Returns the hresult value that caused obj to be created.
nil
 hresult-code hr
Macro
Expands to code that evaluates the form hr and extracts the OLE hresult CODE portion.
 hresult-facility hr
Macro
Expands to code that evaluates the form hr and extracts the OLE hresult FACILITY portion.
 IClassFactory
Class
Allegro Active mixin class.
 IClassFactory-client
Class
Client interface class.
 IClassFactory-server
Class
Server interface class.
 IConnectionPoint
Class
Allegro Active mixin class.
 IConnectionPoint-client
Class
Client interface class.
 IConnectionPointContainer
Class
Allegro Active mixin class.
 IConnectionPointContainer-client
Class
Client interface class.
 IConnectionPointContainer-server
Class
Server interface class.
 IConnectionPoint-server
Class
Server interface class.
 IDispatch
Class
Allegro Active mixin class.
 IDispatch-client
Class

 idispatch-invoke-exception
Class
An object of this class is created to signal an exception in an auto-method.
 IDispatch-server
Class
Server interface class.
 IEnumConnectionPoints
Class
Allegro Active mixin class.
 IEnumConnectionPoints-client
Class
Client interface class.
 IEnumConnectionPoints-server
Class
Server interface class.
 IEnumConnections
Class
Allegro Active mixin class.
 IEnumConnections-client
Class
Client interface class.
 IEnumConnections-server
Class
Server interface class.
 IEnumxxx
Class
This is a base class for all enumerator mixin classes. It provides default behavior for the standard enumerator operations.
 IEnumxxx-client
Class
This is a base class for all client enumerator interface classes. It provides default behavior for the standard enumerator operations.
 IEnumxxx-server
Class
This is a base class for all enumerator server interface classes. It provides default behavior for the standard enumerator operations.
 iid-client-interface-type iid
Function
This function returns the name of the client interface class associated with the lisp-guid iid. If there is no associated client interface class, then an error is signalled.
 IID_IClassFactory
OLE IID
{00000001-0000-0000-c000-000000000046}
 IID_IConnectionPoint
OLE IID
{b196b286-bab4-101a-b69c-00aa00341d07}
 IID_IConnectionPointContainer
OLE IID
{b196b284-bab4-101a-b69c-00aa00341d07}
 IID_IEnumConnectionPoints
OLE IID
{b196b285-bab4-101a-b69c-00aa00341d07}
 IID_IEnumConnections
OLE IID
{b196b287-bab4-101a-b69c-00aa00341d07}
 IID_IMalloc
OLE IID
{00000002-0000-0000-c000-000000000046}
 IID_IStorage
OLE IID
{0000000b-0000-0000-c000-000000000046}
 IID_ITypeInfo
OLE IID
{00020401-0000-0000-c000-000000000046}
 IID_ITypeLib
OLE IID
{00020402-0000-0000-c000-000000000046}
 IID_IUnknown
OLE IID
{00000000-0000-0000-c000-000000000046}
 IID_NULL
OLE IID
{00000000-0000-0000-0000-000000000000}
 IMalloc
Class
Allegro Active mixin class.
 IMalloc-client
Class
Client interface class.
 incoming-error
Class
An error class associated with bad HRESULT codes returned from OLE calls, but without excepinfo data. A subclass of execution-error.
 install-control control site
Method: primary (ur-control t)
Attaches a control object to an existing empty site.
 interface-handle ifc
Generic Function
Returns the pInterface "handle" of a client or server interface object.
 Invoke object dispid riid lcid mode pdisp pvarret pexcept pargerr
Generic Function
This function attempts to perform the specified IDispatch operation, returning an OLE success or failure code.
object
the object that has IDispatch behavior, typically an IDispatch
dispid
the symbol or string naming the operation to perform
riid
ignored
lcid
ignored
mode
one of:
  • DISPATCH_PROPERTYGET - retrieve property named by dispid
  • DISPATCH_PROPERTYPUT - store value in property
  • DISPATCH_METHOD - call method
  • (logior DISPATCH_PROPERTYGET DISPATCH_METHOD) - do either of these
pdisp
address of a foreign-allocated dispparams structure or 0
pvarret
address of a foreign-allocated variant object into which a result value can be stored
pexcept
address of a foreign-allocated excepinfo object into which exception information can be stored
pargerr
not used, should be 0

Invoke obj dispid riid lcid mode pdisp pvarret pexcept pargerr
Method: primary (IDispatch t t t t t t t t)
Responds to an IDispatch.Invoke to carry out the remote request.
 IStorage
Class
Allegro Active mixin class.
 IStorage-client
Class
Client interface class.
 IStorage-server
Class
Server interface class.
 ITypeInfo
Class
Allegro Active mixin class.
 ITypeInfo-client
Class
Client interface class.
 ITypeLib
Class
Allegro Active mixin class.
 ITypeLib-client
Class
Client interface class.
 IUnknown
Class
This is the mixin class that allows a lisp-ole-object to provide an IUnknown-server interface on demand. It is not usually specified as an explicit interface in def-ocx-class, because it will be included automatically if it is not explicitly present. The OLE methods for IUnknown are AddRef, Release, and QueryInterface. The first two are implemented as add-ref and release calls on the server-interface object, which normally just calls add-ref and release, respectively, on the interface's owning lisp-ole-object. The default behavior of QueryInterface is to call query-interface on the owning lisp-ole-object and report the result to the client.
 IUnknown-client
Class
This is the base class from which all standard client interfaces inherit their add-ref, release and query-interface behavior.
 IUnknown-server
Class
Server interface class.
 lisp-date
Type
This is a Lisp object holding (in its lisp-date-ut element) a Lisp universal-time value. It is the typed value associated with a COM date value.
 lisp-date-to-ole-date lisp-date
Function
Returns the OLE double-float value encoding the lisp GMT universal-time
 lisp-date-ut ld
Function
Returns the universal time held in the lisp-date ld.
 lisp-elemdesc
Type
A structure describing an element in a function or structure. It has components for the element name, type, and flow (in, out, lcid retval).
 lisp-elemdesc-flow led
Function
Returns a subset of (:in :out :retval :lcid)
 lisp-elemdesc-name led
Function
Returns a string naming the element described by lisp-elemdesc led.
 lisp-elemdesc-tdesc led
Function
Returns a lisp ctype description of the lisp-elemdesc led.
 lisp-funcdesc
Type
A lisp structure holding the typelibrary information for one function.
 lisp-funcdesc-elemdescFunc lfd
Function
Returns a lisp ctype description of the type of data returned by the function described by the lisp-funcdesc lfd. This may be :empty.
 lisp-funcdesc-invkind lfd
Function
Returns the (numeric) invkind code for the function described by lisp-funcdesc lfd.
 lisp-funcdesc-name lfd
Function
Returns a string naming the function described by lisp-funcdesc lfd.
 lisp-funcdesc-params lfd
Function
Returns a list of lisp-elemdesc structures describing the parameters to the function described by the lisp-funcdesc lfd. This will be nil if there are no parameters.
 lisp-guid
Type
Objects of this type represent OLE guid's. Each unique guid is represented by a unique lisp-guid, which has slots holding: The functions string-guid, binary-guid, unique-guid and code-guid find or create the lisp-guid object corresponding to some representation. The functions guid-name and guid-binary return string and binary representations of the argument lisp-guid. A lisp-guid can be used as an eql specializer in a method; a make-load-form method associated with the type ensures correct semantics in compiled files.
 lisp-ole-object
Class
This is the base class for all lisp-defined objects that make OLE interfaces available to callers. It provides machinery that builds interfaces as needed, along with an object-level reference count accessable via the generic function ref-count. A per-object tracing flag allows marking objects for tracing.
 lisp-safearray
Type
This is a lisp object providing access to an OLE safearray. The lisp-safearray holds a pointer to the OLE (foreign) safearray and an indication of the element type in that safearray.
 lisp-typeinfo
Type
This structure is the lisp representation of a Type Library or entry.
 lisp-typeinfo-functions lti
Function
Returns the list of lisp-funcdesc structures describing functions belonging to the lisp-typeinfo structure lti.
 lisp-typeinfo-interface-flags lti
Function
Returns a list of keywords associated with the interface described by the lisp-typeinfo structure lti. This list will include :source if and only if the interface is an event (i.e., call-back) interface.
 lisp-typeinfo-interfaces lti
Function
Returns the list of lisp-typeinfo structures describing the interfaces belonging to the lisp-typeinfo structure lti.
 lisp-typeinfo-kind lti
Function
Returns one of the following: :enum :record :module :interface :dispatch :coclass :alias :union
 load-typelib &key guid major-version minor-version pathname application &allow-other-keys
Function
This function tries to read a typelib and return the corresponding lisp structure. The typelib to process can be specified by giving either its pathname, or its major and minor version numbers with its guid or an application name. If the typelib is found, its data is internalized and can be formatted as idl.
 lockedp obj
Generic Function
Returns non-nil if and only if the argument is locked, in whatever sense is defined for obj's type.
lockedp (obj class-factory)
Method: nil Returns the state of the class-factory's locked slot. This slot is initially nil; its state is changed by calls to lock-server.
nil
 lock-server object mode
Generic Function
This function locks or unlocks the factory object. If mode is non-nil then the factory is locked; if mode is nil the factory is unlocked.
lock-server ifc flag
Method: primary (IClassFactory-client t)
This method invokes the IClassFactory.LockServer method.
lock-server obj lockit
Method: primary (class-factory t)
Sets the state of the locked slot based on the incoming argument. If the factory is left unlocked and has no children, factory-idle is called.
 make-client-interface-instance class pinterface &optional addref
Function
Creates and returns a client interface object of specified class for the pinterface argument. If the class is not already defined, the function attempts to load the client interface code from the OLE libraries first. If the optional addref argument is non-nil then an AddRef is done on the pinterface. If the pinterface argument is 0, however, make-client-interface-instance returns nil without trying to do an addref.
 make-lisp-date ut
Function
Builds and retuns a new lisp-date whose universal time is ut.
 make-lisp-safearray dims &key (element-type 'variant etype-p) (element-code nil ecode-p)
Function
This function constructs a lisp-safearray having specified dimensions and element type; it also allocates foreign space for the OLE part of the safearray. The dimensions are specified by dims, which can be a single integer or a list of integers. The element type can be specified symbolically with the :element-type keyword or via the OLE element type code via the :element-code keyword. At most one of these two keywords can be specified. Legal values for :element-type are
make-scode severity facility code
Function
This function returns the 32-bit integer value encoding the specified severity, facility, and code components, which must be supplied as integers.
 *malloc-interface*
Variable
Holds the IMalloc interface acquired from OLE at start-ole time. This interface is needed as an argument for a few methods calls.
 manufactured-object
Class
This is the base mixin class for all lisp objects that are to be made available to clients via a class-factory object.
 next-connection-point enumerator
Generic Function
Returns the next connection point object available from enumerator, or nil if there are no more.
next-connection-point ifc
Method: primary (IEnumConnectionPoints-client)
Uses the enumeration methods to retrieve the next IConnectionPoint-client interface from the enumerator ifc, returning nil if there are no more.
 object-name object
Generic Function
This function must return a symbol naming the object uniquely within the set of named OLE objects in the application.
 object-window object
Generic Function
This function must return the window handle for the window associated with object. This is generally applicable to containers and controls.
 ole-date-to-lisp-date ole-date
Function
Returns the lisp-date universal-time encoding for the GMT ole-date
 ole-error hcode &optional xi
Function
ole-error is typically called with an HRESULT value as the first argument. If the excepinfo is present and non-nil and non-zero, then it must reference a foreign excepinfo structure that was filled in by the OLE operation producing the error hcode. ole-error signals an error of type incoming-error if there was no excepinfo, extended-incoming-error if there was excepinfo.
 ole-free object
Generic Function
This function is called when the release function decrements a ref-count to 0. The primary method defined for a lisp-ole-object frees the associated server interfaces. This method should not be overridden. Additional behavior should be added with :before, :after, or :around methods.
ole-free obj
Method: after (automaton)
An after method for an automaton lets its factory, if any, know the new situation.
 *ole-language*
Variable
Holds the default language value for the running system. Initialized from the :language keyword supplied (or defaulted) when start-ole is called.
 *ole-locale*
Variable
Holds the default locale value for the running system. Initialized from the :locale keyword supplied (or defaulted) when start-ole is called.
 open-ole-storage location s &key (mode :direct) (direction :io) (share :exclusive) (priority nil) (delete-on-release nil) (if-exists nil) (if-does-not-exist (case direction (:input :error) (t :create))) (exclude nil)
Function
Opens an OLE Storage and returns the IStorage-client interface.
open-ole-stream location s &key (mode :direct) (direction :input) (share :exclusive) (priority nil) (delete-on-release nil) (if-exists nil) (if-does-not-exist (case direction (:input :error) (t :create)))
Function
Opens an OLE storage stream and returns the IStream-client interface.
open-registry-key root path &key (access :read) (create nil) (error-return nil error-return-p)
Generic Function
Calling this function creates and returns a registry-key instance that provides access to a specified key in the registry. It can be used to add a key entry to the registry. The registry entry to be opened is specified by giving a path to it from some already-open key. The root argument must be an open registry-key instance. The path can be a single string naming a subkey of the root. Alternatively, it can be a list of strings describing a path from the root. For example, a path of ("Class" "Ptr") designates the "Ptr" subkey of the "Class" subkey of the root. The path can be nil, in which case a second access key to the root registry entry is being requested. The specified registry entry is opened with read-only access unless the :access keyword is used to specify :write or :all. If the :create keyword value is non-nil, and the requested entry does not exist, then it will be created. If the :create keyword value is explicitly nil or is omitted, and the entry does not exist, then the result depends on the state of the :error-return keyword. If this keyword is present, then the value it supplies is returned in place of the missing registry entry. Otherwise an error is signalled.
If a registry-key is created, then a gc finalization is scheduled for it, so that its OLE resources can be freed when it is garbage-collected if they have not been released before that.
 owning-process object
Generic Function
This function returns the (Lisp) process that was executing when object was created. This allows the finalization method to free object in the same process, which is essential for some VB-allocated interfaces. There is a method defined for external-ole-interface objects, and these objects are the only ones for which it is meaningful.
 pInterface
Foreign Type
The OLE pInterface type. A pInterface value is the address of an interface instance.
 process-connection-event agent event connection sink cookie
Generic Function
The connection-point support functions arrange to call process-connection-event at several significant points in the history of a connection. The first argument in the call is always the connection-point's agent. Methods specialized to the agent's class provide for user-defined behavior. A null method is defined for a nil agent.
agent
The connection-point's agent. If this is nil, a method that does nothing is invoked.
event
one of
:attach
An AdviseConnection has been accepted and the cookie is about to be returned to the caller.
:predetach
An UnadviseConnection has been received for an active connection, but the connection has not yet been closed.
:detach
An UnadviseConnection has been received and the connection removed, but the sink has not yet been released.
cp
the connection-point object
sink
the Ixxxx-client object that is the sink for this connection
cookie
the value of the cookie to be returned to the caller.

process-connection-event agent event connection sink cookie
Method: primary ((eql nil) t t t t)
This null method handles the case where no agent has been defined for the connection-point.
 process-site-message site msg wp lp
Method: primary (site-mixin t t t)
This is the windows message handler for sites. It returns non-nil if it handled the message, nil otherwise. If it returns a value, that value should be returned to windows. (That is, it should. Currently it does nothing).
 query-interface object iid
Generic Function
This generic function asks object to provide its interface of type iid. Methods defined for client interfaces query the external interface and return a new client interface of the appropriate type or nil, depending on the external object's response. Methods defined for objects that inherit from lisp-ole-object find or build a server interface of the designated type if the object presents that interface and return nil otherwise.
query-interface obj guid
Method: primary (lisp-ole-object t)
This method checks to see if obj supports the specified interface. If it does, then the appropriate interface object is returned, from obj's cache if possible and by creating (and caching) a new one if necessary. If obj doesn't support the specified interface, then this method returns nil.
query-interface ifc iid
Method: primary (IUnknown-client t)
This function calls the foreign pInterface's QueryInterface method, asking for the guid specified by iid. The iid must have an associated client-interface class defined. If the QueryInterface response is positive, query-interface constructs and returns a client-interface object of the appropriate type referencing the new returned pInterface. If the QueryInterface response indicates a failure, query-interface returns two values, nil and the HRESULT value from the QueryInterface call.
query-interface tool iid
Method: primary (remote-autotool t)
This just passes the request on to the tool's IDispatch interface.
 ref-count object
Generic Function
This is an accessor function for the ref-count slot of those ole objects that maintain them.
 register-factory obj classid context flags
Generic Function
Calls CoRegisterClassObject to register obj so that OLE can make the service available to other processes. Returns true if successful, signals an error otherwise
obj
the class-factory object that is to be registered.
classid
the lisp-guid specifying the Classid by which OLE is to register this factory.
context
one or more of the following values or'ed together:
  • CLSCTX_INPROC_SERVER
  • CLSCTX_INPROC_HANDLER
  • CLSCTX_LOCAL_SERVER
  • CLSCTX_REMOTE_SERVER
flags
one of the following codes:
  • REGCLS_SINGLEUSE
  • REGCLS_MULTIPLEUSE
  • REGCLS_MULTI_SEPARATE

register-factory obj classid context flags
Method: primary (class-factory t t t)
Performs all the register-factory business for class-factory objects.
 register-server prog-name readable-name class-id &key inproc32 local32
Function
This function places entries in the registry to allow access to our server.
prog-name
a string of the form "Franz.autosample.1"
readable-name
a readable description of the program, e.g., "Franz Automation Sample"
class-id
the classid to be registered for the name. Can be a lisp-guid or a standard string representation.
inproc32
a string naming the InProcServer32 DLL module for this class. If omitted, no InProcServer32 registry key is created.
local32
non-nil means this class is supported by running lisp as a local server. The lisp executable and the lisp image need to be specified. The value for local32 can be one of the following:
  • a list of two strings giving the pathnames of the lisp executable and the lisp image, in that order.
  • a string giving the pathname of the lisp image; the current lisp executable will be named as the local server.
  • the symbol t; the current lisp executable and image will be specified as the executable and image for the server. This is useful for self-registration.

registry-key
Class
Instances of this class provide access to the windows registry.
 registry-subkey-names k &optional maxlng
Method: primary (registry-key)
Returns a sorted list of the names of subkeys associated with the registry-key k. The optional second argument is not currently effective, and should be omitted.
 registry-value key name &optional path
Generic Function
This function returns the value associated with a specified name in a specified registry entry. The registry entry is designated by giving a starting key, key and an optional path. The path argument can be a string or a list of strings. If omitted or nil it causes the key argument to be the registry entry to search. If the named value is found in that registry entry then the associated value is returned, otherwise nil is returned. If path is non-nil but does not lead to a valid registry entry, then nil is returned.
The empty string "" names the key's default value.
The form (registry-value ...) is setf-able.
 registry-value-names k &optional maxlng
Method: primary (registry-key)
Returns a sorted list of the names of values associated with the registry-key k. The optional second argument is not currently effective, and should be omitted.
 registry-value-present-p key name &optional path
Generic Function
This function searches for a specified name in a specified registry entry. The registry entry is designated by giving a starting key, key and an optional path. The path argument can be a string or a list of strings. If omitted or nil it causes the key argument to be the registry entry to search. If the named value is found in that registry entry then t is returned, otherwise nil is returned.
 release object
Generic Function
This method is called when a user wishes to relinquish access to an interface. An OLE object maintains a reference count and may free resources and generally invalidate future references when the count goes to zero.
release obj
Method: primary (IUnknown)
This method decrements (ref-count object). If the result is zero, ole-free is called on object. The post-decrement ref-count value is returned.
release ifc
Method: primary (IUnknown-client)
This method calls the foreign pInterface's Release method, returning the integer that comes back from that function. It also changes the argument's class to released-IUnknown, preventing its subsequent misuse in method calls.
release tool
Method: primary (remote-autotool)
This releases the IDispatch interface associated with tool.
release obj
Method: after (connection-point)
Releasing a reference to a connection point also releases a reference to its container. See add-ref.
release obj
Method: after (connection-point-enumerator)
Also does a release on the connection-point-container.
release obj
Method: after (connection-enumerator)
Does a release on the connection-point object, as well.
release obj
Method: after (advise-enumerator)
Also does a release on the adviser.
 release-process-client-interfaces
Function
This function goes through acl's pending finalization set to extract the release finalizations for all client interfaces created by this process and not yet triggered. These are removed from acl's finalization set, and are all released (in an undetermined order). The list of released interfaces is returned. (The *malloc-interface* is not released, even if it was created by this process, since it is shared by multiple processes.)
 remote-autotool
Class
This is a client class that provides lisp access to some object via IDispatch. It builds a name-to-id map dynamically as needed to improve call efficiency.
 require-client-interfaces &rest ifclist
Macro
This macro expands into the code to load the client library code for the named (unevaluated) interfaces. For example, a file that needed to call upon the ITypeLib and ITypeInfo interfaces might include the form (require-client-interfaces ITypeLib ITypeInfo).
 require-modules &rest module-names
Macro
This expands to code to require the specified ACLOLE modules. The module-names can include any of the following keywords:
:automation-server
To include support for automation servers
:factory-server
To include support for class factories
:connection-server
To include support for providing connections
:ocx-container
To include support for OLE Containers

require-server-interfaces &rest ifclist
Macro
This macro expands into the code to load the server library code for the named (unevaluated) interfaces. For example, a file that needed to call upon the ITypeLib and ITypeInfo interfaces might include the form (require-server-interfaces ITypeLib ITypeInfo).
 rkey-classes-root
Variable
This holds a registry-key used to access HKEY_CLASSES_ROOT.
 rkey-current-user
Variable
This holds a registry-key used to access HKEY_CURRENT_USER.
 rkey-local-machine
Variable
This holds a registry-key used to access HKEY_LOCAL_MACHINE.
 rkey-users
Variable
This holds a registry-key used to access HKEY_USERS.
 *running-blind*
Variable
Set nonnil to invoke errorset around all server method functions
 safearray
Foreign Type
The OLE SAFEARRAY type.
 safearray-aref v i &rest more-is
Function
This function retrieves and returns an element of the lisp-safearray or OLE safearray v. The specific element is specified by the index list built by consing i in front of more-is. In the common single-dimension case more-is is nil and i is the only index. This function wraps the access in a with-safearray-lock. The form (safearray-aref ...) is setf-able.
 safearray-dimension v i
Function
Returns the dimension specification for the i-th dimension of lisp-safearray or OLE safearray v. The specification is a list of the form (count lbound), where count is the array's width in this dimension and lbound is the lowest valid index in this dimension. The index i must be non-negative and less than v's rank, If i is not a valid dimension index then safearray-dimension returns nil.
 safearray-dimensions v
Function
Returns a list of the dimension specifications for lisp-safearray or OLE safearray v. Each specification is as would be returned by safearray-dimension.
 safearray-element-address v i more-is
Function
This function returns the address of an element of the lisp-safearray or OLE safearray v. The element is specified by the index list built by consing i in front of more-is. In the common single-dimension case more-is is nil and i is the only index. Safearray-element-address can only be called inside a with-safearray-lock block that locks the safearray v, and the result becomes invalid when that block is exited. If the index list is invalid then an error is signalled.
 safearray-pointer v
Function
The argument v can be a lisp-safearray object or the (integer) address of an OLE safearray object. In the former case the address of its associated OLE safearray is returned; in the latter case the return value is the argument value itself.
 safearray-rank v
Function
Returns the number of dimensions defined for the lisp-safarray or OLE safearray v.
 server-dll-name factory
Generic Function
ACLOLE calls this function during self-registration to get the appropriate dll name. Application code must provide an appropriate method for any factories they wish to register.
 *server-initialization-complete*
Variable
This variable should be set non-nil when the Lisp server application is ready to receive requests from OLE. Any thread making OLE requests to the server will be blocked until the value becomes non-nil. This variable cannot be used to block request processing after it has once begun, its sole use is to delay processing while the server performs initialization.
 set-event-return parmname value
Function
This function can be called within the dynamic scope of an event handler created by def-ole-linkage. The parmname argument names one of the out parameters of the method and the value argument must be a legal value to be transmitted back to the method's caller via that out parameter. The last value specified in this way for a particular out parameter will be sent back to the caller. The function returns its second argument.
 set-server-trace object mode
Generic Function
This function controls tracing behavior of individual server interfaces and of server objects. The object argument is the item in question. The mode argument can be :on, to turn tracing on, or :off, to turn tracing off. When an interface is being traced, each call to a method of that particular interface (not interface class) will generate output to *trace-out*. When a server object is being traced, all its interfaces are traced and all requests for a new interface are reported along with the results.
set-server-trace ifc mode
Method: primary (lisp-ole-interface t)
This method turns tracing for the specified interface on or off.
set-server-trace obj mode
Method: primary (lisp-ole-object t)
This method turns tracing for the object on or off. All its existing interfaces will be set to trace or not trace, as appropriate. All interfaces built are marked to trace or not according to the object's trace state at the time the interface is created.
 set-variant-value-extension key val pvariant
Generic Function
This generic function allows (setf variant-value) to be extended to deal with additional types. If a value to be stored in a variant is not of one of the known types, then set-variant-value-extension will be called. The val and pvariant arguments are the value and variant pointer, respectively. The key argument is val, if that is an atom, its car if it is a cons cell. Any method defined on set-variant-value-extension must store an appropriate value in the variant and return true, or return NIL to indicate failure.
 signal-server-exception object code &key source description helpfile helpcontext use-scode
Method: primary (automaton t)
This function can be called within an auto-method handler to signal an exception. It causes the Invoke method to return a DISP_E_EXCEPTION result after filling in the excepinfo block. The fields of the excepinfo structure are filled as follows:
site-mixin
Class
This class is a superclass of all OLE site objects. Site objects correspond to places in application forms where embeddable objects or controls are attached. See the Allegro ActiveX documentation for details.
start-ole &key verbose (language LANG_SYSTEM_DEFAULT) (locale LOCALE_SYSTEM_DEFAULT)
Function
This functions sets up the initial linkage with OLE, loading the necessary dll's. If :verbose is specified and non-nil then progress messages will be printed on *standard-output* during the initialization process. This function initializes the globals *ole-language* and *ole-locale* from the specified or defaulted keyword arguments :language and :locale. Any global initializations defined by defoleglobal macros are performed after OLE is successfully initialized and the *malloc-interface* global has been set.
 stop-ole &optional verbose
Function
This function tells OLE that it is no longer needed. It also runs any de-initialization functions specified by defoleglobal macros. If the optional verbose argument is non-nil, then progress messages will be written to *standard-output* during the shutdown process. The return value will be t if OLE had to be stopped. A second call to this function will find that OLE has already been disconnected and will return nil.
 storage-for-site obj site
Generic Function
This function is to create a storage interface that an object can use to save its state. Methods must be defined to handle whatever application document classes inherit from document-mixin and site-mixin.
storage-for-site this site
Method: primary (object-with-storage t)
This is the default method; it opens a new storage element in the object's storage, signalling an error if the site's storage already exists. The name of the site's storage element is site=[xxx], where xxx is the site's name.
 string-bstr string
Function
String-bstr allocates (using SysAllocString) and returns a foreign bstr object holding a copy of the string argument. If the argument is the empty string "", then string-bstr returns the NULL pointer 0.
 string-guid guid
Function
This function accepts a string encoding a guid in the standard human-readable format, "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}" and returns the lisp-guid object representing that guid.
 string-unicode string &optional cpointer
Function
This function converts its string argument to unicode and returns the result. If the cpointer argument is supplied, then it must be the address of a foreign area big enough to hold the result, the output string will be built there. If the cpointer argument is omitted then string-unicode allocates a foreign area for the result. In either case, the string data is converted to its unicode equivalent in the output area and the area's address is returned.
 success hr
Macro
Expands to code that evaluates the form hr and tests the (integer) result, returning true if and only if it is an OLE success code.
 unadvise-connection connpt cookie
Generic Function
Advises the connection point connpt that the connection it identified by the cookie value can be closed.
unadvise-connection ifc cookie
Method: primary (IConnectionPoint-client t)
Calls IConnectionPoint.Unadvise to disconnect the sink associated with the cookie argument, which must be the value returned from an earlier advise-connection call on the same connection point.
unadvise-connection cp cookie
Method: primary (connection-point t)
If cookie identifies an active connection for cp then the connection is detached, the associated interface is released, and the appropriate calls to process-connection-event are made. The function returns true if the cookie was valid, nil otherwise.
 unicode
Foreign Type
The foreign type representing unicode data.
 unicode-string cpointer &optional (csize most-positive-fixnum)
Function
The unicode data is extracted from the foreign area addressed by the cpointer argument and converted to a newly-allocated Lisp string, which is returned. If the csize argument is provided it specifies a maximum length to be converted. The actual amount converted will be set by the smaller of the csize parameter and the position of the first zero character in the unicode data.
 unique-guid guid
Function
This function accepts a lisp-guid or a string or binary representation of a guid. In the first case it returns the argument itself; in the other cases it finds or creates the associated lisp-guid and returns that.
 unregister-application appname
Function
This function looks up an application in the registry and deletes entries associated with it.
 unregister-factory factory
Generic Function
Informs OLE that factory is no longer available to serve client requests.
unregister-factory obj
Method: primary (class-factory)
Revokes the registration so that OLE will make no further connections to obj.
 variant
Foreign Type
The OLE VARIANT structure in foreign space.
 variant-aref v i
Function
This function returns a lisp value representing the value in the OLE variant object at the i-th position in a (foreign) vector of OLE variant objects starting at address v. The form (variant-aref ...) is setf-able.
 VariantChangeType destination source flags new
Function
This invokes the foreign function of the same name.
 VariantClear variant
Function
This invokes the foreign function of the same name.
 VariantCopy destination source
Function
This invokes the foreign function of the same name.
 VariantInit variant
Function
This invokes the foreign function of the same name.
 variant-value v &optional interface-type
Function
This function returns a lisp value obtained from the OLE variant object at (foreign) address v. The form (variant-value ..) is setf-able. If the optional interface-type argument is supplied it must name a *-client interface type. In that case interface values will be returned as the specified type, rather than IUnknown-client or IDispatch-client. If the special variable variant-value-translation-function is not NIL, then the value extracted from the variant is translated before being returned.
 variant-values v count
Function
This function returns a vector of count elements obtained by converting successive variant values starting at address v.
 variant-value-translation-function
Variable
This symbol may be bound to a function of one variable that is to translate all values extracted from variants. It may be left NIL to skip translation. If a translation function is specified, then whenever variant-value extracts a value from a variant, that value will be passed to the translation function and the result will then be returned as the variant's effective value. Since IDispatch.Invoke arguments are received as variants, this means all such arguments will be translated before being passed to the invoked methods.
 with-foreign-data obdefs &rest body
Macro
This macro expands into code that temporarily and efficiently allocates areas to hold foreign data of specified types while evaluating the body forms. The obdefs entry is a list of elements of the form (symbol foreign-type-spec [count]). The symbols are let-bound to instances of the associated foreign types and the body is evaluated within that set of bindings. The optional count form can specify a constant or a form to be evaluated in the context of the with-foreign-data. If present, it specifies the allocation of an area large enough to hold that many copies of the specified foreign type. The foreign data is logically deallocated after the body forms have been evaluated. It is not defined whether the data areas are allocated from a pool or on the stack, but in any case they may not be referenced outside the body of the with-foreign-data form. The value of the whole form is whatever is computed by the implicit progn of its body forms.
 with-open-registry-key (var root path &rest args) &body body
Macro
This macro expands into code that opens a registry key, evaluates the body, then closes the registry key, returning what the body computed. The close is done as an unwind-protect cleanup. The open registry key is obtained by applying open-registry-key to root path and args, and is then let-bound to the var variable while body is evaluated.
 with-safearray-lock aform &rest body
Macro
Expands to code that evalutes body as an implicit progn inside an environment that has done an OLE lock on the safearray pointer obtained by evaluating aform. This allows the safearray's data to be accessed within the body. The aform can evaluate to a lisp-safearray or an OLE safearray reference.
 with-unicode-argument (v val) &rest body
Macro
This form expands to code that evaluates the val form, which must produce a string, then allocates a foreign area to hold a Unicode version of that string. The unicode form of the string data is copied into the foreign area, the variable v is let-bound to the area, and the body forms are evaluated as an implicit progn in this environment. The unicode data is freed before the with-unicode-argument form returns. This macro is typically wrapped around calls to OLE functions that require unicode arguments.
 xeno-address type ptr &rest access
Macro
Expands to code that returns the address of the specified element of the foreign structure addressed by the ptr argument, assuming it to be of the specified foreign type. All subforms are evaluated.
 xeno-slot type ptr &rest access
Macro
Expands to code that returns the specified element of the foreign structure addressed by the ptr argument, assuming it to be of the specified foreign type. All subforms are evaluated.