# GrowlApplicationBridge-Carbon.h

## Abstract

Declares an API that Carbon applications can use to interact with Growl.

## Discussion

GrowlApplicationBridge uses a delegate to provide information //XXX to Growl (such as your application's name and what notifications it may post) and to provide information to your application (such as that Growl is listening for notifications or that a notification has been clicked).
You can set the Growldelegate with Growl_SetDelegate and find out the current delegate with Growl_GetDelegate. See struct Growl_Delegate for more information about the delegate.

## Functions

`Growl_CopyRegistrationDictionaryFromBundle`
  Looks in a bundle for a registration dictionary.
`Growl_CopyRegistrationDictionaryFromDelegate`
  Asks the delegate for a registration dictionary.
`Growl_CreateBestRegistrationDictionary`
  Obtains a registration dictionary, filled out to the best of GrowlApplicationBridge's knowledge.
`Growl_CreateRegistrationDictionaryByFillingInDictionary`
  Tries to fill in missing keys in a registration dictionary.
`Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys`
  Tries to fill in missing keys in a registration dictionary.
`Growl_GetDelegate`
  Returns the current Growl delegate, if any.
`Growl_IsInstalled`
  Determines whether the Growl prefpane and its helper app are installed.
`Growl_IsRunning`
  Cycles through the process list to find whether GrowlHelperApp is running.
`Growl_LaunchIfInstalled`
  Launches GrowlHelperApp if it is not already running.
`Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext`
  Posts a Growl notification using parameter values.
`Growl_PostNotification`
  Posts a Growl notification.
`Growl_PostNotificationWithDictionary`
  Notifies using a userInfo dictionary suitable for passing to CFDistributedNotificationCenter.
`Growl_RegisterWithDictionary`
  Register your application with Growl without setting a delegate.
`Growl_Reregister`
  Updates your registration with Growl.
`Growl_SetDelegate`
  Replaces the current Growl delegate with a new one, or removes the Growl delegate.
`Growl_SetWillRegisterWhenGrowlIsReady`
  Tells GrowlApplicationBridge to register with Growl when Growl launches (or not).
`Growl_WillRegisterWhenGrowlIsReady`
  Reports whether GrowlApplicationBridge will register with Growl when Growl next launches.

### Growl_CopyRegistrationDictionaryFromBundle

Looks in a bundle for a registration dictionary.

>     CFDictionaryRef Growl_CopyRegistrationDictionaryFromBundle(
>         CFBundleRef bundle);

function result
  A registration dictionary.

##### Discussion

This function looks in a bundle for an auto-discoverable registration dictionary file using `CFBundleCopyResourceURL`. If it finds one, it loads the file using `CFPropertyList` and returns the result.
If you pass `NULL` as the bundle, the main bundle is examined.
This function does not attempt to clean up the dictionary in any way - for example, if it is missing the `GROWL_APP_NAME` key, the result will be missing it too. Use `Growl_CreateRegistrationDictionaryByFillingInDictionary:` or `Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys` to try to fill in missing keys.
This function was introduced in Growl.framework 0.7.

### Growl_CopyRegistrationDictionaryFromDelegate

Asks the delegate for a registration dictionary.

>     CFDictionaryRef Growl_CopyRegistrationDictionaryFromDelegate(
>         void);

function result
  A registration dictionary.

##### Discussion

If no delegate is set, or if the delegate's `registrationDictionary` member is `NULL`, this function returns `NULL`.
This function does not attempt to clean up the dictionary in any way - for example, if it is missing the `GROWL_APP_NAME` key, the result will be missing it too. Use `Growl_CreateRegistrationDictionaryByFillingInDictionary:` or `Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys` to try to fill in missing keys.
This function was introduced in Growl.framework 0.7.

### Growl_CreateBestRegistrationDictionary

Obtains a registration dictionary, filled out to the best of GrowlApplicationBridge's knowledge.

>     CFDictionaryRef Growl_CreateBestRegistrationDictionary(
>         void);

function result
  A registration dictionary.

##### Discussion

