The com-on Reference Manual

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.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 com-on

Utilities for dealing with COM interfaces.

Maintainer

Yukari Hafner <>

Author

Yukari Hafner <>

Home Page

https://shinmera.github.io/com-on/

Source Control

(GIT https://github.com/shinmera/com-on.git)

Bug Tracker

https://github.com/shinmera/com-on/issues

License

zlib

Version

1.0.0

Dependencies
  • cffi (system).
  • documentation-utils (system).
Source

com-on.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 com-on/com-on.asd

Source

com-on.asd.

Parent Component

com-on (system).

ASDF Systems

com-on.


3.1.2 com-on/package.lisp

Source

com-on.asd.

Parent Component

com-on (system).

Packages

3.1.3 com-on/bindings.lisp

Dependency

package.lisp (file).

Source

com-on.asd.

Parent Component

com-on (system).

Public Interface

3.1.4 com-on/error.lisp

Dependency

bindings.lisp (file).

Source

com-on.asd.

Parent Component

com-on (system).

Public Interface

3.1.5 com-on/guid.lisp

Dependency

error.lisp (file).

Source

com-on.asd.

Parent Component

com-on (system).

Public Interface
Internals

3.1.6 com-on/com.lisp

Dependency

guid.lisp (file).

Source

com-on.asd.

Parent Component

com-on (system).

Public Interface
Internals

*initialized* (special variable).


3.1.7 com-on/documentation.lisp

Dependency

com.lisp (file).

Source

com-on.asd.

Parent Component

com-on (system).


4 Packages

Packages are listed by definition order.


4.1 org.shirakumo.com-on.cffi

Source

package.lisp.

Use List

common-lisp.

Public Interface

4.2 org.shirakumo.com-on

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

*initialized* (special variable).


5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Constants

Constant: clsctx-all
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Constant: cp-utf8
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Constant: format-message-from-system
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Constant: format-message-ignore-inserts
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.


5.1.2 Macros

Macro: check-hresult (value-form &rest expected)

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)

Package

org.shirakumo.com-on.

Source

error.lisp.

Macro: check-last-error (predicate &body cleanup)

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)

Package

org.shirakumo.com-on.

Source

error.lisp.

Macro: define-comfun ((struct method &key options conc-name) return-type &body args)

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

Package

org.shirakumo.com-on.

Source

com.lisp.

Macro: define-comstruct (name &body methods)

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

Package

org.shirakumo.com-on.

Source

com.lisp.

Macro: define-guid (name &rest id)

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)

Package

org.shirakumo.com-on.

Source

guid.lisp.

Macro: define-hresult (&body pairs)

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

Package

org.shirakumo.com-on.

Source

error.lisp.

Macro: with-com ((var init) &body body)

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

Package

org.shirakumo.com-on.

Source

com.lisp.

Macro: with-deref ((var type) &body init)

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

Package

org.shirakumo.com-on.

Source

error.lisp.

Macro: with-wstring ((var string) &body body)
Package

org.shirakumo.com-on.

Source

error.lisp.


5.1.3 Ordinary functions

Function: add-hresult (&rest pairs)

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

Package

org.shirakumo.com-on.

Source

error.lisp.

Function: create (class instance)

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

Package

org.shirakumo.com-on.

Source

com.lisp.

Function: create-instance (rclsid punkouter dwclscontext riid ppv)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: error-message (&optional errno)

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

Package

org.shirakumo.com-on.

Source

error.lisp.

Function: format-message (flags source message-id language-id buffer size arguments)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: get-last-error ()
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: guid (&rest id)

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)

Package

org.shirakumo.com-on.

Source

guid.lisp.

Function: guid-data1 (pointer-to-guid)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: (setf guid-data1) (pointer-to-guid)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: guid-data2 (pointer-to-guid)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: (setf guid-data2) (pointer-to-guid)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: guid-data3 (pointer-to-guid)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: (setf guid-data3) (pointer-to-guid)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: guid-data4 (pointer-to-guid)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: (setf guid-data4) (pointer-to-guid)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: guid-string (guid-ish)

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

Package

org.shirakumo.com-on.

Source

guid.lisp.

Function: guid= (a b)

Compares two GUIDs for equality.

Returns T if the two GUIDs are the same, NIL otherwise.

See GUID

Package

org.shirakumo.com-on.

Source

guid.lisp.

Function: init ()

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

Package

org.shirakumo.com-on.

Source

com.lisp.

Function: initialize (nullable init)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: multi-byte-to-wide-char (code-page flags multi-byte-str multi-byte wide-char-str wide-char)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: release (pointer)

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

Package

org.shirakumo.com-on.

Source

com.lisp.

Function: shutdown ()

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

Package

org.shirakumo.com-on.

Source

com.lisp.

Function: string->wstring (string)

Converts a Lisp string to a Windows ’wchar’ string and returns the pointer to this freshly allocated string.

See WSTRING->STRING

Package

org.shirakumo.com-on.

Source

error.lisp.

