The cl-growl Reference Manual

4.1.1 cl-growl/cl-growl.asd

Source

cl-growl.asd.

Parent Component

cl-growl (system).

ASDF Systems

cl-growl.

---

4.1.2 cl-growl/src/package.lisp

Source

cl-growl.asd.

Parent Component

src (module).

Packages

cl-growl.

---

4.1.3 cl-growl/src/constants.lisp

Dependency

package.lisp (file).

Source

cl-growl.asd.

Parent Component

src (module).

Internals

• +growl-notify-message-type+ (constant).
• +growl-protocol-version+ (constant).
• +growl-register-message-type+ (constant).
• +growl-subscribe-message-type+ (constant).
• define-constant (macro).

---

4.1.4 cl-growl/src/types.lisp

Dependency

package.lisp (file).

Source

cl-growl.asd.

Parent Component

src (module).

Internals

• growl-binary-data-type (type).
• growl-checksum-mode (type).
• growl-encryption-mode (type).
• incompatible-checksum-requested-mode (reader method).
• incompatible-encryption-and-checksum-error (condition).
• incompatible-encryption-requested-mode (reader method).
• report-incompatible-encryption-and-checksum-error (function).
• report-unavailable-checksum-error (function).
• report-unavailable-encryption-error (function).
• report-unsupported-iv-type-error (function).
• report-unsupported-salt-type-error (function).
• unavailable-checksum-error (condition).
• unavailable-checksum-requested-mode (reader method).
• unavailable-encryption-error (condition).
• unavailable-encryption-requested-mode (reader method).
• unsupported-iv-type-encryption-mode (reader method).
• unsupported-iv-type-error (condition).
• unsupported-iv-type-iv (reader method).
• unsupported-salt-type-error (condition).
• unsupported-salt-type-salt (reader method).

---

4.1.5 cl-growl/src/utils.lisp

Dependency

package.lisp (file).

Source

cl-growl.asd.

Parent Component

src (module).

Internals

• 3des (function).
• aes (function).
• checksum (function).
• des (function).
• echo-all-bytes (function).
• encrypt (function).
• generate-iv (function).
• generate-random-bytes (function).
• generate-salt (function).
• generate-unique-id (function).
• hex-encode (function).
• ironclad-encrypt (function).
• md5 (function).
• noauth (function).
• pkcs7-pad (function).
• sha1 (function).
• sha256 (function).
• with-output-to-binary-string (macro).
• with-utf-8-strings (macro).
• write-short (function).

---

4.1.6 cl-growl/src/specials.lisp

Dependencies

• package.lisp (file).
• types.lisp (file).
• utils.lisp (file).

Source

cl-growl.asd.

Parent Component

src (module).

Public Interface

• *growl-default-app* (special variable).
• *growl-default-app-icon* (special variable).
• *growl-default-callback-context* (special variable).
• *growl-default-callback-context-type* (special variable).
• *growl-default-callback-target* (special variable).
• *growl-default-checksum-mode* (special variable).
• *growl-default-custom-fields* (special variable).
• *growl-default-encryption-mode* (special variable).
• *growl-default-host* (special variable).
• *growl-default-icon* (special variable).
• *growl-default-notification* (special variable).
• *growl-default-origin-fields* (special variable).
• *growl-default-password* (special variable).
• *growl-default-port* (special variable).
• *growl-default-priority* (special variable).
• *growl-default-salt* (special variable).
• *growl-default-title* (special variable).

Internals

• *growl-default-application-fields* (special variable).
• *growl-default-iv* (special variable).

---

4.1.7 cl-growl/src/gntp.lisp

Dependencies

• package.lisp (file).
• constants.lisp (file).
• types.lisp (file).
• utils.lisp (file).

Source

cl-growl.asd.

Parent Component

src (module).

Internals

