Common Lisp Package: CFFI-OBJECTS

README:

CFFI-objects is a library, that enhances CFFI with several new constructions to use when you need to work with complex structures or objects.

It supports structures by-value and by-reference with and without saving C-pointer on lisp side. Also there is type pobject, that allows to send lisp object with pointer slot or C-pointer. No verbose documentation yet, sorry.

License is BSD

FUNCTION

Public

CLOSE-FOREIGN-LIBRARY (LIBRARY)

Closes a foreign library.

FIND-OBJECT (POINTER &OPTIONAL CLASS)

Returns lisp object for an Object pointer. If not found or found with wrong class, create new one with given CLASS

FOREIGN-ALLOC (TYPE &KEY (INITIAL-ELEMENT NIL INITIAL-ELEMENT-P) (INITIAL-CONTENTS NIL INITIAL-CONTENTS-P) (COUNT 1 COUNT-P) NULL-TERMINATED-P)

Allocate enough memory to hold COUNT objects of type TYPE. If INITIAL-ELEMENT is supplied, each element of the newly allocated memory is initialized with its value. If INITIAL-CONTENTS is supplied, each of its elements will be used to initialize the contents of the newly allocated memory.

FOREIGN-BITFIELD-SYMBOL-LIST (BITFIELD-TYPE)

Return a list of SYMBOLS defined in BITFIELD-TYPE.

FOREIGN-BITFIELD-SYMBOLS (TYPE VALUE)

Convert an integer VALUE into a list of matching symbols according to the bitfield TYPE.

FOREIGN-BITFIELD-VALUE (TYPE SYMBOLS)

Convert a list of symbols into an integer according to the TYPE bitfield.

FOREIGN-ENUM-KEYWORD (TYPE VALUE &KEY (ERRORP T))

Convert an integer VALUE into a keyword according to the enum TYPE.

FOREIGN-ENUM-KEYWORD-LIST (ENUM-TYPE)

Return a list of KEYWORDS defined in ENUM-TYPE.

FOREIGN-ENUM-VALUE (TYPE KEYWORD &KEY (ERRORP T))

Convert a KEYWORD into an integer according to the enum TYPE.

FOREIGN-FREE (PTR)

Free a PTR allocated by FOREIGN-ALLOC.

FOREIGN-SLOT-COUNT (TYPE SLOT-NAME)

Return the number of items in SLOT in a struct TYPE.

FOREIGN-SLOT-NAMES (TYPE)

Returns a list of TYPE's slot names in no particular order.

FOREIGN-SLOT-OFFSET (TYPE SLOT-NAME)

Return the offset of SLOT in a struct TYPE.

FOREIGN-SLOT-POINTER (PTR TYPE SLOT-NAME)

Return the address of SLOT-NAME in the structure at PTR.

FOREIGN-SLOT-TYPE (TYPE SLOT-NAME)

Return the type of SLOT in a struct TYPE.

FOREIGN-SLOT-VALUE (PTR TYPE SLOT-NAME)

Return the value of SLOT-NAME in the foreign structure at PTR.

FOREIGN-STRING-ALLOC (STRING &KEY (ENCODING *DEFAULT-FOREIGN-ENCODING*) (NULL-TERMINATED-P T) (START 0) END)

Allocate a foreign string containing Lisp string STRING. The string must be freed with FOREIGN-STRING-FREE.

FOREIGN-STRING-FREE (PTR)

Free a foreign string allocated by FOREIGN-STRING-ALLOC.

FOREIGN-STRING-TO-LISP (POINTER &KEY (OFFSET 0) COUNT (MAX-CHARS (1- ARRAY-TOTAL-SIZE-LIMIT)) (ENCODING *DEFAULT-FOREIGN-ENCODING*))

Copy at most COUNT bytes from POINTER plus OFFSET encoded in ENCODING into a Lisp string and return it. If POINTER is a null pointer, NIL is returned.

FREE-RETURNED-IF-NEEDED (CFFI-TYPE PTR)

This function should be placed in appropriate place of translate-from-foreign

FREE-SENT-IF-NEEDED (CFFI-TYPE PTR PARAM)

This function should be placed in appropriate place of free-translated-object

