/SparkleShare/Mac/Growl.framework/Versions/A/Headers/GrowlApplicationBridge-Carbon.h
C++ Header | 780 lines | 116 code | 68 blank | 596 comment | 2 complexity | 96254e37dd540ce99650becbc3f7be1d MD5 | raw file
1// 2// GrowlApplicationBridge-Carbon.h 3// Growl 4// 5// Created by Peter Hosey 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"))) DEPRECATED_ATTRIBUTE 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 */ 59struct 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 */ 240struct 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 */ 428GROWL_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 */ 441GROWL_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 */ 463GROWL_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*/ 479GROWL_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 */ 502GROWL_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 */ 536GROWL_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 */ 554GROWL_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 */ 574GROWL_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 */ 581GROWL_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 */ 603GROWL_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 */ 624GROWL_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 */ 650GROWL_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 */ 675GROWL_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 */ 697GROWL_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 */ 711GROWL_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 */ 722GROWL_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 */ 729GROWL_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 */ 741typedef 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 */ 763GROWL_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_ */