Function: task-mem-free (data)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: uninitialize ()
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: vtbl (pointer-to-com)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: (setf vtbl) (pointer-to-com)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: wide-char-to-multi-byte (code-page flags wide-char-str wide-char multi-byte-str multi-byte default-char used-default-char)
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Function: win32-error (code &key function-name message type)

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

Package

org.shirakumo.com-on.

Source

error.lisp.

Function: wstring->string (pointer &optional chars)

Converts a Windows ’wchar’ string to a Lisp string and returns it.

See STRING->WSTRING

Package

org.shirakumo.com-on.

Source

error.lisp.


5.1.4 Generic functions

Generic Reader: bytes (object)

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

Package

org.shirakumo.com-on.

Methods
Reader Method: bytes ((guid guid))

automatically generated reader method

Source

guid.lisp.

Target Slot

bytes.

Generic Reader: code (condition)

Returns the windows error code associated with the problem.

See WIN32-ERROR

Package

org.shirakumo.com-on.

Methods
Reader Method: code ((condition win32-error))
Source

error.lisp.

Target Slot

code.

Generic Reader: function-name (condition)

Returns the function name that caused the error, if known.

See WIN32-ERROR

Package

org.shirakumo.com-on.

Methods
Reader Method: function-name ((condition win32-error))
Source

error.lisp.

Target Slot

function-name.

Generic Reader: message (condition)

Returns a descriptive message about the error.

See WIN32-ERROR

Package

org.shirakumo.com-on.

Methods
Reader Method: message ((condition win32-error))
Source

error.lisp.

Target Slot

message.


5.1.5 Standalone methods

Method: expand-from-foreign (ptr (type guid))
Package

cffi.

Source

guid.lisp.

Method: expand-into-foreign-memory (val (type guid) ptr)
Package

cffi.

Source

guid.lisp.

Method: expand-to-foreign-dyn (val var body (type guid))
Package

cffi.

Source

guid.lisp.

Method: foreign-type-alignment ((type guid))
Package

cffi.

Source

guid.lisp.

Method: foreign-type-size ((type guid))
Package

cffi.

Source

guid.lisp.

Method: free-translated-object (ptr (type guid) param)
Package

cffi.

Source

guid.lisp.

Method: initialize-instance :after ((guid guid) &key id)
Source

guid.lisp.

Method: make-load-form ((guid guid) &optional env)
Source

guid.lisp.

Method: print-object ((guid guid) stream)
Source

guid.lisp.

Method: translate-from-foreign (ptr (type guid))
Package

cffi.

Source

guid.lisp.

Method: translate-into-foreign-memory (guid-ish (type guid) ptr)
Package

cffi.

Source

guid.lisp.

Method: translate-into-foreign-memory ((guid guid) (type guid) ptr)
Package

cffi.

Source

guid.lisp.

Method: translate-into-foreign-memory ((guid guid) (type (eql org.shirakumo.com-on:guid)) ptr)
Package

cffi.

Source

guid.lisp.

Method: translate-to-foreign (guid-ish (type guid))
Package

cffi.

Source

guid.lisp.

Method: translate-to-foreign ((guid guid) (type guid))
Package

cffi.

Source

guid.lisp.


5.1.6 Conditions

Condition: win32-error

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

Package

org.shirakumo.com-on.

Source

error.lisp.

Direct superclasses

error.

Direct methods
Direct slots
Slot: function-name
Initform

(quote nil)

Initargs

:function-name

Readers

function-name.

Writers

This slot is read-only.

Slot: code
Initargs

:code

Readers

code.

Writers

This slot is read-only.

Slot: message
Initform

(quote nil)

Initargs

:message

Readers

message.

Writers

This slot is read-only.


5.1.7 Classes

Class: com
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Direct superclasses
  • foreign-struct-type.
  • translatable-foreign-type.
Class: guid
Package

org.shirakumo.com-on.cffi.

Source

bindings.lisp.

Direct superclasses
  • foreign-struct-type.
  • translatable-foreign-type.
Class: guid

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

Package

org.shirakumo.com-on.

Source

guid.lisp.

Direct superclasses

enhanced-foreign-type.

Direct methods
Direct Default Initargs
InitargValue
:actual-type(quote (pointer))
Direct slots
Slot: bytes
Initform

(make-array 16 :element-type (quote (unsigned-byte 8)))

Initargs

:bytes

Readers

bytes.

Writers

This slot is read-only.


5.2 Internals


5.2.1 Special variables

Special Variable: *initialized*
Package

org.shirakumo.com-on.

Source

com.lisp.


5.2.2 Standalone methods

Method: aggregatep ((type guid))
Package

cffi.

Source

guid.lisp.

Method: translate-aggregate-to-foreign (ptr guid-ish (type guid))
Package

cffi.

Source

guid.lisp.

Method: translate-aggregate-to-foreign (ptr (guid guid) (type guid))
Package

cffi.

Source

guid.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
A   B   C   D   E   F   G   I   M   P   R   S   T   U   V   W  
Index Entry  Section

