# GrowlDefinesInternal.h

## Abstract

Defines internal Growl macros and types.

## Discussion

These constants are used both by GrowlHelperApp and by plug-ins.
Notification keys (used in GrowlHelperApp, in GrowlApplicationBridge, and by applications that don't use GrowlApplicationBridge) are defined in GrowlDefines.h.

## Structs and Unions

### GrowlNetworkNotificationFlags server sends a packet in this format.

Various flags.

>     struct GrowlNetworkNotification {
>         struct GrowlNetworkPacket common;
>         struct GrowlNetworkNotificationFlags {
>             unsigned reserved: 12;
>             signed priority: 3;
>             unsigned sticky: 1;
>             }  flags; //size = 16 (12 + 3 + 1)
>         /* In addition to being unsigned, the notification name length
>      * is in network byte order.
>             */
>         unsigned short nameLen;
>         /* @discussion In addition to being unsigned, the title length is in
>      * network byte order.
>             */
>         unsigned short titleLen;
>         /* In addition to being unsigned, the description length is in
>      * network byte order.
>             */
>         unsigned short descriptionLen;
>         /* In addition to being unsigned, the application name length
>      * is in network byte order.
>             */
>         unsigned short appNameLen;
>         /* The variable-sized data of a notification is:
>      * - Notification name, in UTF-8 encoding, for nameLen bytes.
>      * - Title, in UTF-8 encoding, for titleLen bytes.
>      * - Description, in UTF-8 encoding, for descriptionLen bytes.
>      * - Application name, in UTF-8 encoding, for appNameLen bytes.
>      * - The MD5/SHA256 checksum of all the data preceding the checksum.
>             */
>         unsigned char data[];
>     };

##### Field Descriptions

> `common`
>   The Growl packet header.
> `flags`
>   The priority number and the sticky bit.
> `nameLen`
>   The length of the notification name.
> `titleLen`
>   The length of the notification title.
> `descriptionLen`
>   The length of the notification description.
> `appNameLen`
>   The length of the application name.
> `data`
>   Variable-sized data.
> `reserved`
>   reserved for future use.
> `priority`
>   the priority as a signed 3-bit integer from -2 to +2.
> `sticky`
>   the sticky flag.

##### Discussion

This 16-bit packed structure contains the priority as a signed 3-bit integer from -2 to +2, and the sticky flag as a single bit. The high 12 bits of the structure are reserved for future use.

### GrowlNetworkPacket

This struct is a header common to all incoming Growl network packets which identifies the type and version of the packet.

>     struct GrowlNetworkPacket {
>         unsigned char version;
>         unsigned char type;
>     };

### GrowlNetworkRegistration

The format of a registration packet.

>     struct GrowlNetworkRegistration {
>         struct GrowlNetworkPacket common;
>         /* This name is used both internally and in the Growl
>      * preferences.
>      *
>      * The application name 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.
>      *
>      * In addition to being unsigned, the application name length is in
>      * network byte order.
>             */
>         unsigned short appNameLen;
>         /* These names are used both internally and in the Growl
>      * preferences. For this reason, they should be human-readable.
>             */
>         unsigned char numAllNotifications;
>         unsigned char numDefaultNotifications;
>         /* The variable-sized data of a registration is:
>      * - The application name, in UTF-8 encoding, for appNameLen bytes.
>      * - The list of all notification names.
>      * - The list of default notifications, as 8-bit unsigned indices into the list of all notifications.
>      * - The MD5/SHA256 checksum of all the data preceding the checksum.
>      *
>      * Each notification name is encoded as:
>      * - Length: two bytes, unsigned, network byte order.
>      * - Name: As many bytes of UTF-8-encoded text as the length says.
>      * And there are numAllNotifications of these.
>             */
>         unsigned char data[];
>     };

##### Field Descriptions

> `common`
>   The Growl packet header.
> `appNameLen`
>   The name of the application that is registering.
> `numAllNotifications`
>   The number of notifications in the list.
> `numDefaultNotifications`
>   The number of notifications in the list that are enabled by default.
> `data`
>   Variable-sized data.

##### Discussion

A Growl client that wants to register with a Growl server sends a packet in this format.

## #defines

### GROWL_APP_LOCATION

The location of this application.

>     #define GROWL_APP_LOCATION XSTR(
>         "AppLocation")