GET-VAR-POINTER (SYMBOL)

Return a pointer to the foreign global variable relative to SYMBOL.

INC-POINTER (PTR OFFSET)

Return a pointer pointing OFFSET bytes past PTR.

INITIALIZE (OBJ FIELDS)

Used when you need to mark, that FIELDS already initialized

LIST-FOREIGN-LIBRARIES (&KEY (LOADED-ONLY T) TYPE)

Return a list of defined foreign libraries. If LOADED-ONLY is non-null only loaded libraries are returned. TYPE restricts the output to a specific library type: if NIL all libraries are returned.

LOAD-FOREIGN-LIBRARY (LIBRARY &KEY SEARCH-PATH)

Loads a foreign LIBRARY which can be a symbol denoting a library defined through DEFINE-FOREIGN-LIBRARY; a pathname or string in which case we try to load it directly first then search for it in *FOREIGN-LIBRARY-DIRECTORIES*; or finally list: either (:or lib1 lib2) or (:framework <framework-name>).

MAKE-POINTER (ADDRESS)

Return a pointer pointing to ADDRESS.

MAKE-SHAREABLE-BYTE-VECTOR (SIZE)

Create a Lisp vector of SIZE bytes can passed to WITH-POINTER-TO-VECTOR-DATA.

MEM-APTR (PTR TYPE &OPTIONAL (INDEX 0))

The pointer to the element.

MEM-AREF (PTR TYPE &OPTIONAL (INDEX 0))

Like MEM-REF except for accessing 1d arrays.

MEM-REF (PTR TYPE &OPTIONAL (OFFSET 0))

Return the value of TYPE at OFFSET bytes from PTR. If TYPE is aggregate, we don't return its 'value' but a pointer to it, which is PTR itself.

NULL-POINTER

Construct and return a null pointer.

NULL-POINTER-P (PTR)

Return true if PTR is a null pointer.

POINTER-ADDRESS (PTR)

Return the address pointed to by PTR.

POINTER-EQ (PTR1 PTR2)

Return true if PTR1 and PTR2 point to the same address.

POINTERP (PTR)

Return true if PTR is a foreign pointer.