(
(setf guid-data1): Public ordinary functions
(setf guid-data2): Public ordinary functions
(setf guid-data3): Public ordinary functions
(setf guid-data4): Public ordinary functions
(setf vtbl): Public ordinary functions

A
add-hresult: Public ordinary functions
aggregatep: Private standalone methods

B
bytes: Public generic functions
bytes: Public generic functions

C
check-hresult: Public macros
check-last-error: Public macros
code: Public generic functions
code: Public generic functions
create: Public ordinary functions
create-instance: Public ordinary functions

D
define-comfun: Public macros
define-comstruct: Public macros
define-guid: Public macros
define-hresult: Public macros

E
error-message: Public ordinary functions
expand-from-foreign: Public standalone methods
expand-into-foreign-memory: Public standalone methods
expand-to-foreign-dyn: Public standalone methods

F
foreign-type-alignment: Public standalone methods
foreign-type-size: Public standalone methods
format-message: Public ordinary functions
free-translated-object: Public standalone methods
Function, (setf guid-data1): Public ordinary functions
Function, (setf guid-data2): Public ordinary functions
Function, (setf guid-data3): Public ordinary functions
Function, (setf guid-data4): Public ordinary functions
Function, (setf vtbl): Public ordinary functions
Function, add-hresult: Public ordinary functions
Function, create: Public ordinary functions
Function, create-instance: Public ordinary functions
Function, error-message: Public ordinary functions
Function, format-message: Public ordinary functions
Function, get-last-error: Public ordinary functions
Function, guid: Public ordinary functions
Function, guid-data1: Public ordinary functions
Function, guid-data2: Public ordinary functions
Function, guid-data3: Public ordinary functions
Function, guid-data4: Public ordinary functions
Function, guid-string: Public ordinary functions
Function, guid=: Public ordinary functions
Function, init: Public ordinary functions
Function, initialize: Public ordinary functions
Function, multi-byte-to-wide-char: Public ordinary functions
Function, release: Public ordinary functions
Function, shutdown: Public ordinary functions
Function, string->wstring: Public ordinary functions
Function, task-mem-free: Public ordinary functions
Function, uninitialize: Public ordinary functions
Function, vtbl: Public ordinary functions
Function, wide-char-to-multi-byte: Public ordinary functions
Function, win32-error: Public ordinary functions
Function, wstring->string: Public ordinary functions
function-name: Public generic functions
function-name: Public generic functions

G
Generic Function, bytes: Public generic functions
Generic Function, code: Public generic functions
Generic Function, function-name: Public generic functions
Generic Function, message: Public generic functions
get-last-error: Public ordinary functions
guid: Public ordinary functions
guid-data1: Public ordinary functions
guid-data2: Public ordinary functions
guid-data3: Public ordinary functions
guid-data4: Public ordinary functions
guid-string: Public ordinary functions
guid=: Public ordinary functions

I
init: Public ordinary functions
initialize: Public ordinary functions
initialize-instance: Public standalone methods

M
Macro, check-hresult: Public macros
Macro, check-last-error: Public macros
Macro, define-comfun: Public macros
Macro, define-comstruct: Public macros
Macro, define-guid: Public macros
Macro, define-hresult: Public macros
Macro, with-com: Public macros
Macro, with-deref: Public macros
Macro, with-wstring: Public macros
make-load-form: Public standalone methods
message: Public generic functions
message: Public generic functions
Method, aggregatep: Private standalone methods
Method, bytes: Public generic functions
Method, code: Public generic functions
Method, expand-from-foreign: Public standalone methods
Method, expand-into-foreign-memory: Public standalone methods
Method, expand-to-foreign-dyn: Public standalone methods
Method, foreign-type-alignment: Public standalone methods
Method, foreign-type-size: Public standalone methods
Method, free-translated-object: Public standalone methods
Method, function-name: Public generic functions
Method, initialize-instance: Public standalone methods
Method, make-load-form: Public standalone methods
Method, message: Public generic functions
Method, print-object: Public standalone methods
Method, translate-aggregate-to-foreign: Private standalone methods
Method, translate-aggregate-to-foreign: Private standalone methods
Method, translate-from-foreign: Public standalone methods
Method, translate-into-foreign-memory: Public standalone methods
Method, translate-into-foreign-memory: Public standalone methods
Method, translate-into-foreign-memory: Public standalone methods
Method, translate-to-foreign: Public standalone methods
Method, translate-to-foreign: Public standalone methods
multi-byte-to-wide-char: Public ordinary functions

P
print-object: Public standalone methods

R
release: Public ordinary functions

S
shutdown: Public ordinary functions
string->wstring: Public ordinary functions

T
task-mem-free: Public ordinary functions
translate-aggregate-to-foreign: Private standalone methods
translate-aggregate-to-foreign: Private standalone methods
translate-from-foreign: Public standalone methods
translate-into-foreign-memory: Public standalone methods
translate-into-foreign-memory: Public standalone methods
translate-into-foreign-memory: Public standalone methods
translate-to-foreign: Public standalone methods
translate-to-foreign: Public standalone methods

U
uninitialize: Public ordinary functions

V
vtbl: Public ordinary functions

W
wide-char-to-multi-byte: Public ordinary functions
win32-error: Public ordinary functions
with-com: Public macros
with-deref: Public macros
with-wstring: Public macros
wstring->string: Public ordinary functions