##### Discussion

Contains either the POSIX path to the application, or a file-data dictionary (as used by the Dock). contains the file's alias record and its pathname.

### GROWL_PROTOCOL_VERSION

The current version of the Growl network-notifications protocol (without encryption).

>     #define GROWL_PROTOCOL_VERSION 1

### GROWL_PROTOCOL_VERSION_AES128

The current version of the Growl network-notifications protocol (with AES-128 encryption).

>     #define GROWL_PROTOCOL_VERSION_AES128 2

### GROWL_SCREENSHOT_MODE

Preference and notification key controlling whether to save a screenshot of the notification.

>     #define GROWL_SCREENSHOT_MODE XSTR(
>         "ScreenshotMode")

##### Discussion

This is for GHA's private usage. If your application puts this key into a notification dictionary, GHA will clobber it. This key is only allowed in the notification dictionaries GHA passes to displays.
If this key contains an object whose boolValue is not NO, the display is asked to save a screenshot of the notification to ~/Library/Application\ Support/Growl/Screenshots.

### GROWL_TCP_PORT

The TCP listen port for Growl notification servers.

>     #define GROWL_TCP_PORT 23052

### GROWL_TYPE_NOTIFICATION

The packet type of notification packets with MD5 authentication.

>     #define GROWL_TYPE_NOTIFICATION 1

### GROWL_TYPE_NOTIFICATION_NOAUTH

The packet type of notification packets without authentication.

>     #define GROWL_TYPE_NOTIFICATION_NOAUTH 5

### GROWL_TYPE_NOTIFICATION_SHA256

The packet type of notification packets with SHA-256 authentication.

>     #define GROWL_TYPE_NOTIFICATION_SHA256 3

### GROWL_TYPE_REGISTRATION

The packet type of registration packets with MD5 authentication.

>     #define GROWL_TYPE_REGISTRATION 0

### GROWL_TYPE_REGISTRATION_NOAUTH

The packet type of registration packets without authentication.

>     #define GROWL_TYPE_REGISTRATION_NOAUTH 4

### GROWL_TYPE_REGISTRATION_SHA256

The packet type of registration packets with SHA-256 authentication.

>     #define GROWL_TYPE_REGISTRATION_SHA256 2

### GROWL_UDP_PORT

The UDP listen port for Growl notification servers.

>     #define GROWL_UDP_PORT 9887

### GrowlEnabledKey

Preference key controlling whether Growl is enabled.

>     #define GrowlEnabledKey XSTR(
>         "GrowlEnabled")

##### Discussion

If this is false, then when GrowlHelperApp is launched to open a Growl registration dictionary file, GrowlHelperApp will quit when it has finished processing the file instead of listening for notifications.

### READ_GROWL_PREF_BOOL

Reads the given Boolean from the plug-in's preferences.

>     #define READ_GROWL_PREF_BOOL(
>         key, domain, result) do {
>         \ CFBooleanRef boolValue = NULL; \ READ_GROWL_PREF_VALUE(
>         key, domain, CFBooleanRef, &boolValue); \ if (
>         boolValue) {
>         \ *result = CFBooleanGetValue(
>         boolValue); \ CFRelease(
>         boolValue); \ }
>     } while(
>         0)

##### Parameter Descriptions

> `key`
>   The preference key to read the Boolean from.
> `domain`
>   The bundle ID of the plug-in.
> `result`
>   A pointer to a Boolean type. Left unchanged if the value doesn't exist.

##### Discussion

This is a wrapper around READ_GROWL_PREF_VALUE() intended for use with Booleans.

### READ_GROWL_PREF_FLOAT

