6.3.4 Guile API

This subsection describes callback functions that a Guile database module must provide. The description of each function begins with the function prototype and its entry in the virtual function table.

Guile Callback: open-db name . args

Virtual table: (cons "open" open-db)

Open the database. The argument name contains database name as given in dbname of the database declaration (see databases). Optional argument args is a list of command line parameters obtained from cmdline in database statement (see guile-cmdline). For example, if the configuration file contained:

database foo guile db=file 1 no

then the open-db callback will be called as:

(open-db "foo" '("db=file" "1" "no"))

The open-db callback returns a database handle, i.e. an opaque Scheme object which identifies this database, and keeps its internal state. This value, hereinafter named dbh, will be passed to another callback functions that need to access the database.

The unspecified return value indicates an error.

Guile Callback: close-db dbh

Virtual Table: (cons "close" close-db)

Close the database. This function is called during the cleanup procedure, before termination of smapd child process. The argument dbh is a database handle returned by open-db.

The return value from close-db is ignored. To communicate errors to the daemon, throw an exception.

Guile Callback: query-db dbh map key . rest

Virtual Table: (cons "close" close-db)
Perform the query. Arguments are:

dbh

A database handle returned by open-db.

map

The map name.

key

The lookup key.

rest

If this query came over a UNIX socket, this argument is ‘()’. Otherwise, if the query came over an INET socket, rest is a list of two network socket addresses (see Network Socket Address in The Guile Reference Manual): first element is the address of the remote party (client), second element is the address of the server that is handling the query.

This function must write the reply, terminated with a newline, to the current output port, e.g.:

(define-public (smap-query handle map arg . rest)
  (display "NOTFOUND")
  (newline))

Guile Callback: xform-db dbh arg . rest

Virtual Table: (cons "xform" xform-db)
Transform the argument arg. Arguments dbh and rest have the same meaning as in query-db.

Returns transformed value or ‘#f’ if no transformation applies. This callback may be used to alter map or key values using ‘guile’ module (see transformations). The following example function removes optional domain part from its argument:

(define (smap-xform handle arg . rest)
  (let ((arg-parts (string-split arg #\@)))
    (if (null? (cdr arg-parts))
	#f
	(car arg-parts))))

The following snippet from the smapd.conf file shows how to apply it:

database localpart guile init-script=local.scm

dispatch key like *@* transform key localpart