1 // Copyright 2021 gRPC authors. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef GRPCPP_CREATE_CHANNEL_BINDER_H 16 #define GRPCPP_CREATE_CHANNEL_BINDER_H 17 18 #include <grpc/support/port_platform.h> 19 20 #ifdef GPR_ANDROID 21 22 #include <jni.h> 23 24 #include <memory> 25 26 #include "absl/strings/string_view.h" 27 28 #include <grpcpp/channel.h> 29 #include <grpcpp/security/binder_security_policy.h> 30 #include <grpcpp/support/channel_arguments.h> 31 32 namespace grpc { 33 namespace experimental { 34 35 /// EXPERIMENTAL Create a new \a Channel based on binder transport. The package 36 /// name and class name will be used identify the specific application component 37 /// to connect to. 38 /// 39 /// \param jni_env_void Pointer to a JNIEnv structure 40 /// \param context The context that we will use to invoke \a bindService See 41 /// https://developer.android.com/reference/android/content/Context#bindService(android.content.Intent,%20android.content.ServiceConnection,%20int) 42 /// for detail. 43 /// \param package_name Package name of the component to be connected to 44 /// \param class_name Class name of the component to be connected to 45 /// \param security_policy Used for checking if remote component is allowed to 46 /// connect 47 std::shared_ptr<grpc::Channel> CreateBinderChannel( 48 void* jni_env_void, jobject context, absl::string_view package_name, 49 absl::string_view class_name, 50 std::shared_ptr<grpc::experimental::binder::SecurityPolicy> 51 security_policy); 52 53 /// EXPERIMENTAL Create a new \a Channel based on binder transport. The package 54 /// name and class name will be used identify the specific application component 55 /// to connect to. 56 /// 57 /// \param jni_env_void Pointer to a JNIEnv structure 58 /// \param context The context that we will use to invoke \a bindService See 59 /// https://developer.android.com/reference/android/content/Context#bindService(android.content.Intent,%20android.content.ServiceConnection,%20int) 60 /// for detail. 61 /// \param package_name Package name of the component to be connected to 62 /// \param class_name Class name of the component to be connected to 63 /// \param security_policy Used for checking if remote component is allowed to 64 /// connect 65 /// \param args Options for channel creation. 66 std::shared_ptr<grpc::Channel> CreateCustomBinderChannel( 67 void* jni_env_void, jobject context, absl::string_view package_name, 68 absl::string_view class_name, 69 std::shared_ptr<grpc::experimental::binder::SecurityPolicy> security_policy, 70 const ChannelArguments& args); 71 72 /// EXPERIMENTAL Create a new \a Channel based on binder transport. 73 /// 74 /// \param jni_env_void Pointer to a JNIEnv structure 75 /// \param context The context that we will use to invoke \a bindService See 76 /// https://developer.android.com/reference/android/content/Context#bindService(android.content.Intent,%20android.content.ServiceConnection,%20int) 77 /// for detail. 78 /// \param uri An URI that can be parsed as an `Intent` with 79 /// https://developer.android.com/reference/android/content/Intent#parseUri(java.lang.String,%20int) 80 /// \param security_policy Used for checking if remote component is allowed to 81 /// connect 82 std::shared_ptr<grpc::Channel> CreateBinderChannel( 83 void* jni_env_void, jobject context, absl::string_view uri, 84 std::shared_ptr<grpc::experimental::binder::SecurityPolicy> 85 security_policy); 86 87 /// EXPERIMENTAL Create a new \a Channel based on binder transport. 88 /// 89 /// \param jni_env_void Pointer to a JNIEnv structure 90 /// \param context The context that we will use to invoke \a bindService See 91 /// https://developer.android.com/reference/android/content/Context#bindService(android.content.Intent,%20android.content.ServiceConnection,%20int) 92 /// for detail. 93 /// \param uri An URI that can be parsed as an `Intent` with 94 /// https://developer.android.com/reference/android/content/Intent#parseUri(java.lang.String,%20int) 95 /// \param security_policy Used for checking if remote component is allowed to 96 /// connect 97 /// \param args Options for channel creation. 98 std::shared_ptr<grpc::Channel> CreateCustomBinderChannel( 99 void* jni_env_void, jobject context, absl::string_view uri, 100 std::shared_ptr<grpc::experimental::binder::SecurityPolicy> security_policy, 101 const ChannelArguments& args); 102 103 /// EXPERIMENTAL Finds internal binder transport Java code. To create channels 104 /// in threads created in native code, it is required to call this function 105 /// once beforehand in a thread that is not created in native code. 106 /// See 107 /// https://developer.android.com/training/articles/perf-jni#faq:-why-didnt-findclass-find-my-class 108 /// for details of this limitation. 109 /// Returns true when the initialization is successful. 110 bool InitializeBinderChannelJavaClass(void* jni_env_void); 111 112 /// EXPERIMENTAL Alternative version of `InitializeBinderChannelJavaClass(void* 113 /// jni_env_void)`. This version used a user-specified function to find the 114 /// required internal Java class. When a class is found, the `class_finder` 115 /// function should return a local reference to the class (jclass type). The 116 /// returned jclass will then be used to create global reference for gRPC to use 117 /// it later. After that, gRPC will DeleteLocalRef the returned local reference. 118 bool InitializeBinderChannelJavaClass( 119 void* jni_env_void, std::function<void*(std::string)> class_finder); 120 121 } // namespace experimental 122 } // namespace grpc 123 124 #endif 125 126 #endif // GRPCPP_CREATE_CHANNEL_BINDER_H 127