Reads the given float from the plug-in's preferences.

>     #define READ_GROWL_PREF_FLOAT(
>         key, domain, result) do {
>         \ CFNumberRef floatValue = NULL; \ READ_GROWL_PREF_VALUE(
>         key, domain, CFNumberRef, &floatValue); \ if (
>         floatValue) {
>         \ CFNumberGetValue(
>         floatValue, kCFNumberFloatType, result); \ CFRelease(
>         floatValue); \ }
>     } while(
>         0)

##### Parameter Descriptions

> `key`
>   The preference key to read the float from.
> `domain`
>   The bundle ID of the plug-in.
> `result`
>   A pointer to a float. Leaves unchanged if the value doesn't exist.

##### Discussion

This is a wrapper around READ_GROWL_PREF_VALUE() intended for use with floats.

### READ_GROWL_PREF_INT

Reads the given integer from the plug-in's preferences.

>     #define READ_GROWL_PREF_INT(
>         key, domain, result) do {
>         \ CFNumberRef intValue = NULL; \ READ_GROWL_PREF_VALUE(
>         key, domain, CFNumberRef, &intValue); \ if (
>         intValue) {
>         \ CFNumberGetValue(
>         intValue, kCFNumberIntType, result); \ CFRelease(
>         intValue); \ }
>     } while(
>         0)

##### Parameter Descriptions

> `key`
>   The preference key to read the integer from.
> `domain`
>   The bundle ID of the plug-in.
> `result`
>   A pointer to an integer. Leaves unchanged if the value doesn't exist.

##### Discussion

This is a wrapper around READ_GROWL_PREF_VALUE() intended for use with integers.

### READ_GROWL_PREF_VALUE

Reads the given pref value from the plug-in's preferences.

>     #define READ_GROWL_PREF_VALUE(
>         key, domain, type, result) do {
>         \ CFDictionaryRef prefs = (
>         CFDictionaryRef)CFPreferencesCopyAppValue((
>         CFStringRef)domain, \ CFSTR(
>         "com.Growl.GrowlHelperApp")); \ if (
>         prefs) {
>         \ if (
>         CFDictionaryContainsKey(
>         prefs, key)) {
>         \ *result = (
>         type)CFDictionaryGetValue(
>         prefs, key); \ CFRetain(
>         *result); \
>     } \ CFRelease(
>         prefs);
>     } \
>     } while(
>         0)

##### Parameter Descriptions

> `key`
>   The preference key to read the value of.
> `domain`
>   The bundle ID of the plug-in.
> `type`
>   The type of the result expected.
> `result`
>   A pointer to an id. Set to the value if exists, left unchanged if not.
>   If the value is set, you are responsible for releasing it.

##### Discussion

This macro is intended for use by plug-ins. It reads the value for the given key from the plug-in's preferences (which are stored in a dictionary inside of GrowlHelperApp's prefs).

### SYNCHRONIZE_GROWL_PREFS

Synchronizes Growl prefs so they're up-to-date.

>     #define SYNCHRONIZE_GROWL_PREFS(
>         ) CFPreferencesAppSynchronize(
>         CFSTR(
>         "com.Growl.GrowlHelperApp"))

##### Discussion

This macro is intended for use by GrowlHelperApp and by plug-ins (when the prefpane is selected).

### UPDATE_GROWL_PREFS

Tells GrowlHelperApp to update its prefs.

>     #define UPDATE_GROWL_PREFS(
>         ) do {
>         \ SYNCHRONIZE_GROWL_PREFS(
>         ); \ NSNumber *pid = [[NSNumber alloc] initWithInt:[[NSProcessInfo processInfo] processIdentifier]];
>             \ NSDictionary *userInfo = [[NSDictionary alloc] initWithObjectsAndKeys:\ pid, @"pid",\ nil];\ [pid release];\ [[NSDistributedNotificationCenter defaultCenter]\ postNotificationName:@"GrowlPreferencesChanged" object:@"GrowlUserDefaults" userInfo:userInfo];
>             \ [userInfo release];\
>     } while(
>         0)