This function creates a registration dictionary as best GrowlApplicationBridge knows how.
First, GrowlApplicationBridge examines the Growl delegate (if there is one) and gets the registration dictionary from that. If no such dictionary was obtained, GrowlApplicationBridge looks in your application's main bundle for an auto-discoverable registration dictionary file. If that doesn't exist either, this function returns `NULL`.
Second, GrowlApplicationBridge calls `Growl_CreateRegistrationDictionaryByFillingInDictionary` with whatever dictionary was obtained. The result of that function is the result of this function.
GrowlApplicationBridge uses this function when you call `Growl_SetDelegate`, or when you call `Growl_RegisterWithDictionary` with `NULL`.
This function was introduced in Growl.framework 0.7.

### Growl_CreateRegistrationDictionaryByFillingInDictionary

Tries to fill in missing keys in a registration dictionary.

>     CFDictionaryRef Growl_CreateRegistrationDictionaryByFillingInDictionary(
>         CFDictionaryRef regDict);

##### Parameter Descriptions

> `regDict`
>   The dictionary to fill in.

function result
  The dictionary with the keys filled in.

##### Discussion

This function examines the passed-in dictionary for missing keys, and tries to work out correct values for them. As of 0.7, it uses:
Key Value --- ----- `GROWL_APP_NAME` `CFBundleExecutableName` `GROWL_APP_ICON` The icon of the application. `GROWL_APP_LOCATION` The location of the application. `GROWL_NOTIFICATIONS_DEFAULT` `GROWL_NOTIFICATIONS_ALL`
Keys are only filled in if missing; if a key is present in the dictionary, its value will not be changed.
This function was introduced in Growl.framework 0.7.

### Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys

Tries to fill in missing keys in a registration dictionary.

>     CFDictionaryRef Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys(
>         CFDictionaryRef regDict,
>         CFSetRef keys);

##### Parameter Descriptions

> `regDict`
>   The dictionary to fill in.
> `keys`
>   The keys to fill in. If `NULL`, any missing keys are filled in.

function result
  The dictionary with the keys filled in.

##### Discussion

This function examines the passed-in dictionary for missing keys, and tries to work out correct values for them. As of 0.7, it uses:
Key Value --- ----- `GROWL_APP_NAME` `CFBundleExecutableName` `GROWL_APP_ICON` The icon of the application. `GROWL_APP_LOCATION` The location of the application. `GROWL_NOTIFICATIONS_DEFAULT` `GROWL_NOTIFICATIONS_ALL`
Only those keys that are listed in `keys` will be filled in. Other missing keys are ignored. Also, keys are only filled in if missing; if a key is present in the dictionary, its value will not be changed.
This function was introduced in Growl.framework 0.7.

### Growl_GetDelegate

Returns the current Growl delegate, if any.

>     struct Growl_Delegate *Growl_GetDelegate(
>         void);

function result
  The current Growl delegate.

##### Discussion

Returns the last pointer passed into Growl_SetDelegate, or `NULL` if no such call has been made.
This function follows standard Core Foundation reference-counting rules. Because it is a Get function, not a Copy function, it will not retain the delegate on your behalf. You are responsible for retaining and releasing the delegate as needed.

### Growl_IsInstalled

Determines whether the Growl prefpane and its helper app are installed.

>     Boolean Growl_IsInstalled(
>         void);

function result
  Returns true if Growl is installed, false otherwise.

### Growl_IsRunning

Cycles through the process list to find whether GrowlHelperApp is running.

>     Boolean Growl_IsRunning(
>         void);

function result
  Returns true if Growl is running, false otherwise.

### Growl_LaunchIfInstalled

Launches GrowlHelperApp if it is not already running.

>     Boolean Growl_LaunchIfInstalled(
>         GrowlLaunchCallback callback,
>         void *context);

##### Parameter Descriptions

> `callback`
>   A callback function which will be called if Growl was successfully launched or was already running. Can be `NULL`.
> `context`
>   The context pointer to pass to the callback. Can be `NULL`.

function result
  Returns true if Growl was successfully launched or was already running; returns false and does not call the callback otherwise.

##### Discussion

Returns true and calls the callback (if the callback is not `NULL`) if the Growl helper app began launching or was already running. Returns false and performs no other action if Growl could not be launched (e.g. because the Growl preference pane is not properly installed).
If `Growl_CreateBestRegistrationDictionary` returns non-`NULL`, this function will register with Growl atomically.
The callback should take a single argument; this is to allow applications to have context-relevant information passed back. It is perfectly acceptable for context to be `NULL`. The callback itself can be `NULL` if you don't want one.

### Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext

Posts a Growl notification using parameter values.

