macosx/Growl.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_ */