This is the com-on Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 04:50:22 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
com-onUtilities for dealing with COM interfaces.
Yukari Hafner <shinmera@tymoon.eu>
Yukari Hafner <shinmera@tymoon.eu>
(GIT https://github.com/shinmera/com-on.git)
zlib
1.0.0
cffi (system).
documentation-utils (system).
package.lisp (file).
bindings.lisp (file).
error.lisp (file).
guid.lisp (file).
com.lisp (file).
documentation.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
com-on/com-on.asdcom-on/package.lispcom-on/bindings.lispcom-on/error.lispcom-on/guid.lispcom-on/com.lispcom-on/documentation.lispcom-on/bindings.lisppackage.lisp (file).
com-on (system).
clsctx-all (constant).
com (class).
cp-utf8 (constant).
create-instance (function).
format-message (function).
format-message-from-system (constant).
format-message-ignore-inserts (constant).
get-last-error (function).
guid (class).
guid-data1 (function).
(setf guid-data1) (function).
guid-data2 (function).
(setf guid-data2) (function).
guid-data3 (function).
(setf guid-data3) (function).
guid-data4 (function).
(setf guid-data4) (function).
initialize (function).
multi-byte-to-wide-char (function).
task-mem-free (function).
uninitialize (function).
vtbl (function).
(setf vtbl) (function).
wide-char-to-multi-byte (function).
com-on/error.lispbindings.lisp (file).
com-on (system).
add-hresult (function).
check-hresult (macro).
check-last-error (macro).
code (reader method).
define-hresult (macro).
error-message (function).
function-name (reader method).
message (reader method).
string->wstring (function).
win32-error (function).
win32-error (condition).
with-deref (macro).
with-wstring (macro).
wstring->string (function).
com-on/guid.lisperror.lisp (file).
com-on (system).
bytes (reader method).
define-guid (macro).
expand-from-foreign (method).
expand-into-foreign-memory (method).
expand-to-foreign-dyn (method).
foreign-type-alignment (method).
foreign-type-size (method).
free-translated-object (method).
guid (function).
guid (class).
guid-string (function).
guid= (function).
initialize-instance (method).
make-load-form (method).
print-object (method).
translate-from-foreign (method).
translate-into-foreign-memory (method).
translate-into-foreign-memory (method).
translate-into-foreign-memory (method).
translate-to-foreign (method).
translate-to-foreign (method).
aggregatep (method).
translate-aggregate-to-foreign (method).
translate-aggregate-to-foreign (method).
com-on/com.lispguid.lisp (file).
com-on (system).
create (function).
define-comfun (macro).
define-comstruct (macro).
init (function).
release (function).
shutdown (function).
with-com (macro).
*initialized* (special variable).
Packages are listed by definition order.
org.shirakumo.com-on.cfficommon-lisp.
clsctx-all (constant).
com (class).
cp-utf8 (constant).
create-instance (function).
format-message (function).
format-message-from-system (constant).
format-message-ignore-inserts (constant).
get-last-error (function).
guid (class).
guid-data1 (function).
(setf guid-data1) (function).
guid-data2 (function).
(setf guid-data2) (function).
guid-data3 (function).
(setf guid-data3) (function).
guid-data4 (function).
(setf guid-data4) (function).
initialize (function).
multi-byte-to-wide-char (function).
task-mem-free (function).
uninitialize (function).
vtbl (function).
(setf vtbl) (function).
wide-char-to-multi-byte (function).
org.shirakumo.com-oncommon-lisp.
add-hresult (function).
bytes (generic reader).
check-hresult (macro).
check-last-error (macro).
code (generic reader).
create (function).
define-comfun (macro).
define-comstruct (macro).
define-guid (macro).
define-hresult (macro).
error-message (function).
function-name (generic reader).
guid (function).
guid (class).
guid-string (function).
guid= (function).
init (function).
message (generic reader).
release (function).
shutdown (function).
string->wstring (function).
win32-error (function).
win32-error (condition).
with-com (macro).
with-deref (macro).
with-wstring (macro).
wstring->string (function).
*initialized* (special variable).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Convenience function to check the returned HRESULT and error on failure.
If the return value of VALUE-FORM is not one of the supplied EXPECTED
values, an error of type WIN32-ERROR is returned. If it is one of the
EXPECTED values, the value is returned.
If EXPECTED is not passed, it is assumed to be just (:OK).
See COM:HRESULT
See WIN32-ERROR (type)
Convenience function to check the last error on failure.
If PREDICATE returns NIL, CLEANUP forms are run. After this, the error
code is retrieved through COM:GET-LAST-ERROR, and a WIN32-ERROR is
signalled using this code.
See WIN32-ERROR (type)
Define a method on a COM interface.
ARGS should be a list of argument declarations, with each argument
being composed of an argument name and a CFFI type.
This will create a function with the name of STRUCT-METHOD with the
declared arguments, which will attempt to call the related COM method
on the supplied COM instance. This method must be accessible through a
function called %STRUCT-METHOD to which a pointer to a VTBL can be
passed.
You will typically not use this macro by itself, and instead use
DEFINE-COMSTRUCT to perform the definition of a COM interface.
See COM:VTBL
See DEFINE-COMSTRUCT
Define a COM interface structure.
NAME should be of the following structure:
NAME ::= name | (name &key bare conc-name)
name — The name of the CFFI structure type.
bare — If set, the structure will not be an IUnknown, and
will thus not include the standard methods
QueryInterface, AddRef, and Release.
conc-name — The prefix for the structure interface functions.
If not set, the name is used as a prefix.
METHODS should be a body of the following kinds of entries:
METHODS ::= (method [return-value] ARGUMENT*)*
ARGUMENT ::= (name type)
method — Name of the interface method. You may pick this to
be whatever you like, there is no strict binding to
any C function.
return-value — The return value of the method. If not passed
explicitly, HRESULT is assumed.
name — The name of the argumetn. Again, the name may be
arbitrarily chosen.
type — The CFFI type that the argument should be of.
Note that the order of the methods /must/ be the same as in the actual
C header you’re mimicking. You also /must/ include all of the methods
defined in the C header and cannot skip any. The order is what
actually defines which method is used. The name is purely on the Lisp
side.
Each COM interface always has the following three methods at the
beginning, which DEFINE-COMSTRUCT adds for you automatically:
(QUERY-INTERFACE HRESULT (UID :POINTER) (OUT :POINTER))
(ADD-REF :ULONG)
(RELEASE :ULONG)
Also note that the THIS argument is always assumed for every method
and should therefore be omitted from the declarations.
For each method defined in the body, A DEFINE-COMFUN is generated,
which in turn will generate a function of the name NAME-METHOD using
the declared arguments and return type.
Alongside the methods, a C structure is defined which constitutes the
VTBL layout of the COM interface. Note that it does /not/ define the
COM instance layout itself. Each COM instance is assumed to merely be
a pointer to a structure with a pointer to a VTBL. None of this should
concern you terribly much, however. All you need to know is that you
can just pass a COM instance pointer to the method functions defined
by DEFINE-COMSTRUCT.
See DEFINE-COMFUN
Define a GUID instance.
This is a shorthand for DEFCONSTANT of a GUID instance created from
the given ID argument.
See GUID (type)
See GUID (function)
Define HRESULT values.
This allows you to dynamically add new HRESULT enum keys as if by
CFFI:DEFCENUM.
(define-hresult
(:foo #xDEAD)
(:bar #xBEEF))
See ADD-HRESULT
See COM:HRESULT
Hold a COM instance for the duration of the body.
This will ensure RELEASE is called on the instance when the body is
exited by any means.
INIT may be any form that returns a pointer to a COM instance.
See CREATE
See RELEASE
Shorthand to initialise a value by dereferencing.
Binds VAR to a pointer to a memory region of size fitting for TYPE, then evaluates INIT. INIT should return a COM:HRESULT. If this result is not :OK, an error is signalled. Otherwise, the memory region bound to VAR is dereferenced as a value of TYPE, which is then returned.
Seee CHECK-HRESULT
Add HRESULT values.
This allows you to dynamically add new HRESULT keys to the enum.
The pairs should be specified like a plist:
(add-hresult :foo #xDEAD :bar #xBEEF)
Existing keys or values will be silently overwritten.
See DEFINE-HRESULT
See COM:HRESULT
Create an instance of a COM class.
CLASS should be the GUID of the COM class. Typically named something
like CLSID_...
INSTANCE should be the GUID of the COM instance to access. Typically
named something like IID_...
Returns the pointer to the COM instance if successful, or signals an
error otherwise. You must release this instance when you are done with
it by calling RELEASE.
Automatically calls INIT.
See GUID
See WIN32-ERROR
See RELEASE
See INIT
See WITH-COM
Returns the error messag string for the given error code.
Unless specifically supplied, the last caused error code is used.
See COM:GET-LAST-ERROR
Create a new GUID instance.
ID may either be multiple values, or a single value determining the
GUID’s actual ID values. The following ID types are allowed:
STRING — Parses the string representation of the
UUID into its appropriate octets. Such a
UUID is typically of the form
XXXX-XX-XX-XX-XXXXXX
LIST (16) — Uses the 16 octets in the list to build
the internal octet vector.
LIST (11) — Uses the 11 integers in the list to build
the octet vector. Specifically, the list
should contain integers of the following
bit sizes:
32 16 16 8 8 8 8 8 8 8 8
This representation is sometimes found in
C headers.
CFFI:FOREIGN-POINTER — Copies the contents from the supplied C
pointer to a GUID into the internal byte
vector.
VECTOR (16) — Uses the 16 octets in the vector to build
the internal octet vector.
NULL — Fills the internal octet vector with 0s.
Supplying any integer anywhere in these values outside of the
specified ranges is an error.
See GUID (type)
Returns a standard string representation of the GUID.
The bytes of the GUID are represented in hex format as follows:
3 2 1 0 - 5 4 - 7 6 - 8 9 - 10 11 12 13 14 15
The reordering is due to the little-endian internal representation of
the octets. The passed GUID may either be a GUID instance, or a valid
GUID identifier from which a GUID can be constructed.
See GUID
Compares two GUIDs for equality.
Returns T if the two GUIDs are the same, NIL otherwise.
See GUID
Initialises the COM system if it has not yet been initialised.
This will load OLE32 and initialise COM for a multi-threaded
application.
This function must be called before any COM operations are performed.
Calling this function multiple times is safe.
See SHUTDOWN
Release a COM instance.
After releasing a COM instance, you /must not/ access it again, as it
may have been deallocated or invalidated.
You may get a COM instance through CREATE or some other API function
that returns an instance.
See CREATE
See WITH-COM
Uninitialises the COM system if it has been initialised.
After this you may not perform any further COM operations.
Calling this function multiple times is safe.
See INIT
Converts a Lisp string to a Windows ’wchar’ string and returns the pointer to this freshly allocated string.
See WSTRING->STRING
Signals an error of type WIN32-ERROR
Requires the Windows error code.
If no explicit MESSAGE is passed, the message is determined by
ERROR-MESSAGE.
See WIN32-ERROR (type)
See ERROR-MESSAGE
Converts a Windows ’wchar’ string to a Lisp string and returns it.
See STRING->WSTRING
Returns a 16-octet vector describing the GUID.
Note that the vector elements are in the order expected in the
memory representation of the GUID, which may not be entirely
intuitive.
See GUID
Returns the windows error code associated with the problem.
See WIN32-ERROR
win32-error)) ¶code.
Returns the function name that caused the error, if known.
See WIN32-ERROR
win32-error)) ¶Returns a descriptive message about the error.
See WIN32-ERROR
win32-error)) ¶guid) (type (eql org.shirakumo.com-on:guid)) ptr) ¶cffi.
Condition type for errors coming from the Windows API.
This condition type is signalled whenever a Windows API call returns
unsuccessfully.
See WIN32-ERROR (function)
See FUNCTION-NAME
See CODE
See MESSAGE
See CHECK-LAST-ERROR
See CHECK-HRESULT
error.
(quote nil)
:function-name
This slot is read-only.
foreign-struct-type.
translatable-foreign-type.
foreign-struct-type.
translatable-foreign-type.
Encapsulation for a Windows GUID.
GUIDs are 16 byte identifiers that are used for COM classes and COM
instances.
The :ID initarg determines the GUID’s contents. See MAKE-GUID.
A GUID instance may be passed as an argument to a C function where the
argument expects a COM:GUID structure pointer.
A GUID instance is usable as a literal and may be dumped to a FASL.
See COM:GUID
See BYTES
See GUID-STRING
See GUID (function)
See DEFINE-GUID
enhanced-foreign-type.
aggregatep.
bytes.
expand-from-foreign.
expand-into-foreign-memory.
expand-to-foreign-dyn.
foreign-type-alignment.
foreign-type-size.
free-translated-object.
initialize-instance.
make-load-form.
print-object.
translate-aggregate-to-foreign.
translate-aggregate-to-foreign.
translate-from-foreign.
translate-into-foreign-memory.
translate-into-foreign-memory.
translate-into-foreign-memory.
translate-to-foreign.
translate-to-foreign.
| Initarg | Value |
|---|---|
:actual-type | (quote (pointer)) |
| Jump to: | (
A B C D E F G I M P R S T U V W |
|---|
| Jump to: | (
A B C D E F G I M P R S T U V W |
|---|
| Jump to: | *
B C F M S |
|---|
| Jump to: | *
B C F M S |
|---|
| Jump to: | B C D E F G O P S W |
|---|
| Jump to: | B C D E F G O P S W |
|---|