| Flutter Windows Embedder |

flutter_messenger.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_SHELL_PLATFORM_COMMON_PUBLIC_FLUTTER_MESSENGER_H_
6 #define FLUTTER_SHELL_PLATFORM_COMMON_PUBLIC_FLUTTER_MESSENGER_H_
7
8 #include <stdbool.h>
9 #include <stddef.h>
10 #include <stdint.h>
11
12 #include "flutter_export.h"
13
14 #if defined(__cplusplus)
15 extern "C" {
16 #endif // defined(__cplusplus)
17
18 // Opaque reference to a Flutter engine messenger.
19 typedef struct FlutterDesktopMessenger* FlutterDesktopMessengerRef;
20
21 // Opaque handle for tracking responses to messages.
22 typedef struct _FlutterPlatformMessageResponseHandle
23 FlutterDesktopMessageResponseHandle;
24
25 // The callback expected as a response of a binary message.
26 typedef void (*FlutterDesktopBinaryReply)(const uint8_t* data,
27 size_t data_size,
28 void* user_data);
29
30 // A message received from Flutter.
31 typedef struct {
32 // Size of this struct as created by Flutter.
33 size_t struct_size;
34 // The name of the channel used for this message.
35 const char* channel;
36 // The raw message data.
37 const uint8_t* message;
38 // The length of |message|.
39 size_t message_size;
40 // The response handle. If non-null, the receiver of this message must call
41 // FlutterDesktopSendMessageResponse exactly once with this handle.
42 const FlutterDesktopMessageResponseHandle* response_handle;
43 } FlutterDesktopMessage;
44
45 // Function pointer type for message handler callback registration.
46 //
47 // The user data will be whatever was passed to FlutterDesktopSetMessageHandler
48 // for the channel the message is received on.
49 typedef void (*FlutterDesktopMessageCallback)(
50 FlutterDesktopMessengerRef /* messenger */,
51 const FlutterDesktopMessage* /* message*/,
52 void* /* user data */);
53
54 // Sends a binary message to the Flutter side on the specified channel.
55 FLUTTER_EXPORT bool FlutterDesktopMessengerSend(
56 FlutterDesktopMessengerRef messenger,
57 const char* channel,
58 const uint8_t* message,
59 const size_t message_size);
60
61 // Sends a binary message to the Flutter side on the specified channel.
62 // The |reply| callback will be executed when a response is received.
63 FLUTTER_EXPORT bool FlutterDesktopMessengerSendWithReply(
64 FlutterDesktopMessengerRef messenger,
65 const char* channel,
66 const uint8_t* message,
67 const size_t message_size,
68 const FlutterDesktopBinaryReply reply,
69 void* user_data);
70
71 // Sends a reply to a FlutterDesktopMessage for the given response handle.
72 //
73 // Once this has been called, |handle| is invalid and must not be used again.
74 FLUTTER_EXPORT void FlutterDesktopMessengerSendResponse(
75 FlutterDesktopMessengerRef messenger,
76 const FlutterDesktopMessageResponseHandle* handle,
77 const uint8_t* data,
78 size_t data_length);
79
80 // Registers a callback function for incoming binary messages from the Flutter
81 // side on the specified channel.
82 //
83 // Replaces any existing callback. Provide a null handler to unregister the
84 // existing callback.
85 //
86 // If |user_data| is provided, it will be passed in |callback| calls.
87 FLUTTER_EXPORT void FlutterDesktopMessengerSetCallback(
88 FlutterDesktopMessengerRef messenger,
89 const char* channel,
90 FlutterDesktopMessageCallback callback,
91 void* user_data);
92
93 // Increments the reference count for the |messenger|.
94 //
95 // Operation is thread-safe.
96 //
97 // See also: |FlutterDesktopMessengerRelease|
98 FLUTTER_EXPORT FlutterDesktopMessengerRef FlutterDesktopMessengerAddRef(
99 FlutterDesktopMessengerRef messenger);
100
101 // Decrements the reference count for the |messenger|.
102 //
103 // Operation is thread-safe.
104 //
105 // See also: |FlutterDesktopMessengerAddRef|
106 FLUTTER_EXPORT void FlutterDesktopMessengerRelease(
107 FlutterDesktopMessengerRef messenger);
108
109 // Returns `true` if the |FlutterDesktopMessengerRef| still references a running
110 // engine.
111 //
112 // This check should be made inside of a |FlutterDesktopMessengerLock| and
113 // before any other calls are made to the FlutterDesktopMessengerRef when using
114 // it from a thread other than the platform thread.
115 FLUTTER_EXPORT bool FlutterDesktopMessengerIsAvailable(
116 FlutterDesktopMessengerRef messenger);
117
118 // Locks the `FlutterDesktopMessengerRef` ensuring that
119 // |FlutterDesktopMessengerIsAvailable| does not change while locked.
120 //
121 // All calls to the FlutterDesktopMessengerRef from threads other than the
122 // platform thread should happen inside of a lock.
123 //
124 // Operation is thread-safe.
125 //
126 // Returns the |messenger| value.
127 //
128 // See also: |FlutterDesktopMessengerUnlock|
129 FLUTTER_EXPORT FlutterDesktopMessengerRef FlutterDesktopMessengerLock(
130 FlutterDesktopMessengerRef messenger);
131
132 // Unlocks the `FlutterDesktopMessengerRef`.
133 //
134 // Operation is thread-safe.
135 //
136 // See also: |FlutterDesktopMessengerLock|
137 FLUTTER_EXPORT void FlutterDesktopMessengerUnlock(
138 FlutterDesktopMessengerRef messenger);
139
140 #if defined(__cplusplus)
141 } // extern "C"
142 #endif
143
144 #endif // FLUTTER_SHELL_PLATFORM_COMMON_PUBLIC_FLUTTER_MESSENGER_H_
FlutterDesktopMessengerAddRef
FLUTTER_EXPORT FlutterDesktopMessengerRef FlutterDesktopMessengerAddRef(FlutterDesktopMessengerRef messenger)
Definition: flutter_windows.cc:396
FlutterDesktopMessengerUnlock
FLUTTER_EXPORT void FlutterDesktopMessengerUnlock(FlutterDesktopMessengerRef messenger)
Definition: flutter_windows.cc:418
FlutterDesktopBinaryReply
void(* FlutterDesktopBinaryReply)(const uint8_t *data, size_t data_size, void *user_data)
Definition: flutter_messenger.h:26
user_data
void * user_data
Definition: flutter_windows_view_unittests.cc:53
FLUTTER_EXPORT
#define FLUTTER_EXPORT
Definition: flutter_export.h:23
FlutterDesktopMessengerSendWithReply
FLUTTER_EXPORT bool FlutterDesktopMessengerSendWithReply(FlutterDesktopMessengerRef messenger, const char *channel, const uint8_t *message, const size_t message_size, const FlutterDesktopBinaryReply reply, void *user_data)
Definition: flutter_windows.cc:348
FlutterDesktopMessageResponseHandle
struct _FlutterPlatformMessageResponseHandle FlutterDesktopMessageResponseHandle
Definition: flutter_messenger.h:22
FlutterDesktopMessengerSetCallback
FLUTTER_EXPORT void FlutterDesktopMessengerSetCallback(FlutterDesktopMessengerRef messenger, const char *channel, FlutterDesktopMessageCallback callback, void *user_data)
Definition: flutter_windows.cc:383
FlutterDesktopMessage::message_size
size_t message_size
Definition: flutter_messenger.h:39
FlutterDesktopMessengerRelease
FLUTTER_EXPORT void FlutterDesktopMessengerRelease(FlutterDesktopMessengerRef messenger)
Definition: flutter_windows.cc:403
FlutterDesktopMessengerSendResponse
FLUTTER_EXPORT void FlutterDesktopMessengerSendResponse(FlutterDesktopMessengerRef messenger, const FlutterDesktopMessageResponseHandle *handle, const uint8_t *data, size_t data_length)
Definition: flutter_windows.cc:370
FlutterDesktopMessengerLock
FLUTTER_EXPORT FlutterDesktopMessengerRef FlutterDesktopMessengerLock(FlutterDesktopMessengerRef messenger)
Definition: flutter_windows.cc:412
flutter_export.h
FlutterDesktopMessengerSend
FLUTTER_EXPORT bool FlutterDesktopMessengerSend(FlutterDesktopMessengerRef messenger, const char *channel, const uint8_t *message, const size_t message_size)
Definition: flutter_windows.cc:362
FlutterDesktopMessengerRef
struct FlutterDesktopMessenger * FlutterDesktopMessengerRef
Definition: flutter_messenger.h:19
FlutterDesktopMessage
Definition: flutter_messenger.h:31
FlutterDesktopMessage::channel
const char * channel
Definition: flutter_messenger.h:35
message
Win32Message message
Definition: keyboard_unittests.cc:137
FlutterDesktopMessage::response_handle
const FlutterDesktopMessageResponseHandle * response_handle
Definition: flutter_messenger.h:42
FlutterDesktopMessengerIsAvailable
FLUTTER_EXPORT bool FlutterDesktopMessengerIsAvailable(FlutterDesktopMessengerRef messenger)
Definition: flutter_windows.cc:407
FlutterDesktopMessage::message
const uint8_t * message
Definition: flutter_messenger.h:37
FlutterDesktopMessageCallback
void(* FlutterDesktopMessageCallback)(FlutterDesktopMessengerRef, const FlutterDesktopMessage *, void *)
Definition: flutter_messenger.h:49
FlutterDesktopMessage::struct_size
size_t struct_size
Definition: flutter_messenger.h:33
callback
FlutterDesktopBinaryReply callback
Definition: flutter_windows_view_unittests.cc:52