• app-hdr-line (function).
• compose (function).
• custom-hdr-line (function).
• encode-binary-data (function).
• hdr-line (function).
• hdr-terpri (function).
• make-encryption-hdr (function).
• make-key (function).
• make-password-hash-hdr (function).
• notice-decl (function).
• optional-icon (function).
• optional-id (function).
• optional-string (function).
• origin-hdr-line (function).
• require-iv (function).
• require-salt (function).
• required-id (function).
• required-string (function).
• required-value (function).
• valid-encryption-checksum-combo (function).
• valid-field (function).
• valid-notice-decl (function).
• valid-origin-field (function).
• valid-port (function).
• valid-priority (function).

---

4.1.8 cl-growl/src/register.lisp

Dependencies

• package.lisp (file).
• constants.lisp (file).
• types.lisp (file).
• specials.lisp (file).
• utils.lisp (file).
• gntp.lisp (file).

Source

cl-growl.asd.

Parent Component

src (module).

Public Interface

register (function).

---

4.1.9 cl-growl/src/notify.lisp

Dependencies

• package.lisp (file).
• constants.lisp (file).
• types.lisp (file).
• specials.lisp (file).
• utils.lisp (file).

Source

cl-growl.asd.

Parent Component

src (module).

Public Interface

notify (function).

---

6.1.1 Special variables

Special Variable: *growl-default-app* ¶

This is the default name by which your application will identify itself to the Growl server.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-app-icon* ¶

If not NIL, this icon will be transmitted to the Growl server. It can be either an encoded image stored in a one-dimensional binary array or a URL for the icon image to use.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-callback-context* ¶

If not NIL, this will be the default context supplied to
a callback for the notification. Growl invokes a callback when the user clicks the notification, when the user closes the notification, or when the notification times out.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-callback-context-type* ¶

If not NIL, this specifies the context type information supplied to the callback for the notification.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-callback-target* ¶

If not NIL, this should be a URL for a callback method. This URL will be opened in the user’s default browser if the user clicks the notification.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-checksum-mode* ¶

Default hash algorithm to use. It must be a valid GROWL-CHECKSUM-MODE.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-custom-fields* ¶

GNTP allows custom fields in the Growl message headers. This must be a LIST of CONS cells. The CAR of each cell is the field name. The CDR of each cell is the field value. The value can either be a string or a one-dimensional binary array.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-encryption-mode* ¶

Default encryption algorithm to use. It could be :AES, :DES, :3DES, or :NONE. You need Ironclad to do anything other than :NONE.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-host* ¶

This is the default hostname of the Growl server

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-icon* ¶

If not NIL, this is the default notification-icon that will be transmitted to the Growl server along with your notification events. It can be either an encoded image stored in a one-dimensional binary array or a URL for the icon image to use.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-notification* ¶

This is the default notification level to use when sending notification events to the Growl server.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-origin-fields* ¶

GNTP allows fields that describe the system/software that generated the message.
This must be a LIST of CONS cells. The CAR of each cell is the field name. The CDR of each cell is the field value. The value can either be a string or a one-dimensional binary array.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-password* ¶

Default password to use if the hash algorithm is not :NONE

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-port* ¶

This is the default port number the Growl server is listening on. This is the GNTP default port.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-priority* ¶

If not NIL, this is the default priority used when sending notification events to the Growl server.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-salt* ¶

This can be either a function of no arguments used to generate a binary array or string as a salt, a fixed binary array, or a fixed string.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-title* ¶

This is the default message title to use when sending notification events to the Growl server.

Package

cl-growl.

Source

specials.lisp.

---

6.1.2 Ordinary functions

Function: notify (body &key app notification id title sticky priority icon coalesce callback-context callback-context-type callback-target host port checksum-mode encryption-mode password salt iv) ¶

Send a notification with TITLE as its title and BODY as its text body. The notificiation is from the APP and with notification name NOTIFICATION. It has an ID that is hopefully unique to this notification. And, it has an advisory PRIORITY on the range [-2,2] (unless PRIORITY is nil). The app can request that the notification be STICKY.

This notice can specify its own ICON either by URL or by sending along the binary data.

