* The BLIPConnection receivedRequest: delegate method now returns BOOL. If the method returns NO (or if the method isn't implemented in the delegate), that means it didn't handle the message at all; an error will be returned to the sender.
* If the connection closes unexpectedly due to an error, then the auto-generated responses to pending requests will contain that error. This makes it easier to display a meaningful error message in the handler for the request.
5 // Created by Jens Alfke on 5/15/08.
6 // Copyright 2008 Jens Alfke. All rights reserved.
9 #import <Foundation/Foundation.h>
10 @class MYTarget, BLIPMessage;
13 /** Routes BLIP messages to targets based on a series of rules.
15 Every BLIPConnection has a BLIPDispatcher, which is initially empty, but you can add rules
18 Every BLIPListener also has a dispatcher, which is inherited as the parent by every
19 connection that it accepts, so you can add rules to the listener's dispatcher to share them
20 between all connections.
22 It's not necessary to use a dispatcher. Any undispatched requests will be sent to the
23 BLIPConnection's delegate's -connection:receivedRequest: method, which can do its own
24 custom handling. But it's often easier to use the dispatcher to associate handlers with
25 request based on property values. */
26 @interface BLIPDispatcher : NSObject
29 NSMutableArray *_predicates, *_targets;
30 BLIPDispatcher *_parent;
33 /** The inherited parent dispatcher.
34 If a message does not match any of this dispatcher's rules, it will next be passed to
35 the parent, if there is one. */
36 @property (retain) BLIPDispatcher *parent;
38 /** Convenience method that adds a rule that compares a property against a string. */
39 - (void) addTarget: (MYTarget*)target forValueOfProperty: (NSString*)value forKey: (NSString*)key;
41 #if ! TARGET_OS_IPHONE /* NSPredicate is not available on iPhone, unfortunately */
42 /** Adds a new rule, to call a given target method if a given predicate matches the message. */
43 - (void) addTarget: (MYTarget*)target forPredicate: (NSPredicate*)predicate;
46 /** Removes all rules with the given target method. */
47 - (void) removeTarget: (MYTarget*)target;
49 /** Tests the message against all the rules, in the order they were added, and calls the
50 target of the first matching rule.
51 If no rule matches, the message is passed to the parent dispatcher's -dispatchMessage:,
53 If no rules at all match, NO is returned. */
54 - (BOOL) dispatchMessage: (BLIPMessage*)message;
56 /** Returns a target object that will call this dispatcher's -dispatchMessage: method.
57 This can be used to make this dispatcher the target of another dispatcher's rule,
58 stringing them together hierarchically. */
59 - (MYTarget*) asTarget;