RELOAD-FOREIGN-LIBRARIES (&KEY (TEST #'FOREIGN-LIBRARY-LOADED-P))

(Re)load all currently loaded foreign libraries.

Undocumented

CONVERT-FROM-FOREIGN (VALUE TYPE)

CONVERT-INTO-FOREIGN-MEMORY (VALUE TYPE PTR)

CONVERT-TO-FOREIGN (VALUE TYPE)

FOREIGN-LIBRARY-LOADED-P (LIB)

FOREIGN-LIBRARY-PATHNAME (LIB)

FOREIGN-LIBRARY-TYPE (LIB)

FOREIGN-SYMBOL-POINTER (NAME &KEY (LIBRARY DEFAULT))

FREE-CONVERTED-OBJECT (VALUE TYPE PARAM)

GET-CALLBACK (SYMBOL)

LISP-STRING-TO-FOREIGN (STRING BUFFER BUFSIZE &KEY (START 0) END OFFSET (ENCODING *DEFAULT-FOREIGN-ENCODING*))

OBJECT-BY-ID (ID-KEY)

PAIR (MAYBE-PAIR)

Private

FROM-FOREIGN (VAR TYPE COUNT)

VAR - symbol; type - symbol or list -- CFFI type; count -- integer

STRUCT->CLOS (CLASS STRUCT &OPTIONAL OBJECT)

Translates pointer STRUCT to object OBJECT (if not supplied, then to new object). I suppose, that by default it should convert data from pointer to struct. Only exception is the presence of OBJECT with not boundp value

Undocumented

%CLASS (TYPE VALUE)

CLOS->NEW-STRUCT (CLASS OBJECT)

CLOS->STRUCT (CLASS OBJECT STRUCT)

INITIALIZED (OBJ FIELD)

NAME-P (NAME)

PARSE-STRUCT (BODY)

PTR-STRUCT (PTR TYPE I)

SLOT-ACCESSOR (DESIGNATOR)

STRUCT-P (TYPE)

STRUCT-TYPE (TYPE)

MACRO

Public

DEFBITFIELD (NAME-AND-OPTIONS &BODY MASKS)

Define an foreign enumerated type.

DEFCENUM (NAME-AND-OPTIONS &BODY ENUM-LIST)

Define an foreign enumerated type.

DEFCFUN (NAME-AND-OPTIONS RETURN-TYPE &BODY ARGS)

Defines a Lisp function that calls a foreign function.

DEFCSTRUCT (NAME-AND-OPTIONS &BODY FIELDS)

Define the layout of a foreign structure.

DEFCSTRUCT-ACCESSORS (CLASS &REST FIELDS)

CLASS may be symbol = class-name = struct name, or may be cons (class-name . struct-name)

DEFCTYPE (NAME BASE-TYPE &OPTIONAL DOCUMENTATION)

Utility macro for simple C-like typedefs.

DEFCUNION (NAME-AND-OPTIONS &BODY FIELDS)

Define the layout of a foreign union.

DEFCVAR (NAME-AND-OPTIONS TYPE &OPTIONAL DOCUMENTATION)

Define a foreign global variable.

DEFINE-C-STRUCT-WRAPPER (CLASS-AND-TYPE SUPERS &OPTIONAL SLOTS)

Define a new class with CLOS slots matching those of a foreign struct type. An INITIALIZE-INSTANCE method is defined which takes a :POINTER initarg that is used to store the slots of a foreign object. This pointer is only used for initialization and it is not retained. CLASS-AND-TYPE is either a list of the form (class-name struct-type) or a single symbol naming both. The class will inherit SUPERS. If a list of SLOTS is specified, only those slots will be defined and stored.

DEFINE-FOREIGN-LIBRARY (NAME-AND-OPTIONS &BODY PAIRS)

Defines a foreign library NAME that can be posteriorly used with the USE-FOREIGN-LIBRARY macro.

DEFINE-PARSE-METHOD (NAME LAMBDA-LIST &BODY BODY)

Define a type parser on NAME and lists whose CAR is NAME.

DEFINE-TRANSLATION-METHOD ((OBJECT TYPE METHOD) &BODY BODY)

Define a translation method for the foreign structure type; 'method is one of :into, :from, or :to, meaning relation to foreign memory. If :into, the variable 'pointer is the foreign pointer. Note: type must be defined and loaded before this macro is expanded, and just the bare name (without :struct) should be specified.

FOREIGN-FUNCALL (NAME-AND-OPTIONS &REST ARGS)

Wrapper around %FOREIGN-FUNCALL that translates its arguments.

INIT-SLOTS (CLASS &OPTIONAL ADD-KEYS &BODY BODY)

For SETF-INIT auto-constructor

REMOVE-SETTER (CLASS NAME)

Use this to unregister setters for SETF-INIT and INIT-SLOTS macro

SAVE-SETTER (CLASS NAME)

Use this to register setters for SETF-INIT and INIT-SLOTS macro

SETF-INIT (OBJECT &REST FIELDS)

Should be used in constructors

TRANSLATION-FORMS-FOR-CLASS (CLASS TYPE-CLASS)

Make forms for translation of foreign structures to and from a standard class. The class slots are assumed to have the same name as the foreign structure.

WITH-FOREIGN-OBJECT ((VAR TYPE &OPTIONAL (COUNT 1)) &BODY BODY)

Bind VAR to a pointer to COUNT objects of TYPE during BODY. The buffer has dynamic extent and may be stack allocated.

WITH-FOREIGN-OUT ((VAR TYPE &OPTIONAL COUNT) RETURN-RESULT &BODY BODY)

The same as WITH-FOREIGN-OBJECT, but returns value of object

WITH-FOREIGN-OUTS (BINDINGS RETURN-RESULT &BODY BODY)

The same as WITH-FOREIGN-OBJECTS, but returns (values ...) of result and binded vars, RETURN-RESULT may be :RETURN - return result and values :IF-SUCCESS - return values if result t :IGNORE - discard result

WITH-FOREIGN-OUTS-LIST (BINDINGS RETURN-RESULT &BODY BODY)

The same as WITH-FOREIGN-OBJECTS, but returns list

WITH-FOREIGN-POINTER ((VAR SIZE &OPTIONAL SIZE-VAR) &BODY BODY)

Bind VAR to SIZE bytes of foreign memory during BODY. The pointer in VAR is invalid beyond the dynamic extent of BODY, and may be stack-allocated if supported by the implementation. If SIZE-VAR is supplied, it will be bound to SIZE during BODY.

WITH-FOREIGN-POINTER-AS-STRING ((VAR-OR-VARS SIZE &REST ARGS) &BODY BODY)

VAR-OR-VARS is not evaluated and should be a list of the form (VAR &OPTIONAL SIZE-VAR) or just a VAR symbol. VAR is bound to a foreign buffer of size SIZE within BODY. The return value is constructed by calling FOREIGN-STRING-TO-LISP on the foreign buffer along with ARGS.

WITH-FOREIGN-SLOTS ((VARS PTR TYPE) &BODY BODY)

Create local symbol macros for each var in VARS to reference foreign slots in PTR of TYPE. Similar to WITH-SLOTS.

WITH-FOREIGN-STRING ((VAR-OR-VARS LISP-STRING &REST ARGS) &BODY BODY)

VAR-OR-VARS is not evaluated ans should a list of the form (VAR &OPTIONAL BYTE-SIZE-VAR) or just a VAR symbol. VAR is bound to a foreign string containing LISP-STRING in BODY. When BYTE-SIZE-VAR is specified then bind the C buffer size (including the possible null terminator(s)) to this variable.

WITH-FOREIGN-STRINGS (BINDINGS &BODY BODY)

See WITH-FOREIGN-STRING's documentation.

WITH-POINTER-TO-VECTOR-DATA ((PTR-VAR VECTOR) &BODY BODY)

Bind PTR-VAR to a foreign pointer to the data in VECTOR.

Undocumented

CALLBACK (NAME)

CLEAR-SETTERS (CLASS)

DEFBITACCESSORS (CLASS SLOT &REST FIELDS)

DEFCALLBACK (NAME-AND-OPTIONS RETURN-TYPE ARGS &BODY BODY)

DEFCSTRUCT* (CLASS &BODY BODY)

DEFINE-FOREIGN-TYPE (NAME SUPERS SLOTS &REST OPTIONS)

FOREIGN-FUNCALL-POINTER (POINTER OPTIONS &REST ARGS)

INCF-POINTER (PLACE &OPTIONAL (OFFSET 1) &ENVIRONMENT ENV)

USE-FOREIGN-LIBRARY (NAME)

WITH-FOREIGN-OBJECTS (BINDINGS &BODY BODY)

Private

Undocumented

DEFACCESSOR (NAME C-NAME CLASS &BODY BODY)

GENERIC-FUNCTION

Public

COPY-FROM-FOREIGN (CFFI-TYPE PTR PLACE)

Transfers data from pointer PTR to PLACE. CFFI-TYPE: type defined with define-foreign-type. PTR: foreign pointer PLACE: third parameter of free-translated-object == returned second value of translate-to-foreign

FOREIGN-TYPE-ALIGNMENT (FOREIGN-TYPE)

Return the structure alignment in bytes of a foreign type.

FOREIGN-TYPE-SIZE (FOREIGN-TYPE)

Return the size in bytes of a foreign type.

FREE (OBJECT)

Removes object pointer from lisp hashes.

FREE-PTR (TYPE PTR)

Called to free ptr, unless overriden free-sent-ptr or free-returned-ptr. TYPE should be symbol and be specialized with EQL

FREE-RETURNED-PTR (CFFI-TYPE PTR)

Will be called in translate-from-foreign after conversion. CFFI-TYPE: type defined with define-foreign-type. PTR: foreign pointer

FREE-SENT-PTR (CFFI-TYPE PTR PARAM)

Will be called in free-translated-object. CFFI-TYPE: type defined with define-foreign-type. PTR: foreign pointer PARAM: third parameter of free-translated-object == returned second value of translate-to-foreign.

GCONSTRUCTOR (OBJECT &REST INITARGS &KEY NEW-STRUCT &ALLOW-OTHER-KEYS)

Called during initialization of OBJECT instance. Should return a pointer to foreign OBJECT instance, for example, by g_object_new.

TRANSLATE-INTO-FOREIGN-MEMORY (VALUE TYPE POINTER)

Translate the Lisp value into the foreign memory location given by pointer. Return value is not used.

Undocumented

EXPAND-FROM-FOREIGN (VALUE TYPE)

EXPAND-TO-FOREIGN (VALUE TYPE)

EXPAND-TO-FOREIGN-DYN (VALUE VAR BODY TYPE)

FREE-STRUCT (CLASS VALUE)

FREE-TRANSLATED-OBJECT (VALUE TYPE PARAM)

NEW-STRUCT (CLASS)

TRANSLATE-CAMELCASE-NAME (NAME &KEY UPPER-INITIAL-P SPECIAL-WORDS)

TRANSLATE-FROM-FOREIGN (VALUE TYPE)

TRANSLATE-NAME-FROM-FOREIGN (FOREIGN-NAME PACKAGE &OPTIONAL VARP)

TRANSLATE-NAME-TO-FOREIGN (LISP-NAME PACKAGE &OPTIONAL VARP)

TRANSLATE-TO-FOREIGN (VALUE TYPE)

TRANSLATE-UNDERSCORE-SEPARATED-NAME (NAME)

SLOT-ACCESSOR

Public

POINTER (OBJECT)

Empty method to return null-pointer for non-objects

VOLATILE (OBJECT)

Will not be saved in hash

SETFVOLATILE (NEW-VALUE OBJECT)

Will not be saved in hash

Undocumented

FOREIGN-LIBRARY-NAME (OBJECT)

SETFFOREIGN-LIBRARY-NAME (NEW-VALUE OBJECT)

OBJECT-CLASS (OBJECT)

SETFOBJECT-CLASS (NEW-VALUE OBJECT)

SETFPOINTER (NEW-VALUE OBJECT)

Private

OBJECT-OUT (OBJECT)

This is out param (for fill in foreign side)

SETFOBJECT-OUT (NEW-VALUE OBJECT)

This is out param (for fill in foreign side)

Undocumented

ELEMENT-TYPE (OBJECT)

SETFELEMENT-TYPE (NEW-VALUE OBJECT)

FST-FREE-FROM-FOREIGN-P (OBJECT)

FST-FREE-TO-FOREIGN-P (OBJECT)

ID (OBJECT)

SETFID (NEW-VALUE OBJECT)

VARIABLE

Public

*BUILT-IN-FLOAT-TYPES*

List of real float types supported by CFFI.

*BUILT-IN-INTEGER-TYPES*

List of integer types supported by CFFI.

*DARWIN-FRAMEWORK-DIRECTORIES*

List of directories where Frameworks are searched for.

*DEFAULT-FOREIGN-ENCODING*

Default foreign encoding.

*FOREIGN-LIBRARY-DIRECTORIES*

List onto which user-defined library paths can be pushed.

*OBJECTS*

Hash table: foreign-pointer address as integer -> lisp object

*OBJECTS-IDS*

Hash table: atom -> lisp object

*OTHER-BUILTIN-TYPES*

List of types other than integer or float built in to CFFI.

Undocumented

*ARRAY-LENGTH*

*BUILT-IN-FOREIGN-TYPES*

CLASS

Public

FREEABLE

Mixing to auto-set translators

FREEABLE-OUT

For returning data in out params. If OUT is t, then translate-to-foreign MUST return (values ptr place)

OBJECT

Lisp wrapper for any object. VOLATILE slot set when object shouldn't be stored in *OBJECTS*. Stored pointer GC'ed, if VOLATILE.

PFUNCTION

Takes a foreign pointer, keyword or a string. Keyword or a string = name of C function, substituting #- to #_

STRUCT

If value bound, use it, else use pointer. Struct may be used in OBJECT cffi-type or STRUCT cffi-type

Undocumented

CFFI-ARRAY

CFFI-KEYWORD

CFFI-NULL-ARRAY

CFFI-OBJECT

CFFI-PATHNAME

CFFI-STRUCT

FOREIGN-LIBRARY

FREEABLE-BASE

CONDITION

Public

Undocumented

LOAD-FOREIGN-LIBRARY-ERROR