If a COALESCE is given, it should contain the ID of a previously sent notification that should be updated or replaced by this one.

If a CALLBACK-CONTEXT string is given, it specifies that GROWL should send a message back on this notification’s socket when the user click the message, closes the message, or when the message times out. If CALLBACK-CONTEXT is non-nil (and non-empty), then CALLBACK-CONTEXT-TYPE must also be non-nil (and non-empty). The CALLBACK-CONTEXT and CALLBACK-CONTEXT-TYPE are returned in the callback.

If a CALLBACK-TARGET is specified, it must be a URL. If the user clicks on a notification with a CALLBACK-TARGET, the user’s default browser is opened to the CALLBACK-TARGET URL.

If SALT is an array of unsigned bytes, it will be used directly. If SALT is a string, it will be converted to an array of unsigned bytes using a UTF-8 encoding. If SALT is a function, it will be invoked with zero arguments and can either return an array of unsigned bytes or a string.

This function returns (VALUES STREAM ID). STREAM will be NIL if there is no CALLBACK-CONTEXT. It will be a stream for the socket on which the callback will arrive if a CALLBACK-CONTEXT was given. ID will be the notification ID used for this message.

Package

cl-growl.

Source

notify.lisp.

Function: register (&key app app-icon enabled disabled origin-fields custom-fields application-fields host port checksum-mode encryption-mode password salt iv) ¶

Register as the application named APP with the ENABLED notifications turned on and the DISABLED notifications turned off by default.

The ENABLED and DISABLED parameters are lists. The list elements of the ENABLED and DISABLED parameters can be either a string or a list. If it is a string, it is the name of a notification. If it is a list, it can have either one, two, or three members. The first member is the notification name, the second member (if present) is the human-readable notification name, and the third member (if present) is the notification icon. The third item can be either a URL to the notification icon or a one-dimensional binary vector containing the encoded icon image.

Package

cl-growl.

Source

register.lisp.

---

6.2.1 Constants

Constant: +growl-notify-message-type+ ¶

Message type for notify messages.

Package

cl-growl.

Source

constants.lisp.

Constant: +growl-protocol-version+ ¶

GNTP Protocol Version

Package

cl-growl.

Source

constants.lisp.

Constant: +growl-register-message-type+ ¶

Message type for register messages.

Package

cl-growl.

Source

constants.lisp.

Constant: +growl-subscribe-message-type+ ¶

Message type for subscribe messages.

Package

cl-growl.

Source

constants.lisp.

---

6.2.2 Special variables

Special Variable: *growl-default-application-fields* ¶

GNTP allows app-specific field in the Growl message headers. This must be a LIST of CONS cells. The CAR of each cell is the field name. The CDR of each cell is the field value. The value can either be a string or
a one-dimensional binary array.

Package

cl-growl.

Source

specials.lisp.

Special Variable: *growl-default-iv* ¶

This can be either a function that takes the encryption mode and returns a binary array or string as a salt, a fixed binary array, or a fixed string.

Package

cl-growl.

Source

specials.lisp.

---

6.2.3 Macros

Macro: define-constant (name value &optional doc) ¶

Package

cl-growl.

Source

constants.lisp.

Macro: with-output-to-binary-string (&body body) ¶

Package

cl-growl.

Source

utils.lisp.

Macro: with-utf-8-strings ((&rest names) &body body) ¶

Package

cl-growl.

Source

utils.lisp.

---

6.2.4 Ordinary functions

Function: 3des (payload key iv) ¶

Package

cl-growl.

Source

utils.lisp.

Function: aes (payload key iv) ¶

Package

cl-growl.

Source

utils.lisp.

Function: app-hdr-line (hdr data-hash) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: checksum (payload password checksum-mode) ¶

Package

cl-growl.

Source

utils.lisp.

Function: compose (message-type &key header binary-data checksum-mode encryption-mode password salt iv) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: custom-hdr-line (hdr data-hash) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: des (payload key iv) ¶

Package

cl-growl.

Source

