growlapplicationbridge-carbon.h

lumaqq

/*!	@function Growl_RegisterWithDictionary
 *	@abstract	Register your application with Growl without setting a delegate.
 *	@discussion	When you call this function with a dictionary,
 *	 GrowlApplicationBridge registers your application using that dictionary.
 *	 If you pass <code>NULL</code>, GrowlApplicationBridge will ask the delegate
 *	 (if there is one) for a dictionary, and if that doesn't work, it will look
 *	 in your application's bundle for an auto-discoverable plist.
 *	 (XXX refer to more information on that)
 *
 *	 If you pass a dictionary to this function, it must include the
 *	 <code>GROWL_APP_NAME</code> key, unless a delegate is set.
 *
 *	 This function is mainly an alternative to the delegate system introduced
 *	 with Growl 0.6. Without a delegate, you cannot receive callbacks such as
 *	 <code>growlIsReady</code> (since they are sent to the delegate). You can,
 *	 however, set a delegate after registering without one.
 *
 *	 This function was introduced in Growl.framework 0.7.
 *	@result <code>false</code> if registration failed (e.g. if Growl isn't installed).
 */
Boolean Growl_RegisterWithDictionary(CFDictionaryRef regDict);

/*!	@function	Growl_Reregister
 *	@abstract	Updates your registration with Growl.
 *	@discussion	If your application changes the contents of the
 *	 GROWL_NOTIFICATIONS_ALL key in the registrationDictionary member of the
 *	 Growl delegate, or if it changes the value of that member, or if it
 *	 changes the contents of its auto-discoverable plist, call this function
 *	 to have Growl update its registration information for your application.
 *
 *	 Otherwise, this function does not normally need to be called. If you're
 *	 using a delegate, your application will be registered when you set the
 *	 delegate if both the delegate and its registrationDictionary member are
 *	 non-<code>NULL</code>.
 *
 *	 This function is now implemented using
 *	 <code>Growl_RegisterWithDictionary</code>.
 */
void Growl_Reregister(void);

#pragma mark -

/*!	@function	Growl_SetWillRegisterWhenGrowlIsReady
 *	@abstract	Tells GrowlApplicationBridge to register with Growl when Growl
 *	 launches (or not).
 *	@discussion	When Growl has started listening for notifications, it posts a
 *	 <code>GROWL_IS_READY</code> notification on the Distributed Notification
 *	 Center. GrowlApplicationBridge listens for this notification, using it to
 *	 perform various tasks (such as calling your delegate's
 *	 <code>growlIsReady</code> callback, if it has one). If this function is
 *	 called with <code>true</code>, one of those tasks will be to reregister
 *	 with Growl (in the manner of <code>Growl_Reregister</code>).
 *
 *	 This attribute is automatically set back to <code>false</code>
 *	 (the default) after every <code>GROWL_IS_READY</code> notification.
 *	@param	flag	<code>true</code> if you want GrowlApplicationBridge to register with
 *	 Growl when next it is ready; <code>false</code> if not.
 */
void Growl_SetWillRegisterWhenGrowlIsReady(Boolean flag);
/*!	@function	Growl_WillRegisterWhenGrowlIsReady
 *	@abstract	Reports whether GrowlApplicationBridge will register with Growl
 *	 when Growl next launches.
 *	@result	<code>true</code> if GrowlApplicationBridge will register with
 *	 Growl when next it posts GROWL_IS_READY; <code>false</code> if not.
 */
Boolean Growl_WillRegisterWhenGrowlIsReady(void);

#pragma mark -

//	@functiongroup	Obtaining registration dictionaries

/*!	@function	Growl_CopyRegistrationDictionaryFromDelegate
 *	@abstract	Asks the delegate for a registration dictionary.
 *	@discussion	If no delegate is set, or if the delegate's
 *	 <code>registrationDictionary</code> member is <code>NULL</code>, this
 *	 function returns <code>NULL</code>.
 *
 *	 This function does not attempt to clean up the dictionary in any way - for
 *	 example, if it is missing the <code>GROWL_APP_NAME</code> key, the result
 *	 will be missing it too. Use
 *	 <code>Growl_CreateRegistrationDictionaryByFillingInDictionary:</code> or
 *	 <code>Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys</code>
 *	 to try to fill in missing keys.
 *
 *	 This function was introduced in Growl.framework 0.7.
 *	@result A registration dictionary.
 */