##### Discussion

This macro is intended for use by plug-ins. It sends a notification to tell GrowlHelperApp to update its preferences.

### WRITE_GROWL_PREF_BOOL

Writes the given Boolean to the plug-in's preferences.

>     #define WRITE_GROWL_PREF_BOOL(
>         key, value, domain) do {
>         \ CFBooleanRef boolValue; \ if (
>         value) {
>         \ boolValue = kCFBooleanTrue; \
>     } else {
>         \ boolValue = kCFBooleanFalse; \
>     }\ WRITE_GROWL_PREF_VALUE(
>         key, boolValue, domain);
>     } while(
>         0)

##### Parameter Descriptions

> `key`
>   The preference key to write the Boolean for.
> `value`
>   The Boolean value to write to the preferences.
> `domain`
>   The bundle ID of the plug-in.

##### Discussion

This is a wrapper around WRITE_GROWL_PREF_VALUE() intended for use with Booleans.

### WRITE_GROWL_PREF_FLOAT

Writes the given float to the plug-in's preferences.

>     #define WRITE_GROWL_PREF_FLOAT(
>         key, value, domain) do {
>         \ CFNumberRef floatValue = CFNumberCreate(
>         NULL, kCFNumberFloatType, &value); \ WRITE_GROWL_PREF_VALUE(
>         key, floatValue, domain); \ CFRelease(
>         floatValue);
>     } while(
>         0)

##### Parameter Descriptions

> `key`
>   The preference key to write the float for.
> `value`
>   The float value to write to the preferences.
> `domain`
>   The bundle ID of the plug-in.

##### Discussion

This is a wrapper around WRITE_GROWL_PREF_VALUE() intended for use with floats.

### WRITE_GROWL_PREF_INT

Writes the given integer to the plug-in's preferences.

>     #define WRITE_GROWL_PREF_INT(
>         key, value, domain) do {
>         \ CFNumberRef intValue = CFNumberCreate(
>         NULL, kCFNumberIntType, &value); \ WRITE_GROWL_PREF_VALUE(
>         key, intValue, domain); \ CFRelease(
>         intValue);
>     } while(
>         0)

##### Parameter Descriptions

> `key`
>   The preference key to write the integer for.
> `value`
>   The integer value to write to the preferences.
> `domain`
>   The bundle ID of the plug-in.

##### Discussion

This is a wrapper around WRITE_GROWL_PREF_VALUE() intended for use with integers.

### WRITE_GROWL_PREF_VALUE

Writes the given pref value to the plug-in's preferences.

>     #define WRITE_GROWL_PREF_VALUE(
>         key, value, domain) do {
>         \ CFDictionaryRef staticPrefs = (
>         CFDictionaryRef)CFPreferencesCopyAppValue((
>         CFStringRef)domain, \ CFSTR(
>         "com.Growl.GrowlHelperApp")); \ CFMutableDictionaryRef prefs; \ if (
>         staticPrefs == NULL) {
>         \ prefs = CFDictionaryCreateMutable(
>         NULL, 0, NULL, NULL); \
>     } else {
>         \ prefs = CFDictionaryCreateMutableCopy(
>         NULL, 0, staticPrefs); \ CFRelease(
>         staticPrefs); \
>     }\ CFDictionarySetValue(
>         prefs, key, value); \ CFPreferencesSetAppValue((
>         CFStringRef)domain, prefs, CFSTR(
>         "com.Growl.GrowlHelperApp")); \ CFRelease(
>         prefs);
>     } while(
>         0)

##### Parameter Descriptions

> `key`
>   The preference key to write the value of.
> `value`
>   The value to write to the preferences. It should be either a CoreFoundation type or toll-free bridged with one.
> `domain`
>   The bundle ID of the plug-in.

##### Discussion

This macro is intended for use by plug-ins. It writes the given value to the plug-in's preferences.

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