SVN_SILENT made messages (.desktop file)
[amarok:history.git] / src / mac / Growl-WithInstaller.framework / Versions / A / Headers / GrowlApplicationBridge-Carbon.h
1 //
2 //  GrowlApplicationBridge-Carbon.h
3 //  Growl
4 //
5 //  Created by Mac-arena the Bored Zo on Wed Jun 18 2004.
6 //  Based on GrowlApplicationBridge.h by Evan Schoenberg.
7 //  This source code is in the public domain. You may freely link it into any
8 //    program.
9 //
10
11 #ifndef _GROWLAPPLICATIONBRIDGE_CARBON_H_
12 #define _GROWLAPPLICATIONBRIDGE_CARBON_H_
13
14 #include <sys/cdefs.h>
15 #include <Carbon/Carbon.h>
16
17 #ifndef GROWL_EXPORT
18 #define GROWL_EXPORT __attribute__((visibility("default")))
19 #endif
20
21 /*!     @header GrowlApplicationBridge-Carbon.h
22  *      @abstract       Declares an API that Carbon applications can use to interact with Growl.
23  *      @discussion     GrowlApplicationBridge uses a delegate to provide information //XXX
24  *       to Growl (such as your application's name and what notifications it may
25  *       post) and to provide information to your application (such as that Growl
26  *       is listening for notifications or that a notification has been clicked).
27  *
28  *       You can set the Growldelegate with Growl_SetDelegate and find out the
29  *       current delegate with Growl_GetDelegate. See struct Growl_Delegate for more
30  *       information about the delegate.
31  */
32
33 __BEGIN_DECLS
34
35 /*!     @struct Growl_Delegate
36  *      @abstract Delegate to supply GrowlApplicationBridge with information and respond to events.
37  *      @discussion The Growl delegate provides your interface to
38  *       GrowlApplicationBridge. When GrowlApplicationBridge needs information about
39  *       your application, it looks for it in the delegate; when Growl or the user
40  *       does something that you might be interested in, GrowlApplicationBridge
41  *       looks for a callback in the delegate and calls it if present
42  *       (meaning, if it is not <code>NULL</code>).
43  *      XXX on all of that
44  *  @field size The size of the delegate structure.
45  *      @field applicationName The name of your application.
46  *      @field registrationDictionary A dictionary describing your application and the notifications it can send out.
47  *      @field applicationIconData Your application's icon.
48  *      @field growlInstallationWindowTitle The title of the installation window.
49  *      @field growlInstallationInformation Text to display in the installation window.
50  *      @field growlUpdateWindowTitle The title of the update window.
51  *      @field growlUpdateInformation Text to display in the update window.
52  *      @field referenceCount A count of owners of the delegate.
53  *      @field retain Called when GrowlApplicationBridge receives this delegate.
54  *      @field release Called when GrowlApplicationBridge no longer needs this delegate.
55  *      @field growlIsReady Called when GrowlHelperApp is listening for notifications.
56  *      @field growlNotificationWasClicked Called when a Growl notification is clicked.
57  *  @field growlNotificationTimedOut Called when a Growl notification timed out.
58  */
59 struct Growl_Delegate {
60         /*      @discussion This should be sizeof(struct Growl_Delegate).
61          */
62         size_t size;
63
64         /*All of these attributes are optional.
65          *Optional attributes can be NULL; required attributes that
66          *       are NULL cause setting the Growl delegate to fail.
67          *XXX - move optional/required status into the discussion for each field
68          */
69
70         /* This name is used both internally and in the Growl preferences.
71          *
72          *       This should remain stable between different versions and incarnations of
73          *       your application.
74          *       For example, "SurfWriter" is a good app name, whereas "SurfWriter 2.0" and
75          *       "SurfWriter Lite" are not.
76          *
77          * This can be <code>NULL</code> if it is provided elsewhere, namely in an
78          *       auto-discoverable plist file in your app bundle
79          *       (XXX refer to more information on that) or in registrationDictionary.
80          */
81         CFStringRef applicationName;
82
83         /*
84          * Must contain at least these keys:
85          *      GROWL_NOTIFICATIONS_ALL (CFArray):
86          *              Contains the names of all notifications your application may post.
87          *
88          * Can also contain these keys:
89          *      GROWL_NOTIFICATIONS_DEFAULT (CFArray):
90          *              Names of notifications that should be enabled by default.
91          *              If omitted, GROWL_NOTIFICATIONS_ALL will be used.
92          *      GROWL_APP_NAME (CFString):
93          *              Same as the applicationName member of this structure.
94          *              If both are present, the applicationName member shall prevail.
95          *              If this key is present, you may omit applicationName (set it to <code>NULL</code>).
96          *      GROWL_APP_ICON (CFData):
97          *              Same as the iconData member of this structure.
98          *              If both are present, the iconData member shall prevail.
99          *              If this key is present, you may omit iconData (set it to <code>NULL</code>).
100          *
101          * If you change the contents of this dictionary after setting the delegate,
102          *      be sure to call Growl_Reregister.
103          *
104          * This can be <code>NULL</code> if you have an auto-discoverable plist file in your app
105          *       bundle. (XXX refer to more information on that)
106          */
107         CFDictionaryRef registrationDictionary;
108
109         /* The data can be in any format supported by NSImage. As of
110          *       Mac OS X 10.3, this includes the .icns, TIFF, JPEG, GIF, PNG, PDF, and
111          *       PICT formats.
112          *
113          *       If this is not supplied, Growl will look up your application's icon by
114          *       its application name.
115          */
116         CFDataRef applicationIconData;
117
118         /* Installer display attributes
119          *
120          * These four attributes are used by the Growl installer, if this framework
121          *      supports it.
122          * For any of these being <code>NULL</code>, a localised default will be
123          *      supplied.
124          */
125
126         /*      If this is <code>NULL</code>, Growl will use a default,
127          *       localized title.
128          *
129          *       Only used if you're using Growl-WithInstaller.framework. Otherwise,
130          *       this member is ignored.
131          */
132         CFStringRef growlInstallationWindowTitle;
133         /*      This information may be as long or short as desired (the
134          *       window will be sized to fit it).  If Growl is not installed, it will
135          *       be displayed to the user as an explanation of what Growl is and what
136          *       it can do in your application.
137          *       It should probably note that no download is required to install.
138          *
139          *       If this is <code>NULL</code>, Growl will use a default, localized
140          *       explanation.
141          *
142          *       Only used if you're using Growl-WithInstaller.framework. Otherwise,
143          *       this member is ignored.
144          */
145         CFStringRef growlInstallationInformation;
146         /*      If this is <code>NULL</code>, Growl will use a default,
147          *       localized title.
148          *
149          *       Only used if you're using Growl-WithInstaller.framework. Otherwise,
150          *       this member is ignored.
151          */
152         CFStringRef growlUpdateWindowTitle;
153         /*      This information may be as long or short as desired (the
154          *       window will be sized to fit it).  If an older version of Growl is
155          *       installed, it will be displayed to the user as an explanation that an
156          *       updated version of Growl is included in your application and
157          *       no download is required.
158          *
159          *       If this is <code>NULL</code>, Growl will use a default, localized
160          *       explanation.
161          *
162          *       Only used if you're using Growl-WithInstaller.framework. Otherwise,
163          *       this member is ignored.
164          */
165         CFStringRef growlUpdateInformation;
166
167         /*      This member is provided for use by your retain and release
168          *       callbacks (see below).
169          *
170          *       GrowlApplicationBridge never directly uses this member. Instead, it
171          *       calls your retain callback (if non-<code>NULL</code>) and your release
172          *       callback (if non-<code>NULL</code>).
173          */
174         unsigned referenceCount;
175
176         //Functions. Currently all of these are optional (any of them can be NULL).
177
178         /*      When you call Growl_SetDelegate(newDelegate), it will call
179          *       oldDelegate->release(oldDelegate), and then it will call
180          *       newDelegate->retain(newDelegate), and the return value from retain
181          *       is what will be set as the delegate.
182          *       (This means that this member works like CFRetain and -[NSObject retain].)
183          *       This member is optional (it can be <code>NULL</code>).
184          *       For a delegate allocated with malloc, this member would be
185          *       <code>NULL</code>.
186          *      @result A delegate to which GrowlApplicationBridge holds a reference.
187          */
188         void *(*retain)(void *);
189         /*      When you call Growl_SetDelegate(newDelegate), it will call
190          *       oldDelegate->release(oldDelegate), and then it will call
191          *       newDelegate->retain(newDelegate), and the return value from retain
192          *       is what will be set as the delegate.
193          *       (This means that this member works like CFRelease and
194          *        -[NSObject release].)
195          *       This member is optional (it can be NULL).
196          *       For a delegate allocated with malloc, this member might be
197          *       <code>free</code>(3).
198          */
199         void (*release)(void *);
200
201         /*      Informs the delegate that Growl (specifically, the GrowlHelperApp) was
202          *       launched successfully (or was already running). The application can
203          *       take actions with the knowledge that Growl is installed and functional.
204          */
205         void (*growlIsReady)(void);
206
207         /*      Informs the delegate that a Growl notification was clicked. It is only
208          *       sent for notifications sent with a non-<code>NULL</code> clickContext,
209          *       so if you want to receive a message when a notification is clicked,
210          *       clickContext must not be <code>NULL</code> when calling
211          *       Growl_PostNotification or
212          *       Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext.
213          */
214         void (*growlNotificationWasClicked)(CFPropertyListRef clickContext);
215
216         /*      Informs the delegate that a Growl notification timed out. It is only
217          *       sent for notifications sent with a non-<code>NULL</code> clickContext,
218          *       so if you want to receive a message when a notification is clicked,
219          *       clickContext must not be <code>NULL</code> when calling
220          *       Growl_PostNotification or
221          *       Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext.
222          */
223         void (*growlNotificationTimedOut)(CFPropertyListRef clickContext);
224 };
225
226 /*!     @struct Growl_Notification
227  *      @abstract Structure describing a Growl notification.
228  *      @discussion XXX
229  *      @field size The size of the notification structure.
230  *      @field name Identifies the notification.
231  *      @field title Short synopsis of the notification.
232  *  @field description Additional text.
233  *      @field iconData An icon for the notification.
234  *      @field priority An indicator of the notification's importance.
235  *      @field reserved Bits reserved for future usage.
236  *      @field isSticky Requests that a notification stay on-screen until dismissed explicitly.
237  *      @field clickContext An identifier to be passed to your click callback when a notification is clicked.
238  *      @field clickCallback A callback to call when the notification is clicked.
239  */
240 struct Growl_Notification {
241         /*      This should be sizeof(struct Growl_Notification).
242          */
243         size_t size;
244
245         /*      The notification name distinguishes one type of
246          *       notification from another. The name should be human-readable, as it
247          *       will be displayed in the Growl preference pane.
248          *
249          *       The name is used in the GROWL_NOTIFICATIONS_ALL and
250          *       GROWL_NOTIFICATIONS_DEFAULT arrays in the registration dictionary, and
251          *       in this member of the Growl_Notification structure.
252          */
253         CFStringRef name;
254
255         /*      A notification's title describes the notification briefly.
256          *       It should be easy to read quickly by the user.
257          */
258         CFStringRef title;
259
260         /*      The description supplements the title with more
261          *       information. It is usually longer and sometimes involves a list of
262          *       subjects. For example, for a 'Download complete' notification, the
263          *       description might have one filename per line. GrowlMail in Growl 0.6
264          *       uses a description of '%d new mail(s)' (formatted with the number of
265          *       messages).
266          */
267         CFStringRef description;
268
269         /*      The notification icon usually indicates either what
270          *       happened (it may have the same icon as e.g. a toolbar item that
271          *       started the process that led to the notification), or what it happened
272          *       to (e.g. a document icon).
273          *
274          *       The icon data is optional, so it can be <code>NULL</code>. In that
275          *       case, the application icon is used alone. Not all displays support
276          *       icons.
277          *
278          *       The data can be in any format supported by NSImage. As of Mac OS X
279          *       10.3, this includes the .icns, TIFF, JPEG, GIF, PNG, PDF, and PICT form
280          *       ats.
281          */
282         CFDataRef iconData;
283
284         /*      Priority is new in Growl 0.6, and is represented as a
285          *       signed integer from -2 to +2. 0 is Normal priority, -2 is Very Low
286          *       priority, and +2 is Very High priority.
287          *
288          *       Not all displays support priority. If you do not wish to assign a
289          *       priority to your notification, assign 0.
290          */
291         signed int priority;
292
293         /*      These bits are not used in Growl 0.6. Set them to 0.
294          */
295         unsigned reserved: 31;
296
297         /*      When the sticky bit is clear, in most displays,
298          *       notifications disappear after a certain amount of time. Sticky
299          *       notifications, however, remain on-screen until the user dismisses them
300          *       explicitly, usually by clicking them.
301          *
302          *       Sticky notifications were introduced in Growl 0.6. Most notifications
303          *       should not be sticky. Not all displays support sticky notifications,
304          *       and the user may choose in Growl's preference pane to force the
305          *       notification to be sticky or non-sticky, in which case the sticky bit
306          *       in the notification will be ignored.
307          */
308         unsigned isSticky: 1;
309
310         /*      If this is not <code>NULL</code>, and your click callback
311          *       is not <code>NULL</code> either, this will be passed to the callback
312          *       when your notification is clicked by the user.
313          *
314          *       Click feedback was introduced in Growl 0.6, and it is optional. Not
315          *       all displays support click feedback.
316          */
317         CFPropertyListRef clickContext;
318
319         /*      If this is not <code>NULL</code>, it will be called instead
320          *       of the Growl delegate's click callback when clickContext is
321          *       non-<code>NULL</code> and the notification is clicked on by the user.
322          *
323          *       Click feedback was introduced in Growl 0.6, and it is optional. Not
324          *       all displays support click feedback.
325          *
326          *       The per-notification click callback is not yet supported as of Growl
327          *       0.7.
328          */
329         void (*clickCallback)(CFPropertyListRef clickContext);
330
331         CFStringRef identifier;
332 };
333
334 #pragma mark -
335 #pragma mark Easy initialisers
336
337 /*!     @defined        InitGrowlDelegate
338  *      @abstract       Callable macro. Initializes a Growl delegate structure to defaults.
339  *      @discussion     Call with a pointer to a struct Growl_Delegate. All of the
340  *       members of the structure will be set to 0 or <code>NULL</code>, except for
341  *       size (which will be set to <code>sizeof(struct Growl_Delegate)</code>) and
342  *       referenceCount (which will be set to 1).
343  */
344 #define InitGrowlDelegate(delegate) \
345         do { \
346                 if (delegate) { \
347                         (delegate)->size = sizeof(struct Growl_Delegate); \
348                         (delegate)->applicationName = NULL; \
349                         (delegate)->registrationDictionary = NULL; \
350                         (delegate)->applicationIconData = NULL; \
351                         (delegate)->growlInstallationWindowTitle = NULL; \
352                         (delegate)->growlInstallationInformation = NULL; \
353                         (delegate)->growlUpdateWindowTitle = NULL; \
354                         (delegate)->growlUpdateInformation = NULL; \
355                         (delegate)->referenceCount = 1U; \
356                         (delegate)->retain = NULL; \
357                         (delegate)->release = NULL; \
358                         (delegate)->growlIsReady = NULL; \
359                         (delegate)->growlNotificationWasClicked = NULL; \
360                         (delegate)->growlNotificationTimedOut = NULL; \
361                 } \
362         } while(0)
363
364 /*!     @defined        InitGrowlNotification
365  *      @abstract       Callable macro. Initializes a Growl notification structure to defaults.
366  *      @discussion     Call with a pointer to a struct Growl_Notification. All of
367  *       the members of the structure will be set to 0 or <code>NULL</code>, except
368  *       for size (which will be set to
369  *      <code>sizeof(struct Growl_Notification)</code>).
370  */
371 #define InitGrowlNotification(notification) \
372         do { \
373                 if (notification) { \
374                         (notification)->size = sizeof(struct Growl_Notification); \
375                         (notification)->name = NULL; \
376                         (notification)->title = NULL; \
377                         (notification)->description = NULL; \
378                         (notification)->iconData = NULL; \
379                         (notification)->priority = 0; \
380                         (notification)->reserved = 0U; \
381                         (notification)->isSticky = false; \
382                         (notification)->clickContext = NULL; \
383                         (notification)->clickCallback = NULL; \
384                         (notification)->identifier = NULL; \
385                 } \
386         } while(0)
387
388 #pragma mark -
389 #pragma mark Public API
390
391 //      @functiongroup  Managing the Growl delegate
392
393 /*!     @function       Growl_SetDelegate
394  *      @abstract       Replaces the current Growl delegate with a new one, or removes
395  *       the Growl delegate.
396  *      @param  newDelegate
397  *      @result Returns false and does nothing else if a pointer that was passed in
398  *       is unsatisfactory (because it is non-<code>NULL</code>, but at least one
399  *       required member of it is <code>NULL</code>). Otherwise, sets or unsets the
400  *       delegate and returns true.
401  *      @discussion     When <code>newDelegate</code> is non-<code>NULL</code>, sets
402  *       the delegate to <code>newDelegate</code>. When it is <code>NULL</code>,
403  *       the current delegate will be unset, and no delegate will be in place.
404  *
405  *       It is legal for <code>newDelegate</code> to be the current delegate;
406  *       nothing will happen, and Growl_SetDelegate will return true. It is also
407  *       legal for it to be <code>NULL</code>, as described above; again, it will
408  *       return true.
409  *
410  *       If there was a delegate in place before the call, Growl_SetDelegate will
411  *       call the old delegate's release member if it was non-<code>NULL</code>. If
412  *       <code>newDelegate</code> is non-<code>NULL</code>, Growl_SetDelegate will
413  *       call <code>newDelegate->retain</code>, and set the delegate to its return
414  *       value.
415  *
416  *       If you are using Growl-WithInstaller.framework, and an older version of
417  *       Growl is installed on the user's system, the user will automatically be
418  *       prompted to update.
419  *
420  *       GrowlApplicationBridge currently does not copy this structure, nor does it
421  *       retain any of the CF objects in the structure (it regards the structure as
422  *       a container that retains the objects when they are added and releases them
423  *       when they are removed or the structure is destroyed). Also,
424  *       GrowlApplicationBridge currently does not modify any member of the
425  *       structure, except possibly the referenceCount by calling the retain and
426  *       release members.
427  */
428 GROWL_EXPORT Boolean Growl_SetDelegate(struct Growl_Delegate *newDelegate);
429
430 /*!     @function       Growl_GetDelegate
431  *      @abstract       Returns the current Growl delegate, if any.
432  *      @result The current Growl delegate.
433  *      @discussion     Returns the last pointer passed into Growl_SetDelegate, or
434  *       <code>NULL</code> if no such call has been made.
435  *
436  *       This function follows standard Core Foundation reference-counting rules.
437  *       Because it is a Get function, not a Copy function, it will not retain the
438  *       delegate on your behalf. You are responsible for retaining and releasing
439  *       the delegate as needed.
440  */
441 GROWL_EXPORT struct Growl_Delegate *Growl_GetDelegate(void);
442
443 #pragma mark -
444
445 //      @functiongroup  Posting Growl notifications
446
447 /*!     @function       Growl_PostNotification
448  *      @abstract       Posts a Growl notification.
449  *      @param  notification    The notification to post.
450  *      @discussion     This is the preferred means for sending a Growl notification.
451  *       The notification name and at least one of the title and description are
452  *       required (all three are preferred). All other parameters may be
453  *       <code>NULL</code> (or 0 or false as appropriate) to accept default values.
454  *
455  *       If using the Growl-WithInstaller framework, if Growl is not installed the
456  *       user will be prompted to install Growl.
457  *       If the user cancels, this function will have no effect until the next
458  *       application session, at which time when it is called the user will be
459  *       prompted again. The user is also given the option to not be prompted again.
460  *       If the user does choose to install Growl, the requested notification will
461  *       be displayed once Growl is installed and running.
462  */
463 GROWL_EXPORT void Growl_PostNotification(const struct Growl_Notification *notification);
464
465 /*!     @function Growl_PostNotificationWithDictionary
466 *       @abstract       Notifies using a userInfo dictionary suitable for passing to
467 *        CFDistributedNotificationCenter.
468 *       @param  userInfo        The dictionary to notify with.
469 *       @discussion     Before Growl 0.6, your application would have posted
470 *        notifications using CFDistributedNotificationCenter by creating a userInfo
471 *        dictionary with the notification data. This had the advantage of allowing
472 *        you to add other data to the dictionary for programs besides Growl that
473 *        might be listening.
474 *
475 *        This function allows you to use such dictionaries without being restricted
476 *        to using CFDistributedNotificationCenter. The keys for this dictionary
477  *       can be found in GrowlDefines.h.
478 */
479 GROWL_EXPORT void Growl_PostNotificationWithDictionary(CFDictionaryRef userInfo);
480
481 /*!     @function       Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext
482  *      @abstract       Posts a Growl notification using parameter values.
483  *      @param  title   The title of the notification.
484  *      @param  description     The description of the notification.
485  *      @param  notificationName        The name of the notification as listed in the
486  *       registration dictionary.
487  *      @param  iconData        Data representing a notification icon. Can be <code>NULL</code>.
488  *      @param  priority        The priority of the notification (-2 to +2, with -2
489  *       being Very Low and +2 being Very High).
490  *      @param  isSticky        If true, requests that this notification wait for a
491  *       response from the user.
492  *      @param  clickContext    An object to pass to the clickCallback, if any. Can
493  *       be <code>NULL</code>, in which case the clickCallback is not called.
494  *      @discussion     Creates a temporary Growl_Notification, fills it out with the
495  *       supplied information, and calls Growl_PostNotification on it.
496  *       See struct Growl_Notification and Growl_PostNotification for more
497  *       information.
498  *
499  *       The icon data can be in any format supported by NSImage. As of Mac OS X
500  *       10.3, this includes the .icns, TIFF, JPEG, GIF, PNG, PDF, and PICT formats.
501  */
502 GROWL_EXPORT void Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext(
503  /*inhale*/
504         CFStringRef title,
505         CFStringRef description,
506         CFStringRef notificationName,
507         CFDataRef iconData,
508         signed int priority,
509         Boolean isSticky,
510         CFPropertyListRef clickContext);
511
512 #pragma mark -
513
514 //      @functiongroup  Registering
515
516 /*!     @function Growl_RegisterWithDictionary
517  *      @abstract       Register your application with Growl without setting a delegate.
518  *      @discussion     When you call this function with a dictionary,
519  *       GrowlApplicationBridge registers your application using that dictionary.
520  *       If you pass <code>NULL</code>, GrowlApplicationBridge will ask the delegate
521  *       (if there is one) for a dictionary, and if that doesn't work, it will look
522  *       in your application's bundle for an auto-discoverable plist.
523  *       (XXX refer to more information on that)
524  *
525  *       If you pass a dictionary to this function, it must include the
526  *       <code>GROWL_APP_NAME</code> key, unless a delegate is set.
527  *
528  *       This function is mainly an alternative to the delegate system introduced
529  *       with Growl 0.6. Without a delegate, you cannot receive callbacks such as
530  *       <code>growlIsReady</code> (since they are sent to the delegate). You can,
531  *       however, set a delegate after registering without one.
532  *
533  *       This function was introduced in Growl.framework 0.7.
534  *      @result <code>false</code> if registration failed (e.g. if Growl isn't installed).
535  */
536 GROWL_EXPORT Boolean Growl_RegisterWithDictionary(CFDictionaryRef regDict);
537
538 /*!     @function       Growl_Reregister
539  *      @abstract       Updates your registration with Growl.
540  *      @discussion     If your application changes the contents of the
541  *       GROWL_NOTIFICATIONS_ALL key in the registrationDictionary member of the
542  *       Growl delegate, or if it changes the value of that member, or if it
543  *       changes the contents of its auto-discoverable plist, call this function
544  *       to have Growl update its registration information for your application.
545  *
546  *       Otherwise, this function does not normally need to be called. If you're
547  *       using a delegate, your application will be registered when you set the
548  *       delegate if both the delegate and its registrationDictionary member are
549  *       non-<code>NULL</code>.
550  *
551  *       This function is now implemented using
552  *       <code>Growl_RegisterWithDictionary</code>.
553  */
554 GROWL_EXPORT void Growl_Reregister(void);
555
556 #pragma mark -
557
558 /*!     @function       Growl_SetWillRegisterWhenGrowlIsReady
559  *      @abstract       Tells GrowlApplicationBridge to register with Growl when Growl
560  *       launches (or not).
561  *      @discussion     When Growl has started listening for notifications, it posts a
562  *       <code>GROWL_IS_READY</code> notification on the Distributed Notification
563  *       Center. GrowlApplicationBridge listens for this notification, using it to
564  *       perform various tasks (such as calling your delegate's
565  *       <code>growlIsReady</code> callback, if it has one). If this function is
566  *       called with <code>true</code>, one of those tasks will be to reregister
567  *       with Growl (in the manner of <code>Growl_Reregister</code>).
568  *
569  *       This attribute is automatically set back to <code>false</code>
570  *       (the default) after every <code>GROWL_IS_READY</code> notification.
571  *      @param  flag    <code>true</code> if you want GrowlApplicationBridge to register with
572  *       Growl when next it is ready; <code>false</code> if not.
573  */
574 GROWL_EXPORT void Growl_SetWillRegisterWhenGrowlIsReady(Boolean flag);
575 /*!     @function       Growl_WillRegisterWhenGrowlIsReady
576  *      @abstract       Reports whether GrowlApplicationBridge will register with Growl
577  *       when Growl next launches.
578  *      @result <code>true</code> if GrowlApplicationBridge will register with
579  *       Growl when next it posts GROWL_IS_READY; <code>false</code> if not.
580  */
581 GROWL_EXPORT Boolean Growl_WillRegisterWhenGrowlIsReady(void);
582
583 #pragma mark -
584
585 //      @functiongroup  Obtaining registration dictionaries
586
587 /*!     @function       Growl_CopyRegistrationDictionaryFromDelegate
588  *      @abstract       Asks the delegate for a registration dictionary.
589  *      @discussion     If no delegate is set, or if the delegate's
590  *       <code>registrationDictionary</code> member is <code>NULL</code>, this
591  *       function returns <code>NULL</code>.
592  *
593  *       This function does not attempt to clean up the dictionary in any way - for
594  *       example, if it is missing the <code>GROWL_APP_NAME</code> key, the result
595  *       will be missing it too. Use
596  *       <code>Growl_CreateRegistrationDictionaryByFillingInDictionary</code> or
597  *       <code>Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys</code>
598  *       to try to fill in missing keys.
599  *
600  *       This function was introduced in Growl.framework 0.7.
601  *      @result A registration dictionary.
602  */
603 GROWL_EXPORT CFDictionaryRef Growl_CopyRegistrationDictionaryFromDelegate(void);
604
605 /*!     @function       Growl_CopyRegistrationDictionaryFromBundle
606  *      @abstract       Looks in a bundle for a registration dictionary.
607  *      @discussion     This function looks in a bundle for an auto-discoverable
608  *       registration dictionary file using <code>CFBundleCopyResourceURL</code>.
609  *       If it finds one, it loads the file using <code>CFPropertyList</code> and
610  *       returns the result.
611  *
612  *       If you pass <code>NULL</code> as the bundle, the main bundle is examined.
613  *
614  *       This function does not attempt to clean up the dictionary in any way - for
615  *       example, if it is missing the <code>GROWL_APP_NAME</code> key, the result
616  *       will be missing it too. Use
617  *       <code>Growl_CreateRegistrationDictionaryByFillingInDictionary:</code> or
618  *       <code>Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys</code>
619  *       to try to fill in missing keys.
620  *
621  *       This function was introduced in Growl.framework 0.7.
622  *      @result A registration dictionary.
623  */
624 GROWL_EXPORT CFDictionaryRef Growl_CopyRegistrationDictionaryFromBundle(CFBundleRef bundle);
625
626 /*!     @function       Growl_CreateBestRegistrationDictionary
627  *      @abstract       Obtains a registration dictionary, filled out to the best of
628  *       GrowlApplicationBridge's knowledge.
629  *      @discussion     This function creates a registration dictionary as best
630  *       GrowlApplicationBridge knows how.
631  *
632  *       First, GrowlApplicationBridge examines the Growl delegate (if there is
633  *       one) and gets the registration dictionary from that. If no such dictionary
634  *       was obtained, GrowlApplicationBridge looks in your application's main
635  *       bundle for an auto-discoverable registration dictionary file. If that
636  *       doesn't exist either, this function returns <code>NULL</code>.
637  *
638  *       Second, GrowlApplicationBridge calls
639  *       <code>Growl_CreateRegistrationDictionaryByFillingInDictionary</code> with
640  *       whatever dictionary was obtained. The result of that function is the
641  *       result of this function.
642  *
643  *       GrowlApplicationBridge uses this function when you call
644  *       <code>Growl_SetDelegate</code>, or when you call
645  *       <code>Growl_RegisterWithDictionary</code> with <code>NULL</code>.
646  *
647  *       This function was introduced in Growl.framework 0.7.
648  *      @result A registration dictionary.
649  */
650 GROWL_EXPORT CFDictionaryRef Growl_CreateBestRegistrationDictionary(void);
651
652 #pragma mark -
653
654 //      @functiongroup  Filling in registration dictionaries
655
656 /*!     @function       Growl_CreateRegistrationDictionaryByFillingInDictionary
657  *      @abstract       Tries to fill in missing keys in a registration dictionary.
658  *      @param  regDict The dictionary to fill in.
659  *      @result The dictionary with the keys filled in.
660  *      @discussion     This function examines the passed-in dictionary for missing keys,
661  *       and tries to work out correct values for them. As of 0.7, it uses:
662  *
663  *       Key                                                                 Value
664  *       ---                                                                 -----
665  *       <code>GROWL_APP_NAME</code>                 <code>CFBundleExecutableName</code>
666  *       <code>GROWL_APP_ICON</code>                 The icon of the application.
667  *       <code>GROWL_APP_LOCATION</code>             The location of the application.
668  *       <code>GROWL_NOTIFICATIONS_DEFAULT</code>    <code>GROWL_NOTIFICATIONS_ALL</code>
669  *
670  *       Keys are only filled in if missing; if a key is present in the dictionary,
671  *       its value will not be changed.
672  *
673  *       This function was introduced in Growl.framework 0.7.
674  */
675 GROWL_EXPORT CFDictionaryRef Growl_CreateRegistrationDictionaryByFillingInDictionary(CFDictionaryRef regDict);
676 /*!     @function       Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys
677  *      @abstract       Tries to fill in missing keys in a registration dictionary.
678  *      @param  regDict The dictionary to fill in.
679  *      @param  keys    The keys to fill in. If <code>NULL</code>, any missing keys are filled in.
680  *      @result The dictionary with the keys filled in.
681  *      @discussion     This function examines the passed-in dictionary for missing keys,
682  *       and tries to work out correct values for them. As of 0.7, it uses:
683  *
684  *       Key                                                                 Value
685  *       ---                                                                 -----
686  *       <code>GROWL_APP_NAME</code>                 <code>CFBundleExecutableName</code>
687  *       <code>GROWL_APP_ICON</code>                 The icon of the application.
688  *       <code>GROWL_APP_LOCATION</code>             The location of the application.
689  *       <code>GROWL_NOTIFICATIONS_DEFAULT</code>    <code>GROWL_NOTIFICATIONS_ALL</code>
690  *
691  *       Only those keys that are listed in <code>keys</code> will be filled in.
692  *       Other missing keys are ignored. Also, keys are only filled in if missing;
693  *       if a key is present in the dictionary, its value will not be changed.
694  *
695  *       This function was introduced in Growl.framework 0.7.
696  */
697 GROWL_EXPORT CFDictionaryRef Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys(CFDictionaryRef regDict, CFSetRef keys);
698
699 /*!     @brief  Tries to fill in missing keys in a notification dictionary.
700  *      @param  notifDict       The dictionary to fill in.
701  *      @return The dictionary with the keys filled in. This will be a separate instance from \a notifDict.
702  *      @discussion     This function examines the \a notifDict for missing keys, and 
703  *       tries to get them from the last known registration dictionary. As of 1.1, 
704  *       the keys that it will look for are:
705  *
706  *       \li <code>GROWL_APP_NAME</code>
707  *       \li <code>GROWL_APP_ICON</code>
708  *
709  *      @since Growl.framework 1.1
710  */
711 GROWL_EXPORT CFDictionaryRef Growl_CreateNotificationDictionaryByFillingInDictionary(CFDictionaryRef notifDict);
712
713 #pragma mark -
714
715 //      @functiongroup  Querying Growl's status
716
717 /*!     @function       Growl_IsInstalled
718  *      @abstract       Determines whether the Growl prefpane and its helper app are
719  *       installed.
720  *      @result Returns true if Growl is installed, false otherwise.
721  */
722 GROWL_EXPORT Boolean Growl_IsInstalled(void);
723
724 /*!     @function       Growl_IsRunning
725  *      @abstract       Cycles through the process list to find whether GrowlHelperApp
726  *       is running.
727  *      @result Returns true if Growl is running, false otherwise.
728  */
729 GROWL_EXPORT Boolean Growl_IsRunning(void);
730
731 #pragma mark -
732
733 //      @functiongroup  Launching Growl
734
735 /*!     @typedef        GrowlLaunchCallback
736  *      @abstract       Callback to notify you that Growl is running.
737  *      @param  context The context pointer passed to Growl_LaunchIfInstalled.
738  *      @discussion     Growl_LaunchIfInstalled calls this callback function if Growl
739  *       was already running or if it launched Growl successfully.
740  */
741 typedef void (*GrowlLaunchCallback)(void *context);
742
743 /*!     @function       Growl_LaunchIfInstalled
744  *      @abstract       Launches GrowlHelperApp if it is not already running.
745  *      @param  callback        A callback function which will be called if Growl was successfully
746  *       launched or was already running. Can be <code>NULL</code>.
747  *      @param  context The context pointer to pass to the callback. Can be <code>NULL</code>.
748  *      @result Returns true if Growl was successfully launched or was already
749  *       running; returns false and does not call the callback otherwise.
750  *      @discussion     Returns true and calls the callback (if the callback is not
751  *       <code>NULL</code>) if the Growl helper app began launching or was already
752  *       running. Returns false and performs no other action if Growl could not be
753  *       launched (e.g. because the Growl preference pane is not properly installed).
754  *
755  *       If <code>Growl_CreateBestRegistrationDictionary</code> returns
756  *       non-<code>NULL</code>, this function will register with Growl atomically.
757  *
758  *       The callback should take a single argument; this is to allow applications
759  *       to have context-relevant information passed back. It is perfectly
760  *       acceptable for context to be <code>NULL</code>. The callback itself can be
761  *       <code>NULL</code> if you don't want one.
762  */
763 GROWL_EXPORT Boolean Growl_LaunchIfInstalled(GrowlLaunchCallback callback, void *context);
764
765 #pragma mark -
766 #pragma mark Constants
767
768 /*!     @defined        GROWL_PREFPANE_BUNDLE_IDENTIFIER
769  *      @abstract       The CFBundleIdentifier of the Growl preference pane bundle.
770  *      @discussion     GrowlApplicationBridge uses this to determine whether Growl is
771  *       currently installed, by searching for the Growl preference pane. Your
772  *       application probably does not need to use this macro itself.
773  */
774 #ifndef GROWL_PREFPANE_BUNDLE_IDENTIFIER
775 #define GROWL_PREFPANE_BUNDLE_IDENTIFIER        CFSTR("com.growl.prefpanel")
776 #endif
777
778 __END_DECLS
779
780 #endif /* _GROWLAPPLICATIONBRIDGE_CARBON_H_ */