utils.lisp.

Function: echo-all-bytes (stream &optional buffer) ¶

Package

cl-growl.

Source

utils.lisp.

Function: encode-binary-data (id value &key encryption-mode key iv) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: encrypt (payload encryption-mode key iv) ¶

Package

cl-growl.

Source

utils.lisp.

Function: generate-iv (encryption-mode) ¶

Package

cl-growl.

Source

utils.lisp.

Function: generate-random-bytes (byte-count) ¶

Package

cl-growl.

Source

utils.lisp.

Function: generate-salt (salt-byte-count) ¶

Package

cl-growl.

Source

utils.lisp.

Function: generate-unique-id (item) ¶

Package

cl-growl.

Source

utils.lisp.

Function: hdr-line (key value data-hash) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: hdr-terpri () ¶

Package

cl-growl.

Source

gntp.lisp.

Function: hex-encode (bytes) ¶

Package

cl-growl.

Source

utils.lisp.

Function: ironclad-encrypt (name payload key iv) ¶

Package

cl-growl.

Source

utils.lisp.

Function: make-encryption-hdr (encryption-mode iv) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: make-key (checksum-mode password salt) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: make-password-hash-hdr (key checksum-mode salt) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: md5 (buffer password) ¶

Package

cl-growl.

Source

utils.lisp.

Function: noauth (buffer password) ¶

Package

cl-growl.

Source

utils.lisp.

Function: notice-decl (nn enabled data-hash) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: optional-icon (ii) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: optional-id (id) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: optional-string (ss) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: origin-hdr-line (hdr data-hash) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: pkcs7-pad (payload block-len) ¶

Package

cl-growl.

Source

utils.lisp.

Function: report-incompatible-encryption-and-checksum-error (err stream) ¶

Package

cl-growl.

Source

types.lisp.

Function: report-unavailable-checksum-error (err stream) ¶

Package

cl-growl.

Source

types.lisp.

Function: report-unavailable-encryption-error (err stream) ¶

Package

cl-growl.

Source

types.lisp.

Function: report-unsupported-iv-type-error (err stream) ¶

Package

cl-growl.

Source

types.lisp.

Function: report-unsupported-salt-type-error (err stream) ¶

Package

cl-growl.

Source

types.lisp.

Function: require-iv (iv encryption-mode) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: require-salt (salt) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: required-id (id) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: required-string (ss) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: required-value (vv) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: sha1 (buffer password) ¶

Package

cl-growl.

Source

utils.lisp.

Function: sha256 (buffer password) ¶

Package

cl-growl.

Source

utils.lisp.

Function: valid-encryption-checksum-combo (encryption-mode checksum-mode) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: valid-field (ff) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: valid-notice-decl (nn) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: valid-origin-field (ff) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: valid-port (pp) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: valid-priority (pp) ¶

Package

cl-growl.

Source

gntp.lisp.

Function: write-short (ss stream) ¶

Package

cl-growl.

Source

utils.lisp.

---

6.2.5 Generic functions

Generic Reader: incompatible-checksum-requested-mode (condition) ¶

Package

cl-growl.

Methods

Reader Method: incompatible-checksum-requested-mode ((condition incompatible-encryption-and-checksum-error)) ¶

Source

types.lisp.

Target Slot

requested-checksum-mode.

Generic Reader: incompatible-encryption-requested-mode (condition) ¶

Package

cl-growl.

Methods

Reader Method: incompatible-encryption-requested-mode ((condition incompatible-encryption-and-checksum-error)) ¶

Source

types.lisp.

Target Slot

requested-encryption-mode.

Generic Reader: unavailable-checksum-requested-mode (condition) ¶

Package

cl-growl.

Methods

Reader Method: unavailable-checksum-requested-mode ((condition unavailable-checksum-error)) ¶

Source

types.lisp.

Target Slot

requested-mode.

Generic Reader: unavailable-encryption-requested-mode (condition) ¶

Package

cl-growl.

Methods

