Flutter Engine
FlutterPlugin.h
Go to the documentation of this file.
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 
12 #import "FlutterChannels.h"
13 #import "FlutterCodecs.h"
14 #import "FlutterPlatformViews.h"
15 #import "FlutterTexture.h"
16 
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 #if __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_10_0
27  <UNUserNotificationCenterDelegate>
28 #endif
29 @optional
30 /**
31  * Called if this has been registered for `UIApplicationDelegate` callbacks.
32  *
33  * @return `NO` if this vetoes application launch.
34  */
35 - (BOOL)application:(UIApplication*)application
36  didFinishLaunchingWithOptions:(NSDictionary*)launchOptions;
37 
38 /**
39  * Called if this has been registered for `UIApplicationDelegate` callbacks.
40  *
41  * @return `NO` if this vetoes application launch.
42  */
43 - (BOOL)application:(UIApplication*)application
44  willFinishLaunchingWithOptions:(NSDictionary*)launchOptions;
45 
46 /**
47  * Called if this has been registered for `UIApplicationDelegate` callbacks.
48  */
49 - (void)applicationDidBecomeActive:(UIApplication*)application;
50 
51 /**
52  * Called if this has been registered for `UIApplicationDelegate` callbacks.
53  */
54 - (void)applicationWillResignActive:(UIApplication*)application;
55 
56 /**
57  * Called if this has been registered for `UIApplicationDelegate` callbacks.
58  */
59 - (void)applicationDidEnterBackground:(UIApplication*)application;
60 
61 /**
62  * Called if this has been registered for `UIApplicationDelegate` callbacks.
63  */
64 - (void)applicationWillEnterForeground:(UIApplication*)application;
65 
66 /**
67  Called if this has been registered for `UIApplicationDelegate` callbacks.
68  */
69 - (void)applicationWillTerminate:(UIApplication*)application;
70 
71 /**
72  * Called if this has been registered for `UIApplicationDelegate` callbacks.
73  */
74 - (void)application:(UIApplication*)application
75  didRegisterUserNotificationSettings:(UIUserNotificationSettings*)notificationSettings
76  API_DEPRECATED(
77  "See -[UIApplicationDelegate application:didRegisterUserNotificationSettings:] deprecation",
78  ios(8.0, 10.0));
79 
80 /**
81  * Called if this has been registered for `UIApplicationDelegate` callbacks.
82  */
83 - (void)application:(UIApplication*)application
84  didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken;
85 
86 /**
87  * Called if this has been registered for `UIApplicationDelegate` callbacks.
88  */
89 - (void)application:(UIApplication*)application
90  didFailToRegisterForRemoteNotificationsWithError:(NSError*)error;
91 
92 /**
93  * Called if this has been registered for `UIApplicationDelegate` callbacks.
94  *
95  * @return `YES` if this handles the request.
96  */
97 - (BOOL)application:(UIApplication*)application
98  didReceiveRemoteNotification:(NSDictionary*)userInfo
99  fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler;
100 
101 /**
102  * Calls all plugins registered for `UIApplicationDelegate` callbacks.
103  */
104 - (void)application:(UIApplication*)application
105  didReceiveLocalNotification:(UILocalNotification*)notification
106  API_DEPRECATED(
107  "See -[UIApplicationDelegate application:didReceiveLocalNotification:] deprecation",
108  ios(4.0, 10.0));
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 @optional
233 /**
234  * Called when a plugin is being removed from a `FlutterEngine`, which is
235  * usually the result of the `FlutterEngine` being deallocated. This method
236  * provides the opportunity to do necessary cleanup.
237  *
238  * You will only receive this method if you registered your plugin instance with
239  * the `FlutterEngine` via `-[FlutterPluginRegistry publish:]`.
240  *
241  * @param registrar The registrar that was used to publish the plugin.
242  *
243  */
244 - (void)detachFromEngineForRegistrar:(NSObject<FlutterPluginRegistrar>*)registrar;
245 @end
246 
247 #pragma mark -
248 /**
249  * How the UIGestureRecognizers of a platform view are blocked.
250  *
251  * UIGestureRecognizers of platform views can be blocked based on decisions made by the
252  * Flutter Framework (e.g. When an interact-able widget is covering the platform view).
253  */
254 typedef enum {
255  /**
256  * Flutter blocks all the UIGestureRecognizers on the platform view as soon as it
257  * decides they should be blocked.
258  *
259  * With this policy, only the `touchesBegan` method for all the UIGestureRecognizers is guaranteed
260  * to be called.
261  */
263  /**
264  * Flutter blocks the platform view's UIGestureRecognizers from recognizing only after
265  * touchesEnded was invoked.
266  *
267  * This results in the platform view's UIGestureRecognizers seeing the entire touch sequence,
268  * but never recognizing the gesture (and never invoking actions).
269  */
272 
273 #pragma mark -
274 /**
275  * Registration context for a single `FlutterPlugin`, providing a one stop shop
276  * for the plugin to access contextual information and register callbacks for
277  * various application events.
278  *
279  * Registrars are obtained from a `FlutterPluginRegistry` which keeps track of
280  * the identity of registered plugins and provides basic support for cross-plugin
281  * coordination.
282  */
283 @protocol FlutterPluginRegistrar <NSObject>
284 /**
285  * Returns a `FlutterBinaryMessenger` for creating Dart/iOS communication
286  * channels to be used by the plugin.
287  *
288  * @return The messenger.
289  */
290 - (NSObject<FlutterBinaryMessenger>*)messenger;
291 
292 /**
293  * Returns a `FlutterTextureRegistry` for registering textures
294  * provided by the plugin.
295  *
296  * @return The texture registry.
297  */
298 - (NSObject<FlutterTextureRegistry>*)textures;
299 
300 /**
301  * Registers a `FlutterPlatformViewFactory` for creation of platform views.
302  *
303  * Plugins expose `UIView` for embedding in Flutter apps by registering a view factory.
304  *
305  * @param factory The view factory that will be registered.
306  * @param factoryId A unique identifier for the factory, the Dart code of the Flutter app can use
307  * this identifier to request creation of a `UIView` by the registered factory.
308  */
309 - (void)registerViewFactory:(NSObject<FlutterPlatformViewFactory>*)factory
310  withId:(NSString*)factoryId;
311 
312 /**
313  * Registers a `FlutterPlatformViewFactory` for creation of platform views.
314  *
315  * Plugins can expose a `UIView` for embedding in Flutter apps by registering a view factory.
316  *
317  * @param factory The view factory that will be registered.
318  * @param factoryId A unique identifier for the factory, the Dart code of the Flutter app can use
319  * this identifier to request creation of a `UIView` by the registered factory.
320  * @param gestureRecognizersBlockingPolicy How UIGestureRecognizers on the platform views are
321  * blocked.
322  *
323  */
324 - (void)registerViewFactory:(NSObject<FlutterPlatformViewFactory>*)factory
325  withId:(NSString*)factoryId
326  gestureRecognizersBlockingPolicy:
327  (FlutterPlatformViewGestureRecognizersBlockingPolicy)gestureRecognizersBlockingPolicy;
328 
329 /**
330  * Publishes a value for external use of the plugin.
331  *
332  * Plugins may publish a single value, such as an instance of the
333  * plugin's main class, for situations where external control or
334  * interaction is needed.
335  *
336  * The published value will be available from the `FlutterPluginRegistry`.
337  * Repeated calls overwrite any previous publication.
338  *
339  * @param value The value to be published.
340  */
341 - (void)publish:(NSObject*)value;
342 
343 /**
344  * Registers the plugin as a receiver of incoming method calls from the Dart side
345  * on the specified `FlutterMethodChannel`.
346  *
347  * @param delegate The receiving object, such as the plugin's main class.
348  * @param channel The channel
349  */
350 - (void)addMethodCallDelegate:(NSObject<FlutterPlugin>*)delegate
351  channel:(FlutterMethodChannel*)channel;
352 
353 /**
354  * Registers the plugin as a receiver of `UIApplicationDelegate` calls.
355  *
356  * @param delegate The receiving object, such as the plugin's main class.
357  */
358 - (void)addApplicationDelegate:(NSObject<FlutterPlugin>*)delegate;
359 
360 /**
361  * Returns the file name for the given asset.
362  * The returned file name can be used to access the asset in the application's main bundle.
363  *
364  * @param asset The name of the asset. The name can be hierarchical.
365  * @return the file name to be used for lookup in the main bundle.
366  */
367 - (NSString*)lookupKeyForAsset:(NSString*)asset;
368 
369 /**
370  * Returns the file name for the given asset which originates from the specified package.
371  * The returned file name can be used to access the asset in the application's main bundle.
372  *
373  *
374  * @param asset The name of the asset. The name can be hierarchical.
375  * @param package The name of the package from which the asset originates.
376  * @return the file name to be used for lookup in the main bundle.
377  */
378 - (NSString*)lookupKeyForAsset:(NSString*)asset fromPackage:(NSString*)package;
379 @end
380 
381 #pragma mark -
382 /**
383  * A registry of Flutter iOS plugins.
384  *
385  * Plugins are identified by unique string keys, typically the name of the
386  * plugin's main class. The registry tracks plugins by this key, mapping it to
387  * a value published by the plugin during registration, if any. This provides a
388  * very basic means of cross-plugin coordination with loose coupling between
389  * unrelated plugins.
390  *
391  * Plugins typically need contextual information and the ability to register
392  * callbacks for various application events. To keep the API of the registry
393  * focused, these facilities are not provided directly by the registry, but by
394  * a `FlutterPluginRegistrar`, created by the registry in exchange for the unique
395  * key of the plugin.
396  *
397  * There is no implied connection between the registry and the registrar.
398  * Specifically, callbacks registered by the plugin via the registrar may be
399  * relayed directly to the underlying iOS application objects.
400  */
401 @protocol FlutterPluginRegistry <NSObject>
402 /**
403  * Returns a registrar for registering a plugin.
404  *
405  * @param pluginKey The unique key identifying the plugin.
406  */
407 - (nullable NSObject<FlutterPluginRegistrar>*)registrarForPlugin:(NSString*)pluginKey;
408 /**
409  * Returns whether the specified plugin has been registered.
410  *
411  * @param pluginKey The unique key identifying the plugin.
412  * @return `YES` if `registrarForPlugin` has been called with `pluginKey`.
413  */
414 - (BOOL)hasPlugin:(NSString*)pluginKey;
415 
416 /**
417  * Returns a value published by the specified plugin.
418  *
419  * @param pluginKey The unique key identifying the plugin.
420  * @return An object published by the plugin, if any. Will be `NSNull` if
421  * nothing has been published. Will be `nil` if the plugin has not been
422  * registered.
423  */
424 - (nullable NSObject*)valuePublishedByPlugin:(NSString*)pluginKey;
425 @end
426 
427 #pragma mark -
428 /**
429  * Implement this in the `UIAppDelegate` of your app to enable Flutter plugins to register
430  * themselves to the application life cycle events.
431  *
432  * For plugins to receive events from `UNUserNotificationCenter`, register this as the
433  * `UNUserNotificationCenterDelegate`.
434  */
435 @protocol FlutterAppLifeCycleProvider
436 #if __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_10_0
437  <UNUserNotificationCenterDelegate>
438 #endif
439 
440 /**
441  * Called when registering a new `FlutterApplicaitonLifeCycleDelegate`.
442  *
443  * See also: `-[FlutterAppDelegate addApplicationLifeCycleDelegate:]`
444  */
445 - (void)addApplicationLifeCycleDelegate:(NSObject<FlutterApplicationLifeCycleDelegate>*)delegate;
446 @end
447 
449 
450 #endif // FLUTTER_FLUTTERPLUGIN_H_
#define NS_ASSUME_NONNULL_END
Definition: FlutterMacros.h:20
GAsyncResult * result
#define NS_ASSUME_NONNULL_BEGIN
Definition: FlutterMacros.h:19
void(^ FlutterResult)(id _Nullable result)
FlutterPlatformViewGestureRecognizersBlockingPolicy
int BOOL
Definition: windows_types.h:37
void(* FlutterPluginRegistrantCallback)(NSObject< FlutterPluginRegistry > *registry)