| // | |
| // Copyright 2018 Google Inc. | |
| // | |
| // Licensed under the Apache License, Version 2.0 (the "License"); | |
| // you may not use this file except in compliance with the License. | |
| // You may obtain a copy of the License at | |
| // | |
| // http://www.apache.org/licenses/LICENSE-2.0 | |
| // | |
| // Unless required by applicable law or agreed to in writing, software | |
| // distributed under the License is distributed on an "AS IS" BASIS, | |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| // See the License for the specific language governing permissions and | |
| // limitations under the License. | |
| // | |
| #import <Foundation/Foundation.h> | |
| #import <os/availability.h> | |
| NS_ASSUME_NONNULL_BEGIN | |
| @class EDOHostNamingService; | |
| @class EDOHostPort; | |
| /** The error handler for handling errors generated when sending client requests. */ | |
| typedef void (^EDOClientErrorHandler)(NSError *_Nonnull); | |
| /** | |
| * Sets the error handler for the client, and returns the error handler that is previously set for | |
| * the client. The procedure is thread-safe. | |
| * | |
| * The handler will be invoked if there is an error when sending a request. The default handler | |
| * throws an EDOServiceGenericException for any reported error. The exception's user info contains | |
| * the entry EDOUnderlyingErrorKey that embeds the @c NSError object. | |
| * | |
| * @param errorHandler The error handler to be used for the client. If it's @c nil, the default | |
| * handler will be used. | |
| * | |
| * @return The old error handler that is set for the client previously, or the default handler | |
| * if it get called the first time. | |
| */ | |
| FOUNDATION_EXTERN EDOClientErrorHandler | |
| EDOSetClientErrorHandler(EDOClientErrorHandler _Nullable errorHandler); | |
| /** | |
| * The EDOClientService manages the communication to the remote objects in remote process. | |
| * | |
| * The service manages the distant objects fetched from remote process. It provides API to make | |
| * remote invocation to a @c EDOHostService running in the remote process. | |
| */ | |
| @interface EDOClientService<ObjectType> : NSObject | |
| /** | |
| * Gets the root object on the host port. | |
| * | |
| * @param hostPort The host port the service is running on. | |
| * @return The remote root object. | |
| */ | |
| + (ObjectType)rootObjectWithHostPort:(EDOHostPort *)hostPort; | |
| /** | |
| * Gets the remote class object on the host port. | |
| * | |
| * @param className The class name. | |
| * @param hostPort The host port the service is running on. | |
| * @return The remote @c Class object. | |
| */ | |
| + (nullable Class)classObjectWithName:(NSString *)className hostPort:(EDOHostPort *)hostPort; | |
| - (instancetype)init NS_UNAVAILABLE; | |
| /** | |
| * Determines if an @c EDOHostService is listening on @c port. | |
| * | |
| * @param port The port to check if an @c EDOHostService is listening on. | |
| * @return @c YES if an @c EDOHostService is listening on @c port and it is safe to connect, @c NO | |
| * otherwise. | |
| */ | |
| + (BOOL)isServiceAvailableOnPort:(UInt16)port; | |
| #pragma mark - Deprecated APIs | |
| /** Retrieve the root object from the given host port of a service. */ | |
| + (ObjectType)rootObjectWithPort:(UInt16)port; | |
| /** Retrieve the root object from the given name of a service. */ | |
| + (ObjectType)rootObjectWithServiceName:(NSString *)serviceName; | |
| /** Retrieve the class object from the given host port of a service. */ | |
| + (nullable Class)classObjectWithName:(NSString *)className port:(UInt16)port; | |
| /** Retrieve the class object from the given host port of and name of a service. */ | |
| + (nullable Class)classObjectWithName:(NSString *)className serviceName:(NSString *)serviceName; | |
| @end | |
| /** The device support methods for @c EDOClientService. */ | |
| @interface EDOClientService (Device) | |
| /** | |
| * Fetches the naming service remote instance running on the physical device with given device | |
| * @c serial synchronously. | |
| * | |
| * @note This is used to get the service's listen port on the host side by service name. | |
| */ | |
| + (EDOHostNamingService *)namingServiceWithDeviceSerial:(NSString *)serial | |
| error:(NSError *_Nullable *_Nullable)error; | |
| @end | |
| /** | |
| * Checks if @c object is an eDO proxy. | |
| * | |
| * @param object The object that performs the type check. | |
| * | |
| * @return @c YES if it's an eDO proxy; @c NO otherwise. | |
| */ | |
| FOUNDATION_EXTERN BOOL EDOIsRemoteObject(id object); | |
| NS_ASSUME_NONNULL_END | |
| /** | |
| * Stub the class implementation so it can resolve symbol lookup errors for the class methods. | |
| * | |
| * The linker can't resolve class symbols when it compiles the class method statically. This macro | |
| * helps to generate the stub implementation where it forwards the class method to the remote | |
| * class object. | |
| * | |
| * @note This is generally not encouraged because this could cause retain/release imbalance | |
| * if not used properly. For example, custom ns_returns_retained will not be | |
| * captured at runtime and may lead to a memory crash. This is useful if only the class | |
| * methods are used and any method from the +alloc, +new, +copy, and mutableCopy methods | |
| * families are not used. | |
| * | |
| * @note +allocWithZone: is forwarded. +alloc is not forwarded as it calls into the forwarded | |
| * method +allocWithZone: for historical reasons. | |
| * https://developer.apple.com/documentation/objectivec/nsobject/1571958-alloc?language=objc | |
| * | |
| * @param __class The class literal. | |
| * @param __port The port that the service listens on. | |
| */ | |
| // TODO(haowoo): Cache the class object when we can know when the service is invalid. | |
| // Refer to https://clang.llvm.org/docs/DiagnosticsReference.html for information about the | |
| // ignored flags. | |
| // TODO(ynzhang): Remove clang-format switch when b/78026272 is resolved. | |
| // clang-format off | |
| #define EDO_STUB_CLASS(__class, __port) \ | |
| _Pragma("clang diagnostic push") \ | |
| _Pragma("clang diagnostic ignored \"-Wincomplete-implementation\"") \ | |
| _Pragma("clang diagnostic ignored \"-Wprotocol\"") \ | |
| _Pragma("clang diagnostic ignored \"-Wobjc-property-implementation\"") \ | |
| _Pragma("clang diagnostic ignored \"-Wobjc-protocol-property-synthesis\"") \ | |
| \ | |
| @implementation __class \ | |
| \ | |
| + (id)forwardingTargetForSelector:(SEL)sel { \ | |
| return [EDOClientService classObjectWithName:@""#__class port:(__port)]; \ | |
| } \ | |
| \ | |
| + (instancetype)allocWithZone:(NSZone *)zone { \ | |
| id instance = [self forwardingTargetForSelector:@selector(alloc)]; \ | |
| return [instance alloc]; \ | |
| } \ | |
| \ | |
| @end \ | |
| _Pragma("clang diagnostic pop") | |
| // clang-format on | |
| /** | |
| * Fetch the remote class type. | |
| * | |
| * When the stub is not used and the reference to the remote class is needed, this method can do | |
| * the type checking and bypass the symbol lookup. | |
| * | |
| * @note The explicit conversion is used to have the compiler check the spelling because it | |
| * converts the class literal into a NSString. | |
| * | |
| * @param __class The class literal | |
| * @param __port The port that the service listens on. | |
| */ | |
| #define EDO_REMOTE_CLASS(__class, __port) \ | |
| ((Class)(__class *)[EDOClientService classObjectWithName:@"" #__class port:(__port)]) |