CFFI User Manual - Common Lisp.net

Chapter 4: An Introduction to Foreign Interfaces and CFFI 18
Of course, that itself is slightly unwieldy, so you may want to define a function around it
that simply retrieves a URL. I will leave synthesis of all the relevant REPL forms presented
thus far into a single function as an exercise for the reader.
The remaining sections of this tutorial explore some advanced features of CFFI; the
definition of new types will receive special attention. Some of these features are essential
for particular foreign function calls; some are very helpful when trying to develop a Lispy
interface to C.
4.11 Defining new types
We’ve occasionally used the defctype macro in previous sections as a kind of documentation,
much what you’d use typedef for in C. We also tried one special kind of type
definition, the defcenum type. See [defcstruct], page 33, for a definition macro that may
come in handy if you need to use C structs as data.
However, all of these are mostly sugar for the powerful underlying foreign type interface
called type translators. You can easily define new translators for any simple named foreign
type. Since we’ve defined the new type curl-code to use as the return type for various
libcurl functions, we can use that to directly convert cURL errors to Lisp errors.
defctype’s purpose is to define simple typedef-like aliases. In order to use type translators
we must use the define-foreign-type macro. So let’s redefine curl-code using
it.
(define-foreign-type curl-code-type ()
()
(:actual-type :int)
(:simple-parser curl-code))
define-foreign-type is a thin wrapper around defclass. For now, all you need to
know in the context of this example is that it does what (defctype curl-code :int) would
do and, additionally, defines a new class curl-code-type which we will take advantage of
shortly.
The CURLcode enumeration seems to follow the typical error code convention of ‘0’
meaning all is well, and each non-zero integer indicating a different kind of error. We can
apply that trivially to differentiate between normal exits and error exits.
(define-condition curl-code-error (error)
(($code :initarg :curl-code :reader curl-error-code))
(:report (lambda (c stream)
(format stream "libcurl function returned error ~A"
(curl-error-code c))))
(:documentation "Signalled when a libcurl function answers
a code other than CURLE_OK."))
(defmethod translate-from-foreign (value (type curl-code-type))
"Raise a CURL-CODE-ERROR if VALUE, a curl-code, is non-zero."
(if (zerop value)
:curle-ok
(error ’curl-code-error :curl-code value)))