CFDictionaryRef Growl_CopyRegistrationDictionaryFromDelegate(void);

/*!	@function	Growl_CopyRegistrationDictionaryFromBundle
 *	@abstract	Looks in a bundle for a registration dictionary.
 *	@discussion	This function looks in a bundle for an auto-discoverable
 *	 registration dictionary file using <code>CFBundleCopyResourceURL</code>.
 *	 If it finds one, it loads the file using <code>CFPropertyList</code> and
 *	 returns the result.
 *
 *	 If you pass <code>NULL</code> as the bundle, the main bundle is examined.
 *
 *	 This function does not attempt to clean up the dictionary in any way - for
 *	 example, if it is missing the <code>GROWL_APP_NAME</code> key, the result
 *	 will be missing it too. Use
 *	 <code>Growl_CreateRegistrationDictionaryByFillingInDictionary:</code> or
 *	 <code>Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys</code>
 *	 to try to fill in missing keys.
 *
 *	 This function was introduced in Growl.framework 0.7.
 *	@result A registration dictionary.
 */
CFDictionaryRef Growl_CopyRegistrationDictionaryFromBundle(CFBundleRef bundle);

/*!	@function	Growl_CreateBestRegistrationDictionary
 *	@abstract	Obtains a registration dictionary, filled out to the best of
 *	 GrowlApplicationBridge's knowledge.
 *	@discussion	This function creates a registration dictionary as best
 *	 GrowlApplicationBridge knows how.
 *
 *	 First, GrowlApplicationBridge examines the Growl delegate (if there is
 *	 one) and gets the registration dictionary from that. If no such dictionary
 *	 was obtained, GrowlApplicationBridge looks in your application's main
 *	 bundle for an auto-discoverable registration dictionary file. If that
 *	 doesn't exist either, this function returns <code>NULL</code>.
 *
 *	 Second, GrowlApplicationBridge calls
 *	 <code>Growl_CreateRegistrationDictionaryByFillingInDictionary</code> with
 *	 whatever dictionary was obtained. The result of that function is the
 *	 result of this function.
 *
 *	 GrowlApplicationBridge uses this function when you call
 *	 <code>Growl_SetDelegate</code>, or when you call
 *	 <code>Growl_RegisterWithDictionary</code> with <code>NULL</code>.
 *
 *	 This function was introduced in Growl.framework 0.7.
 *	@result	A registration dictionary.
 */
CFDictionaryRef Growl_CreateBestRegistrationDictionary(void);

#pragma mark -

//	@functiongroup	Filling in registration dictionaries

/*!	@function	Growl_CreateRegistrationDictionaryByFillingInDictionary
 *	@abstract	Tries to fill in missing keys in a registration dictionary.
 *	@param	regDict	The dictionary to fill in.
 *	@result	The dictionary with the keys filled in.
 *	@discussion	This function examines the passed-in dictionary for missing keys,
 *	 and tries to work out correct values for them. As of 0.7, it uses:
 *
 *	 Key							             Value
 *	 ---							             -----
 *	 <code>GROWL_APP_NAME</code>                 <code>CFBundleExecutableName</code>
 *	 <code>GROWL_APP_ICON</code>                 The icon of the application.
 *	 <code>GROWL_APP_LOCATION</code>             The location of the application.
 *	 <code>GROWL_NOTIFICATIONS_DEFAULT</code>    <code>GROWL_NOTIFICATIONS_ALL</code>
 *
 *	 Keys are only filled in if missing; if a key is present in the dictionary,
 *	 its value will not be changed.
 *
 *	 This function was introduced in Growl.framework 0.7.
 */