>     void Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext(
>         /*inhale*/
>         CFStringRef title,
>         CFStringRef description,
>         CFStringRef notificationName,
>         CFDataRef iconData,
>         signed int priority,
>         Boolean isSticky,
>         CFPropertyListRef clickContext);

##### Parameter Descriptions

> `title`
>   The title of the notification.
> `description`
>   The description of the notification.
> `notificationName`
>   The name of the notification as listed in the registration dictionary.
> `iconData`
>   Data representing a notification icon. Can be `NULL`.
> `priority`
>   The priority of the notification (-2 to +2, with -2 being Very Low and +2 being Very High).
> `isSticky`
>   If true, requests that this notification wait for a response from the user.
> `clickContext`
>   An object to pass to the clickCallback, if any. Can be `NULL`, in which case the clickCallback is not called.

##### Discussion

Creates a temporary Growl_Notification, fills it out with the supplied information, and calls Growl_PostNotification on it. See struct Growl_Notification and Growl_PostNotification for more information.
The icon data can be in any format supported by NSImage. As of Mac OS X

### Growl_PostNotification

Posts a Growl notification.

>     void Growl_PostNotification(
>         const struct Growl_Notification *notification);

##### Parameter Descriptions

> `notification`
>   The notification to post.

##### Discussion

This is the preferred means for sending a Growl notification. The notification name and at least one of the title and description are required (all three are preferred). All other parameters may be `NULL` (or 0 or false as appropriate) to accept default values.
If using the Growl-WithInstaller framework, if Growl is not installed the user will be prompted to install Growl. If the user cancels, this function will have no effect until the next application session, at which time when it is called the user will be prompted again. The user is also given the option to not be prompted again. If the user does choose to install Growl, the requested notification will be displayed once Growl is installed and running.

### Growl_PostNotificationWithDictionary

Notifies using a userInfo dictionary suitable for passing to CFDistributedNotificationCenter.

>     void Growl_PostNotificationWithDictionary(
>         CFDictionaryRef userInfo);

##### Parameter Descriptions

> `userInfo`
>   The dictionary to notify with.

##### Discussion

Before Growl 0.6, your application would have posted notifications using CFDistributedNotificationCenter by creating a userInfo dictionary with the notification data. This had the advantage of allowing you to add other data to the dictionary for programs besides Growl that might be listening.
This function allows you to use such dictionaries without being restricted to using CFDistributedNotificationCenter. The keys for this dictionary can be found in GrowlDefines.h.

### Growl_RegisterWithDictionary

Register your application with Growl without setting a delegate.

>     Boolean Growl_RegisterWithDictionary(
>         CFDictionaryRef regDict);

