/core/externals/update-engine/externals/google-toolbox-for-mac/Foundation/GTMTransientRootProxy.h

  1//
  2//  GTMTransientRootProxy.h
  3//
  4//  Copyright 2006-2009 Google Inc.
  5//
  6//  Licensed under the Apache License, Version 2.0 (the "License"); you may not
  7//  use this file except in compliance with the License.  You may obtain a copy
  8//  of the License at
  9//
 10//  http://www.apache.org/licenses/LICENSE-2.0
 11//
 12//  Unless required by applicable law or agreed to in writing, software
 13//  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 14//  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
 15//  License for the specific language governing permissions and limitations under
 16//  the License.
 17//
 18
 19#import <Foundation/Foundation.h>
 20
 21// Handle (re-)connecting to a transient root proxy object via DO.
 22//
 23// This class is designed to handle connecting and reconnecting to a Distributed
 24// Objects root proxy (NSDistantObject* instance). It is a replacement for using
 25// the NSDistantObject returned from NSConnection, directly. When the DO
 26// connection is up, messages sent to this class are forwarded to the real
 27// object (the NSDistantObject); when the DO connection is down, messages sent
 28// to this class are silently swallowed. You can use the -isConnected method on
 29// this class to see if the DO connection is up or down.
 30//
 31// This class may be useful when you need a DO connection, but the
 32// server you're connected to may be going up and down.  For example, the 
 33// web browser plugins in Google Desktop may need to connect to the Google
 34// Desktop local webserver, but we'd want the browser plugins to be able to
 35// gracefully handle the local Google Desktop webserver starting and stopping.
 36//
 37// === Example Usage ===
 38//
 39// Old code:
 40//
 41// NSDistantObject<MyProto> *o =
 42//   [NSConnection rootProxyForConnectionWithRegisteredName:@"server"
 43//                                                     host:nil];
 44// [o setProtocolForProxy:@protocol(MyProto)];
 45// [o someMethodInMyProto];
 46// // ... write a bunch of code to handle error conditions
 47//
 48// New code:
 49//
 50// GTMTransientRootProxy<MyProto> *o =
 51//   [GTMTransientRootProxy rootProxyWithRegisteredName:@"server"
 52//                                                 host:nil
 53//                                             protocol:@protocol(MyProto)
 54//                                       requestTimeout:5.0
 55//                                         replyTimeout:5.0];
 56// [o someMethodInMyProto];
 57//
 58// The 'Old code' requires you to handle all the error conditions that may
 59// arise when using DO (such as the server crashing, or network going down),
 60// handle properly tearing down the broken connection, and trying to reconnect
 61// when the server finally comes back online.  The 'New code' handles all of
 62// those details for you.
 63//
 64// Also, when creating a GMTransientRootProxy object, you must tell it the
 65// @protocol that will be used for communication - this is not optional.  And
 66// in order to quiet compiler warnings, you'll also want to staticly type
 67// the pointer with the protocol as well.
 68//
 69@interface GTMTransientRootProxy : NSProxy {
 70 @protected
 71  __weak Protocol *protocol_;
 72  NSDistantObject *realProxy_;
 73
 74  NSString *registeredName_;
 75  NSString *host_;
 76
 77  NSTimeInterval requestTimeout_;
 78  NSTimeInterval replyTimeout_;
 79}
 80
 81// Returns an autoreleased instance
 82+ (id)rootProxyWithRegisteredName:(NSString *)name
 83                             host:(NSString *)host
 84                         protocol:(Protocol *)protocol
 85                   requestTimeout:(NSTimeInterval)requestTimeout
 86                     replyTimeout:(NSTimeInterval)replyTimeout;
 87
 88// This function will return a GTMTransientRootProxy that is using Mach ports
 89// for the connection.  The |name| and |host| arguments will be used to lookup
 90// the correct information to create the Mach port connection.
 91//
 92- (id)initWithRegisteredName:(NSString *)name
 93                        host:(NSString *)host
 94                    protocol:(Protocol *)protocol
 95              requestTimeout:(NSTimeInterval)requestTimeout
 96                replyTimeout:(NSTimeInterval)replyTimeout;
 97
 98// Returns YES if the DO connection is up and working, NO otherwise.
 99//
100- (BOOL)isConnected;
101
102@end
103
104// Subclass of GTMTransientRootProxy that catches and ignores ALL exceptions.
105// This class overrides GTMTransientRootProxy's -forwardInvocation:
106// method, and wraps it in a try/catch block, and ignores all exceptions.
107//
108@interface GTMRootProxyCatchAll : GTMTransientRootProxy
109
110// Overridden, and ignores all thrown exceptions.
111- (void)forwardInvocation:(NSInvocation *)invocation;
112
113@end