CFDictionaryRef Growl_CreateRegistrationDictionaryByFillingInDictionary(CFDictionaryRef regDict);
/*!	@function	Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys
 *	@abstract	Tries to fill in missing keys in a registration dictionary.
 *	@param	regDict	The dictionary to fill in.
 *	@param	keys	The keys to fill in. If <code>NULL</code>, any missing keys are filled in.
 *	@result	The dictionary with the keys filled in.
 *	@discussion	This function examines the passed-in dictionary for missing keys,
 *	 and tries to work out correct values for them. As of 0.7, it uses:
 *
 *	 Key							             Value
 *	 ---							             -----
 *	 <code>GROWL_APP_NAME</code>                 <code>CFBundleExecutableName</code>
 *	 <code>GROWL_APP_ICON</code>                 The icon of the application.
 *	 <code>GROWL_APP_LOCATION</code>             The location of the application.
 *	 <code>GROWL_NOTIFICATIONS_DEFAULT</code>    <code>GROWL_NOTIFICATIONS_ALL</code>
 *
 *	 Only those keys that are listed in <code>keys</code> will be filled in.
 *	 Other missing keys are ignored. Also, keys are only filled in if missing;
 *	 if a key is present in the dictionary, its value will not be changed.
 *
 *	 This function was introduced in Growl.framework 0.7.
 */
CFDictionaryRef Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys(CFDictionaryRef regDict, CFSetRef keys);

#pragma mark -

//	@functiongroup	Querying Growl's status

/*!	@function	Growl_IsInstalled
 *	@abstract	Determines whether the Growl prefpane and its helper app are
 *	 installed.
 *	@result	Returns true if Growl is installed, false otherwise.
 */
Boolean Growl_IsInstalled(void);

/*!	@function	Growl_IsRunning
 *	@abstract	Cycles through the process list to find whether GrowlHelperApp
 *	 is running.
 *	@result	Returns true if Growl is running, false otherwise.
 */
Boolean Growl_IsRunning(void);

#pragma mark -

//	@functiongroup	Launching Growl

/*!	@typedef	GrowlLaunchCallback
 *	@abstract	Callback to notify you that Growl is running.
 *	@param	context	The context pointer passed to Growl_LaunchIfInstalled.
 *	@discussion	Growl_LaunchIfInstalled calls this callback function if Growl
 *	 was already running or if it launched Growl successfully.
 */
typedef void (*GrowlLaunchCallback)(void *context);

/*!	@function	Growl_LaunchIfInstalled
 *	@abstract	Launches GrowlHelperApp if it is not already running.
 *	@param	callback	A callback function which will be called if Growl was successfully
 *	 launched or was already running. Can be <code>NULL</code>.
 *	@param	context	The context pointer to pass to the callback. Can be <code>NULL</code>.
 *	@result	Returns true if Growl was successfully launched or was already
 *	 running; returns false and does not call the callback otherwise.
 *	@discussion	Returns true and calls the callback (if the callback is not
 *	 <code>NULL</code>) if the Growl helper app began launching or was already
 *	 running. Returns false and performs no other action if Growl could not be
 *	 launched (e.g. because the Growl preference pane is not properly installed).
 *
 *	 If <code>Growl_CreateBestRegistrationDictionary</code> returns
 *	 non-<code>NULL</code>, this function will register with Growl atomically.
 *
 *	 The callback should take a single argument; this is to allow applications
 *	 to have context-relevant information passed back. It is perfectly
 *	 acceptable for context to be <code>NULL</code>. The callback itself can be
 *	 <code>NULL</code> if you don't want one.
 */
Boolean Growl_LaunchIfInstalled(GrowlLaunchCallback callback, void *context);

#pragma mark -
#pragma mark Constants

/*!	@defined	GROWL_PREFPANE_BUNDLE_IDENTIFIER
 *	@abstract	The CFBundleIdentifier of the Growl preference pane bundle.
 *	@discussion	GrowlApplicationBridge uses this to determine whether Growl is
 *	 currently installed, by searching for the Growl preference pane. Your
 *	 application probably does not need to use this macro itself.
 */
#ifndef GROWL_PREFPANE_BUNDLE_IDENTIFIER
#define GROWL_PREFPANE_BUNDLE_IDENTIFIER	CFSTR("com.growl.prefpanel")
#endif

__END_DECLS

#endif /* _GROWLAPPLICATIONBRIDGE_CARBON_H_ */