function result
  `false` if registration failed (e.g. if Growl isn't installed).

##### Discussion

When you call this function with a dictionary, GrowlApplicationBridge registers your application using that dictionary. If you pass `NULL`, GrowlApplicationBridge will ask the delegate (if there is one) for a dictionary, and if that doesn't work, it will look in your application's bundle for an auto-discoverable plist. (XXX refer to more information on that)
If you pass a dictionary to this function, it must include the `GROWL_APP_NAME` key, unless a delegate is set.
This function is mainly an alternative to the delegate system introduced with Growl 0.6. Without a delegate, you cannot receive callbacks such as `growlIsReady` (since they are sent to the delegate). You can, however, set a delegate after registering without one.
This function was introduced in Growl.framework 0.7.

### Growl_Reregister

Updates your registration with Growl.

>     void Growl_Reregister(
>         void);

##### Discussion

If your application changes the contents of the GROWL_NOTIFICATIONS_ALL key in the registrationDictionary member of the Growl delegate, or if it changes the value of that member, or if it changes the contents of its auto-discoverable plist, call this function to have Growl update its registration information for your application.
Otherwise, this function does not normally need to be called. If you're using a delegate, your application will be registered when you set the delegate if both the delegate and its registrationDictionary member are non-`NULL`.
This function is now implemented using `Growl_RegisterWithDictionary`.

### Growl_SetDelegate

Replaces the current Growl delegate with a new one, or removes the Growl delegate.

>     Boolean Growl_SetDelegate(
>         struct Growl_Delegate *newDelegate);

##### Parameter Descriptions

> `newDelegate`

function result
  Returns false and does nothing else if a pointer that was passed in is unsatisfactory (because it is non-`NULL`, but at least one required member of it is `NULL`). Otherwise, sets or unsets the delegate and returns true.

##### Discussion

When `newDelegate` is non-`NULL`, sets the delegate to `newDelegate`. When it is `NULL`, the current delegate will be unset, and no delegate will be in place.
It is legal for `newDelegate` to be the current delegate; nothing will happen, and Growl_SetDelegate will return true. It is also legal for it to be `NULL`, as described above; again, it will return true.
If there was a delegate in place before the call, Growl_SetDelegate will call the old delegate's release member if it was non-`NULL`. If `newDelegate` is non-`NULL`, Growl_SetDelegate will call `newDelegate->retain`, and set the delegate to its return value.
If you are using Growl-WithInstaller.framework, and an older version of Growl is installed on the user's system, the user will automatically be prompted to update.
GrowlApplicationBridge currently does not copy this structure, nor does it retain any of the CF objects in the structure (it regards the structure as a container that retains the objects when they are added and releases them when they are removed or the structure is destroyed). Also, GrowlApplicationBridge currently does not modify any member of the structure, except possibly the referenceCount by calling the retain and release members.

### Growl_SetWillRegisterWhenGrowlIsReady

Tells GrowlApplicationBridge to register with Growl when Growl launches (or not).

>     void Growl_SetWillRegisterWhenGrowlIsReady(
>         Boolean flag);

##### Parameter Descriptions

> `flag`
>   `true` if you want GrowlApplicationBridge to register with Growl when next it is ready; `false` if not.

##### Discussion

When Growl has started listening for notifications, it posts a `GROWL_IS_READY` notification on the Distributed Notification Center. GrowlApplicationBridge listens for this notification, using it to perform various tasks (such as calling your delegate's `growlIsReady` callback, if it has one). If this function is called with `true`, one of those tasks will be to reregister with Growl (in the manner of `Growl_Reregister`).
This attribute is automatically set back to `false` (the default) after every `GROWL_IS_READY` notification.

### Growl_WillRegisterWhenGrowlIsReady

Reports whether GrowlApplicationBridge will register with Growl when Growl next launches.

>     Boolean Growl_WillRegisterWhenGrowlIsReady(
>         void);

function result
  `true` if GrowlApplicationBridge will register with Growl when next it posts GROWL_IS_READY; `false` if not.

## Typedefs

### GrowlLaunchCallback

Callback to notify you that Growl is running.

>     typedef void (*GrowlLaunchCallback)(
>         void *context);

##### Parameter Descriptions

> `context`
>   The context pointer passed to Growl_LaunchIfInstalled.

##### Discussion

Growl_LaunchIfInstalled calls this callback function if Growl was already running or if it launched Growl successfully.

## Structs and Unions

### Growl_Delegate

Delegate to supply GrowlApplicationBridge with information and respond to events.

>     struct Growl_Delegate {
>         /* @discussion This should be sizeof(struct Growl_Delegate).
>             */
>         size_t size;
>         /*All of these attributes are optional.
>      *Optional attributes can be NULL; required attributes that
>      * are NULL cause setting the Growl delegate to fail.
>      *XXX - move optional/required status into the discussion for each field
>             */
>         /* This name is used both internally and in the Growl preferences.
>      *
>      * This should remain stable between different versions and incarnations of
>      * your application.
>      * For example, "SurfWriter" is a good app name, whereas "SurfWriter 2.0" and
>      * "SurfWriter Lite" are not.
>      *
>      * This can be <code>NULL</code> if it is provided elsewhere, namely in an
>      * auto-discoverable plist file in your app bundle
>      * (XXX refer to more information on that) or in registrationDictionary.
>             */
>         CFStringRef applicationName;
>         /*
>      * Must contain at least these keys:
>      * GROWL_NOTIFICATIONS_ALL (CFArray):
>      * Contains the names of all notifications your application may post.
>      *
>      * Can also contain these keys:
>      * GROWL_NOTIFICATIONS_DEFAULT (CFArray):
>      * Names of notifications that should be enabled by default.
>      * If omitted, GROWL_NOTIFICATIONS_ALL will be used.
>      * GROWL_APP_NAME (CFString):
>      * Same as the applicationName member of this structure.
>      * If both are present, the applicationName member shall prevail.
>      * If this key is present, you may omit applicationName (set it to <code>NULL</code>).
>      * GROWL_APP_ICON (CFData):
>      * Same as the iconData member of this structure.
>      * If both are present, the iconData member shall prevail.
>      * If this key is present, you may omit iconData (set it to <code>NULL</code>).
>      *
>      * If you change the contents of this dictionary after setting the delegate,
>      * be sure to call Growl_Reregister.
>      *
>      * This can be <code>NULL</code> if you have an auto-discoverable plist file in your app
>      * bundle. (XXX refer to more information on that)
>             */
>         CFDictionaryRef registrationDictionary;
>         /* The data can be in any format supported by NSImage. As of
>      * Mac OS X 10.3, this includes the .icns, TIFF, JPEG, GIF, PNG, PDF, and
>      * PICT formats.
>      *
>      * If this is not supplied, Growl will look up your application's icon by
>      * its application name.
>             */
>         CFDataRef applicationIconData;
>         /* Installer display attributes
>      *
>      * These four attributes are used by the Growl installer, if this framework
>      * supports it.
>      * For any of these being <code>NULL</code>, a localised default will be
>      * supplied.
>             */
>         /* If this is <code>NULL</code>, Growl will use a default,
>      * localized title.
>      *
>      * Only used if you're using Growl-WithInstaller.framework. Otherwise,
>      * this member is ignored.
>             */
>         CFStringRef growlInstallationWindowTitle;
>         /* This information may be as long or short as desired (the
>      * window will be sized to fit it). If Growl is not installed, it will
>      * be displayed to the user as an explanation of what Growl is and what
>      * it can do in your application.
>      * It should probably note that no download is required to install.
>      *
>      * If this is <code>NULL</code>, Growl will use a default, localized
>      * explanation.
>      *
>      * Only used if you're using Growl-WithInstaller.framework. Otherwise,
>      * this member is ignored.
>             */
>         CFStringRef growlInstallationInformation;
>         /* If this is <code>NULL</code>, Growl will use a default,
>      * localized title.
>      *
>      * Only used if you're using Growl-WithInstaller.framework. Otherwise,
>      * this member is ignored.
>             */
>         CFStringRef growlUpdateWindowTitle;
>         /* This information may be as long or short as desired (the
>      * window will be sized to fit it). If an older version of Growl is
>      * installed, it will be displayed to the user as an explanation that an
>      * updated version of Growl is included in your application and
>      * no download is required.
>      *
>      * If this is <code>NULL</code>, Growl will use a default, localized
>      * explanation.
>      *
>      * Only used if you're using Growl-WithInstaller.framework. Otherwise,
>      * this member is ignored.
>             */
>         CFStringRef growlUpdateInformation;
>         /* This member is provided for use by your retain and release
>      * callbacks (see below).
>      *
>      * GrowlApplicationBridge never directly uses this member. Instead, it
>      * calls your retain callback (if non-<code>NULL</code>) and your release
>      * callback (if non-<code>NULL</code>).
>             */
>         unsigned referenceCount;
>         //Functions. Currently all of these are optional (any of them can be NULL).
>         /* When you call Growl_SetDelegate(newDelegate), it will call
>      * oldDelegate->release(oldDelegate), and then it will call
>      * newDelegate->retain(newDelegate), and the return value from retain
>      * is what will be set as the delegate.
>                 NSObject retain]
>      * This member is optional (it can be <code>NULL</code>).
>      * For a delegate allocated with malloc, this member would be
>      * <code>NULL</code>.
>      * @result A delegate to which GrowlApplicationBridge holds a reference.
>             */
>         void *(*retain)(
>             void *);
>         /* When you call Growl_SetDelegate(newDelegate), it will call
>      * oldDelegate->release(oldDelegate), and then it will call
>      * newDelegate->retain(newDelegate), and the return value from retain
>      * is what will be set as the delegate.
>      * (This means that this member works like CFRelease and
>                 NSObject release]
>      * This member is optional (it can be NULL).
>      * For a delegate allocated with malloc, this member might be
>      * <code>free</code>(3).
>             */
>         void (*release)(
>             void *);
>         /* Informs the delegate that Growl (specifically, the GrowlHelperApp) was
>      * launched successfully (or was already running). The application can
>      * take actions with the knowledge that Growl is installed and functional.
>             */
>         void (*growlIsReady)(
>             void);
>         /* Informs the delegate that a Growl notification was clicked. It is only
>      * sent for notifications sent with a non-<code>NULL</code> clickContext,
>      * so if you want to receive a message when a notification is clicked,
>      * clickContext must not be <code>NULL</code> when calling
>      * Growl_PostNotification or
>      * Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext.
>             */
>         void (*growlNotificationWasClicked)(
>             CFPropertyListRef clickContext);
>         /* Informs the delegate that a Growl notification timed out. It is only
>      * sent for notifications sent with a non-<code>NULL</code> clickContext,
>      * so if you want to receive a message when a notification is clicked,
>      * clickContext must not be <code>NULL</code> when calling
>      * Growl_PostNotification or
>      * Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext.
>             */
>         void (*growlNotificationTimedOut)(
>             CFPropertyListRef clickContext);
>     };

##### Field Descriptions

> `size`
>   The size of the delegate structure.
> `applicationName`
>   The name of your application.
> `registrationDictionary`
>   A dictionary describing your application and the notifications it can send out.
> `applicationIconData`
>   Your application's icon.
> `growlInstallationWindowTitle`
>   The title of the installation window.
> `growlInstallationInformation`
>   Text to display in the installation window.
> `growlUpdateWindowTitle`
>   The title of the update window.
> `growlUpdateInformation`
>   Text to display in the update window.
> `referenceCount`
>   A count of owners of the delegate.
> `retain`
>   Called when GrowlApplicationBridge receives this delegate.
> `release`
>   Called when GrowlApplicationBridge no longer needs this delegate.
> `growlIsReady`
>   Called when GrowlHelperApp is listening for notifications.
> `growlNotificationWasClicked`
>   Called when a Growl notification is clicked.
> `growlNotificationTimedOut`
>   Called when a Growl notification timed out.

##### Discussion

The Growl delegate provides your interface to GrowlApplicationBridge. When GrowlApplicationBridge needs information about your application, it looks for it in the delegate; when Growl or the user does something that you might be interested in, GrowlApplicationBridge looks for a callback in the delegate and calls it if present (meaning, if it is not `NULL`). XXX on all of that

### Growl_Notification

Structure describing a Growl notification.

>     struct Growl_Notification {
>         /* This should be sizeof(struct Growl_Notification).
>             */
>         size_t size;
>         /* The notification name distinguishes one type of
>      * notification from another. The name should be human-readable, as it
>      * will be displayed in the Growl preference pane.
>      *
>      * The name is used in the GROWL_NOTIFICATIONS_ALL and
>      * GROWL_NOTIFICATIONS_DEFAULT arrays in the registration dictionary, and
>      * in this member of the Growl_Notification structure.
>             */
>         CFStringRef name;
>         /* A notification's title describes the notification briefly.
>      * It should be easy to read quickly by the user.
>             */
>         CFStringRef title;
>         /* The description supplements the title with more
>      * information. It is usually longer and sometimes involves a list of
>      * subjects. For example, for a 'Download complete' notification, the
>      * description might have one filename per line. GrowlMail in Growl 0.6
>      * uses a description of '%d new mail(s)' (formatted with the number of
>      * messages).
>             */
>         CFStringRef description;
>         /* The notification icon usually indicates either what
>      * happened (it may have the same icon as e.g. a toolbar item that
>      * started the process that led to the notification), or what it happened
>      * to (e.g. a document icon).
>      *
>      * The icon data is optional, so it can be <code>NULL</code>. In that
>      * case, the application icon is used alone. Not all displays support
>      * icons.
>      *
>      * The data can be in any format supported by NSImage. As of Mac OS X
>      * 10.3, this includes the .icns, TIFF, JPEG, GIF, PNG, PDF, and PICT form
>      * ats.
>             */
>         CFDataRef iconData;
>         /* Priority is new in Growl 0.6, and is represented as a
>      * signed integer from -2 to +2. 0 is Normal priority, -2 is Very Low
>      * priority, and +2 is Very High priority.
>      *
>      * Not all displays support priority. If you do not wish to assign a
>      * priority to your notification, assign 0.
>             */
>         signed int priority;
>         /* These bits are not used in Growl 0.6. Set them to 0.
>             */
>         unsigned reserved: 31;
>         /* When the sticky bit is clear, in most displays,
>      * notifications disappear after a certain amount of time. Sticky
>      * notifications, however, remain on-screen until the user dismisses them
>      * explicitly, usually by clicking them.
>      *
>      * Sticky notifications were introduced in Growl 0.6. Most notifications
>      * should not be sticky. Not all displays support sticky notifications,
>      * and the user may choose in Growl's preference pane to force the
>      * notification to be sticky or non-sticky, in which case the sticky bit
>      * in the notification will be ignored.
>             */
>         unsigned isSticky: 1;
>         /* If this is not <code>NULL</code>, and your click callback
>      * is not <code>NULL</code> either, this will be passed to the callback
>      * when your notification is clicked by the user.
>      *
>      * Click feedback was introduced in Growl 0.6, and it is optional. Not
>      * all displays support click feedback.
>             */
>         CFPropertyListRef clickContext;
>         /* If this is not <code>NULL</code>, it will be called instead
>      * of the Growl delegate's click callback when clickContext is
>      * non-<code>NULL</code> and the notification is clicked on by the user.
>      *
>      * Click feedback was introduced in Growl 0.6, and it is optional. Not
>      * all displays support click feedback.
>      *
>      * The per-notification click callback is not yet supported as of Growl
>      * 0.7.
>             */
>         void (*clickCallback)(
>             CFPropertyListRef clickContext);
>     };

##### Field Descriptions

> `size`
>   The size of the notification structure.
> `name`
>   Identifies the notification.
> `title`
>   Short synopsis of the notification.
> `description`
>   Additional text.
> `iconData`
>   An icon for the notification.
> `priority`
>   An indicator of the notification's importance.
> `reserved`
>   Bits reserved for future usage.
> `isSticky`
>   Requests that a notification stay on-screen until dismissed explicitly.
> `clickContext`
>   An identifier to be passed to your click callback when a notification is clicked.
> `clickCallback`
>   A callback to call when the notification is clicked.

##### Discussion

XXX

## #defines

### GROWL_PREFPANE_BUNDLE_IDENTIFIER

The CFBundleIdentifier of the Growl preference pane bundle.

>     #define GROWL_PREFPANE_BUNDLE_IDENTIFIER CFSTR(
>         "com.growl.prefpanel")

##### Discussion

GrowlApplicationBridge uses this to determine whether Growl is currently installed, by searching for the Growl preference pane. Your application probably does not need to use this macro itself.

### InitGrowlDelegate

Callable macro. Initializes a Growl delegate structure to defaults.

>     #define InitGrowlDelegate(
>         delegate) \ do {
>         \ if (
>         delegate) {
>         \ (
>         delegate)->size = sizeof(
>         struct Growl_Delegate); \ (
>         delegate)->applicationName = NULL; \ (
>         delegate)->registrationDictionary = NULL; \ (
>         delegate)->applicationIconData = NULL; \ (
>         delegate)->growlInstallationWindowTitle = NULL; \ (
>         delegate)->growlInstallationInformation = NULL; \ (
>         delegate)->growlUpdateWindowTitle = NULL; \ (
>         delegate)->growlUpdateInformation = NULL; \ (
>         delegate)->referenceCount = 1U; \ (
>         delegate)->retain = NULL; \ (
>         delegate)->release = NULL; \ (
>         delegate)->growlIsReady = NULL; \ (
>         delegate)->growlNotificationWasClicked = NULL; \ (
>         delegate)->growlNotificationTimedOut = NULL; \
>     } \
>     } while(
>         0)

##### Discussion

Call with a pointer to a struct Growl_Delegate. All of the members of the structure will be set to 0 or `NULL`, except for size (which will be set to `sizeof(struct Growl_Delegate)`) and referenceCount (which will be set to 1).

### InitGrowlNotification

Callable macro. Initializes a Growl notification structure to defaults.

>     #define InitGrowlNotification(
>         notification) \ do {
>         \ if (
>         notification) {
>         \ (
>         notification)->size = sizeof(
>         struct Growl_Notification); \ (
>         notification)->name = NULL; \ (
>         notification)->title = NULL; \ (
>         notification)->description = NULL; \ (
>         notification)->iconData = NULL; \ (
>         notification)->priority = 0; \ (
>         notification)->reserved = 0U; \ (
>         notification)->isSticky = false; \ (
>         notification)->clickContext = NULL; \
>     } \
>     } while(
>         0)

##### Discussion

Call with a pointer to a struct Growl_Notification. All of the members of the structure will be set to 0 or `NULL`, except for size (which will be set to `sizeof(struct Growl_Notification)`).

© The Growl Project (Last Updated May 14, 2005)