Reader Method: unavailable-encryption-requested-mode ((condition unavailable-encryption-error)) ¶

Source

types.lisp.

Target Slot

requested-mode.

Generic Reader: unsupported-iv-type-encryption-mode (condition) ¶

Package

cl-growl.

Methods

Reader Method: unsupported-iv-type-encryption-mode ((condition unsupported-iv-type-error)) ¶

Source

types.lisp.

Target Slot

encryption-mode.

Generic Reader: unsupported-iv-type-iv (condition) ¶

Package

cl-growl.

Methods

Reader Method: unsupported-iv-type-iv ((condition unsupported-iv-type-error)) ¶

Source

types.lisp.

Target Slot

iv.

Generic Reader: unsupported-salt-type-salt (condition) ¶

Package

cl-growl.

Methods

Reader Method: unsupported-salt-type-salt ((condition unsupported-salt-type-error)) ¶

Source

types.lisp.

Target Slot

salt.

---

6.2.6 Conditions

Condition: incompatible-encryption-and-checksum-error ¶

Package

cl-growl.

Source

types.lisp.

Direct superclasses

error.

Direct methods

• incompatible-checksum-requested-mode.
• incompatible-encryption-requested-mode.

Direct slots

Slot: requested-encryption-mode ¶

Initargs

:requested-encryption-mode

Readers

incompatible-encryption-requested-mode.

Writers

This slot is read-only.

Slot: requested-checksum-mode ¶

Initargs

:requested-checksum-mode

Readers

incompatible-checksum-requested-mode.

Writers

This slot is read-only.

Condition: unavailable-checksum-error ¶

Package

cl-growl.

Source

types.lisp.

Direct superclasses

error.

Direct methods

unavailable-checksum-requested-mode.

Direct slots

Slot: requested-mode ¶

Initargs

:requested-mode

Readers

unavailable-checksum-requested-mode.

Writers

This slot is read-only.

Condition: unavailable-encryption-error ¶

Package

cl-growl.

Source

types.lisp.

Direct superclasses

error.

Direct methods

unavailable-encryption-requested-mode.

Direct slots

Slot: requested-mode ¶

Initargs

:requested-mode

Readers

unavailable-encryption-requested-mode.

Writers

This slot is read-only.

Condition: unsupported-iv-type-error ¶

Package

cl-growl.

Source

types.lisp.

Direct superclasses

error.

Direct methods

• unsupported-iv-type-encryption-mode.
• unsupported-iv-type-iv.

Direct slots

Slot: iv ¶

Initargs

:iv

Readers

unsupported-iv-type-iv.

Writers

This slot is read-only.

Slot: encryption-mode ¶

Initargs

:encryption-mode

Readers

unsupported-iv-type-encryption-mode.

Writers

This slot is read-only.

Condition: unsupported-salt-type-error ¶

Package

cl-growl.

Source

types.lisp.

Direct superclasses

error.

Direct methods

unsupported-salt-type-salt.

Direct slots

Slot: salt ¶

Initargs

:salt

Readers

unsupported-salt-type-salt.

Writers

This slot is read-only.

---

6.2.7 Types

Type: growl-binary-data-type () ¶

Package

cl-growl.

Source

types.lisp.

Type: growl-checksum-mode () ¶

If you have Ironclad, you can do :SHA256, :SHA1, :MD5, or :NONE. If you have the MD5 package, you can do :MD5 or :NONE.
If you have neither Ironclad nor MD5, you can only do :NONE. With :NONE, you will not be able to do authenticated Growl transactions.

Package

cl-growl.

Source

types.lisp.

Type: growl-encryption-mode () ¶

If you have Ironclad, then you can encrypt with mode :AES, :DES, :3DES, or :NONE. If you do not have Ironclad, you can only use the :NONE mode. You can still do authenticated Growl transactions with encryption mode :NONE, but the contents of the transaction will go over the network in plain text so an eavesdropper could potentially read the contents of the Growl.

Package

cl-growl.

Source

types.lisp.

---