1 // Copyright 2013 The Flutter Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef FLUTTER_FLUTTERPLUGIN_H_ 6 #define FLUTTER_FLUTTERPLUGIN_H_ 7 8 #import <UIKit/UIKit.h> 9 #import <UserNotifications/UNUserNotificationCenter.h> 10 11 #include "FlutterBinaryMessenger.h" 12 #include "FlutterChannels.h" 13 #include "FlutterCodecs.h" 14 #include "FlutterPlatformViews.h" 15 #include "FlutterTexture.h" 16 17 NS_ASSUME_NONNULL_BEGIN 18 @protocol FlutterPluginRegistrar; 19 @protocol FlutterPluginRegistry; 20 21 #pragma mark - 22 /*************************************************************************************************** 23 * Protocol for listener of events from the UIApplication, typically a FlutterPlugin. 24 */ 25 @protocol FlutterApplicationLifeCycleDelegate 26 @optional 27 /** 28 * Called if this has been registered for `UIApplicationDelegate` callbacks. 29 * 30 * @return `NO` if this vetoes application launch. 31 */ 32 - (BOOL)application:(UIApplication*)application 33 didFinishLaunchingWithOptions:(NSDictionary*)launchOptions; 34 35 /** 36 * Called if this has been registered for `UIApplicationDelegate` callbacks. 37 * 38 * @return `NO` if this vetoes application launch. 39 */ 40 - (BOOL)application:(UIApplication*)application 41 willFinishLaunchingWithOptions:(NSDictionary*)launchOptions; 42 43 /** 44 * Called if this has been registered for `UIApplicationDelegate` callbacks. 45 */ 46 - (void)applicationDidBecomeActive:(UIApplication*)application; 47 48 /** 49 * Called if this has been registered for `UIApplicationDelegate` callbacks. 50 */ 51 - (void)applicationWillResignActive:(UIApplication*)application; 52 53 /** 54 * Called if this has been registered for `UIApplicationDelegate` callbacks. 55 */ 56 - (void)applicationDidEnterBackground:(UIApplication*)application; 57 58 /** 59 * Called if this has been registered for `UIApplicationDelegate` callbacks. 60 */ 61 - (void)applicationWillEnterForeground:(UIApplication*)application; 62 63 /** 64 Called if this has been registered for `UIApplicationDelegate` callbacks. 65 */ 66 - (void)applicationWillTerminate:(UIApplication*)application; 67 68 /** 69 * Called if this has been registered for `UIApplicationDelegate` callbacks. 70 */ 71 - (void)application:(UIApplication*)application 72 didRegisterUserNotificationSettings:(UIUserNotificationSettings*)notificationSettings 73 API_DEPRECATED( 74 "See -[UIApplicationDelegate application:didRegisterUserNotificationSettings:] deprecation", 75 ios(8.0, 10.0)); 76 77 /** 78 * Called if this has been registered for `UIApplicationDelegate` callbacks. 79 */ 80 - (void)application:(UIApplication*)application 81 didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken; 82 83 /** 84 * Called if this has been registered for `UIApplicationDelegate` callbacks. 85 * 86 * @return `YES` if this handles the request. 87 */ 88 - (BOOL)application:(UIApplication*)application 89 didReceiveRemoteNotification:(NSDictionary*)userInfo 90 fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler; 91 92 /** 93 * Calls all plugins registered for `UIApplicationDelegate` callbacks. 94 */ 95 - (void)application:(UIApplication*)application 96 didReceiveLocalNotification:(UILocalNotification*)notification 97 API_DEPRECATED( 98 "See -[UIApplicationDelegate application:didReceiveLocalNotification:] deprecation", 99 ios(4.0, 10.0)); 100 101 /** 102 * Calls all plugins registered for `UNUserNotificationCenterDelegate` callbacks. 103 */ 104 - (void)userNotificationCenter:(UNUserNotificationCenter*)center 105 willPresentNotification:(UNNotification*)notification 106 withCompletionHandler: 107 (void (^)(UNNotificationPresentationOptions options))completionHandler 108 API_AVAILABLE(ios(10)); 109 110 /** 111 * Called if this has been registered for `UIApplicationDelegate` callbacks. 112 * 113 * @return `YES` if this handles the request. 114 */ 115 - (BOOL)application:(UIApplication*)application 116 openURL:(NSURL*)url 117 options:(NSDictionary<UIApplicationOpenURLOptionsKey, id>*)options; 118 119 /** 120 * Called if this has been registered for `UIApplicationDelegate` callbacks. 121 * 122 * @return `YES` if this handles the request. 123 */ 124 - (BOOL)application:(UIApplication*)application handleOpenURL:(NSURL*)url; 125 126 /** 127 * Called if this has been registered for `UIApplicationDelegate` callbacks. 128 * 129 * @return `YES` if this handles the request. 130 */ 131 - (BOOL)application:(UIApplication*)application 132 openURL:(NSURL*)url 133 sourceApplication:(NSString*)sourceApplication 134 annotation:(id)annotation; 135 136 /** 137 * Called if this has been registered for `UIApplicationDelegate` callbacks. 138 * 139 * @return `YES` if this handles the request. 140 */ 141 - (BOOL)application:(UIApplication*)application 142 performActionForShortcutItem:(UIApplicationShortcutItem*)shortcutItem 143 completionHandler:(void (^)(BOOL succeeded))completionHandler 144 API_AVAILABLE(ios(9.0)); 145 146 /** 147 * Called if this has been registered for `UIApplicationDelegate` callbacks. 148 * 149 * @return `YES` if this handles the request. 150 */ 151 - (BOOL)application:(UIApplication*)application 152 handleEventsForBackgroundURLSession:(nonnull NSString*)identifier 153 completionHandler:(nonnull void (^)(void))completionHandler; 154 155 /** 156 * Called if this has been registered for `UIApplicationDelegate` callbacks. 157 * 158 * @return `YES` if this handles the request. 159 */ 160 - (BOOL)application:(UIApplication*)application 161 performFetchWithCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler; 162 163 /** 164 * Called if this has been registered for `UIApplicationDelegate` callbacks. 165 * 166 * @return `YES` if this handles the request. 167 */ 168 - (BOOL)application:(UIApplication*)application 169 continueUserActivity:(NSUserActivity*)userActivity 170 restorationHandler:(void (^)(NSArray*))restorationHandler; 171 @end 172 173 #pragma mark - 174 /*************************************************************************************************** 175 * A plugin registration callback. 176 * 177 * Used for registering plugins with additional instances of 178 * `FlutterPluginRegistry`. 179 * 180 * @param registry The registry to register plugins with. 181 */ 182 typedef void (*FlutterPluginRegistrantCallback)(NSObject<FlutterPluginRegistry>* registry); 183 184 #pragma mark - 185 /*************************************************************************************************** 186 * Implemented by the iOS part of a Flutter plugin. 187 * 188 * Defines a set of optional callback methods and a method to set up the plugin 189 * and register it to be called by other application components. 190 */ 191 @protocol FlutterPlugin <NSObject, FlutterApplicationLifeCycleDelegate> 192 @required 193 /** 194 * Registers this plugin using the context information and callback registration 195 * methods exposed by the given registrar. 196 * 197 * The registrar is obtained from a `FlutterPluginRegistry` which keeps track of 198 * the identity of registered plugins and provides basic support for cross-plugin 199 * coordination. 200 * 201 * The caller of this method, a plugin registrant, is usually autogenerated by 202 * Flutter tooling based on declared plugin dependencies. The generated registrant 203 * asks the registry for a registrar for each plugin, and calls this method to 204 * allow the plugin to initialize itself and register callbacks with application 205 * objects available through the registrar protocol. 206 * 207 * @param registrar A helper providing application context and methods for 208 * registering callbacks. 209 */ 210 + (void)registerWithRegistrar:(NSObject<FlutterPluginRegistrar>*)registrar; 211 @optional 212 /** 213 * Set a callback for registering plugins to an additional `FlutterPluginRegistry`, 214 * including headless `FlutterEngine` instances. 215 * 216 * This method is typically called from within an application's `AppDelegate` at 217 * startup to allow for plugins which create additional `FlutterEngine` instances 218 * to register the application's plugins. 219 * 220 * @param callback A callback for registering some set of plugins with a 221 * `FlutterPluginRegistry`. 222 */ 223 + (void)setPluginRegistrantCallback:(FlutterPluginRegistrantCallback)callback; 224 @optional 225 /** 226 * Called if this plugin has been registered to receive `FlutterMethodCall`s. 227 * 228 * @param call The method call command object. 229 * @param result A callback for submitting the result of the call. 230 */ 231 - (void)handleMethodCall:(FlutterMethodCall*)call result:(FlutterResult)result; 232 @end 233 234 #pragma mark - 235 /*************************************************************************************************** 236 *Registration context for a single `FlutterPlugin`, providing a one stop shop 237 *for the plugin to access contextual information and register callbacks for 238 *various application events. 239 * 240 *Registrars are obtained from a `FlutterPluginRegistry` which keeps track of 241 *the identity of registered plugins and provides basic support for cross-plugin 242 *coordination. 243 */ 244 @protocol FlutterPluginRegistrar <NSObject> 245 /** 246 * Returns a `FlutterBinaryMessenger` for creating Dart/iOS communication 247 * channels to be used by the plugin. 248 * 249 * @return The messenger. 250 */ 251 - (NSObject<FlutterBinaryMessenger>*)messenger; 252 253 /** 254 * Returns a `FlutterTextureRegistry` for registering textures 255 * provided by the plugin. 256 * 257 * @return The texture registry. 258 */ 259 - (NSObject<FlutterTextureRegistry>*)textures; 260 261 /** 262 * Registers a `FlutterPlatformViewFactory` for creation of platform views. 263 * 264 * Plugins expose `UIView` for embedding in Flutter apps by registering a view factory. 265 * 266 * @param factory The view factory that will be registered. 267 * @param factoryId A unique identifier for the factory, the Dart code of the Flutter app can use 268 * this identifier to request creation of a `UIView` by the registered factory. 269 */ 270 - (void)registerViewFactory:(NSObject<FlutterPlatformViewFactory>*)factory 271 withId:(NSString*)factoryId; 272 273 /** 274 * Publishes a value for external use of the plugin. 275 * 276 * Plugins may publish a single value, such as an instance of the 277 * plugin's main class, for situations where external control or 278 * interaction is needed. 279 * 280 * The published value will be available from the `FlutterPluginRegistry`. 281 * Repeated calls overwrite any previous publication. 282 * 283 * @param value The value to be published. 284 */ 285 - (void)publish:(NSObject*)value; 286 287 /** 288 * Registers the plugin as a receiver of incoming method calls from the Dart side 289 * on the specified `FlutterMethodChannel`. 290 * 291 * @param delegate The receiving object, such as the plugin's main class. 292 * @param channel The channel 293 */ 294 - (void)addMethodCallDelegate:(NSObject<FlutterPlugin>*)delegate 295 channel:(FlutterMethodChannel*)channel; 296 297 /** 298 * Registers the plugin as a receiver of `UIApplicationDelegate` calls. 299 * 300 * @param delegate The receiving object, such as the plugin's main class. 301 */ 302 - (void)addApplicationDelegate:(NSObject<FlutterPlugin>*)delegate; 303 304 /** 305 * Returns the file name for the given asset. 306 * The returned file name can be used to access the asset in the application's main bundle. 307 * 308 * @param asset The name of the asset. The name can be hierarchical. 309 * @return the file name to be used for lookup in the main bundle. 310 */ 311 - (NSString*)lookupKeyForAsset:(NSString*)asset; 312 313 /** 314 * Returns the file name for the given asset which originates from the specified package. 315 * The returned file name can be used to access the asset in the application's main bundle. 316 * 317 * 318 * @param asset The name of the asset. The name can be hierarchical. 319 * @param package The name of the package from which the asset originates. 320 * @return the file name to be used for lookup in the main bundle. 321 */ 322 - (NSString*)lookupKeyForAsset:(NSString*)asset fromPackage:(NSString*)package; 323 @end 324 325 #pragma mark - 326 /*************************************************************************************************** 327 * A registry of Flutter iOS plugins. 328 * 329 * Plugins are identified by unique string keys, typically the name of the 330 * plugin's main class. The registry tracks plugins by this key, mapping it to 331 * a value published by the plugin during registration, if any. This provides a 332 * very basic means of cross-plugin coordination with loose coupling between 333 * unrelated plugins. 334 * 335 * Plugins typically need contextual information and the ability to register 336 * callbacks for various application events. To keep the API of the registry 337 * focused, these facilities are not provided directly by the registry, but by 338 * a `FlutterPluginRegistrar`, created by the registry in exchange for the unique 339 * key of the plugin. 340 * 341 * There is no implied connection between the registry and the registrar. 342 * Specifically, callbacks registered by the plugin via the registrar may be 343 * relayed directly to the underlying iOS application objects. 344 */ 345 @protocol FlutterPluginRegistry <NSObject> 346 /** 347 * Returns a registrar for registering a plugin. 348 * 349 * @param pluginKey The unique key identifying the plugin. 350 */ 351 - (NSObject<FlutterPluginRegistrar>*)registrarForPlugin:(NSString*)pluginKey; 352 /** 353 * Returns whether the specified plugin has been registered. 354 * 355 * @param pluginKey The unique key identifying the plugin. 356 * @return `YES` if `registrarForPlugin` has been called with `pluginKey`. 357 */ 358 - (BOOL)hasPlugin:(NSString*)pluginKey; 359 360 /** 361 * Returns a value published by the specified plugin. 362 * 363 * @param pluginKey The unique key identifying the plugin. 364 * @return An object published by the plugin, if any. Will be `NSNull` if 365 * nothing has been published. Will be `nil` if the plugin has not been 366 * registered. 367 */ 368 - (NSObject*)valuePublishedByPlugin:(NSString*)pluginKey; 369 @end 370 371 #pragma mark - 372 /*************************************************************************************************** 373 * Implement this in the `UIAppDelegate` of your app to enable Flutter plugins to register 374 * themselves to the application life cycle events. 375 */ 376 @protocol FlutterAppLifeCycleProvider 377 - (void)addApplicationLifeCycleDelegate:(NSObject<FlutterApplicationLifeCycleDelegate>*)delegate; 378 @end 379 380 NS_ASSUME_NONNULL_END; 381 382 #endif // FLUTTER_FLUTTERPLUGIN_H_ 383