1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/BLIP/BLIPRequest.h	Sat May 24 13:26:02 2008 -0700
     1.3 @@ -0,0 +1,101 @@
     1.4 +//
     1.5 +//  BLIPRequest.h
     1.6 +//  MYNetwork
     1.7 +//
     1.8 +//  Created by Jens Alfke on 5/22/08.
     1.9 +//  Copyright 2008 Jens Alfke. All rights reserved.
    1.10 +//
    1.11 +
    1.12 +#import "BLIPMessage.h"
    1.13 +@class BLIPResponse, MYTarget;
    1.14 +
    1.15 +
    1.16 +/** A Request, or initiating message. */
    1.17 +@interface BLIPRequest : BLIPMessage
    1.18 +{
    1.19 +    @private
    1.20 +    BLIPResponse *_response;
    1.21 +}
    1.22 +
    1.23 +/** Creates an outgoing request.
    1.24 +    The body may be nil.
    1.25 +    The request is not associated with any BLIPConnection yet, so you must either set its
    1.26 +    connection property before calling -send, or pass the request as a parameter to
    1.27 +    -[BLIPConnection sendRequest:]. */
    1.28 ++ (BLIPRequest*) requestWithBody: (NSData*)body;
    1.29 +
    1.30 +/** Creates an outgoing request.
    1.31 +    The body or properties may be nil.
    1.32 +    The request is not associated with any BLIPConnection yet, so you must either set its
    1.33 +    connection property before calling -send, or pass the request as a parameter to
    1.34 +    -[BLIPConnection sendRequest:]. */
    1.35 ++ (BLIPRequest*) requestWithBody: (NSData*)body
    1.36 +                      properties: (NSDictionary*)properties;
    1.37 +
    1.38 +/** BLIPRequest extends the -connection property to be settable.
    1.39 +    This allows a request to be created without a connection (i.e. before the connection is created).
    1.40 +    It can later be sent by setting the connection property and calling -send. */
    1.41 +@property (retain) BLIPConnection *connection;
    1.42 +
    1.43 +/** Sends this request over its connection.
    1.44 +    (Actually, the connection queues it to be sent; this method always returns immediately.)
    1.45 +    If this request has not been assigned to a connection, an exception will be raised.
    1.46 +    Its matching response object will be returned, or nil if the request couldn't be sent. */
    1.47 +- (BLIPResponse*) send;
    1.48 +
    1.49 +/** Does this request not need a response?
    1.50 +    This property can only be set before sending the request. */
    1.51 +@property BOOL noReply;
    1.52 +
    1.53 +/** Returns YES if you've replied to this request (by accessing its -response property.) */
    1.54 +@property (readonly) BOOL repliedTo;
    1.55 +
    1.56 +/** The request's response. This can be accessed at any time, even before sending the request,
    1.57 +    but the contents of the response won't be filled in until it arrives, of course. */
    1.58 +@property (readonly) BLIPResponse *response;
    1.59 +
    1.60 +/** Call this when a request arrives, to indicate that you want to respond to it later.
    1.61 +    It will prevent a default empty response from being sent upon return from the request handler. */
    1.62 +- (void) deferResponse;
    1.63 +
    1.64 +/** Shortcut to respond to this request with the given data. */
    1.65 +- (void) respondWithData: (NSData*)data;
    1.66 +
    1.67 +/** Shortcut to respond to this request with the given string (which will be encoded in UTF-8). */
    1.68 +- (void) respondWithString: (NSString*)string;
    1.69 +
    1.70 +/** Shortcut to respond to this request with an error. */
    1.71 +- (void) respondWithError: (NSError*)error;
    1.72 +
    1.73 +/** Shortcut to respond to this request with the given error code and message.
    1.74 +    The BLIPErrorDomain is assumed. */
    1.75 +- (void) respondWithErrorCode: (int)code message: (NSString*)message; //, ... __attribute__ ((format (__NSString__, 2,3)));;
    1.76 +
    1.77 +/** Shortcut to respond to this message with an error indicating that an exception occurred. */
    1.78 +- (void) respondWithException: (NSException*)exception;
    1.79 +
    1.80 +@end
    1.81 +
    1.82 +
    1.83 +
    1.84 +
    1.85 +/** A reply to a BLIPRequest. */
    1.86 +@interface BLIPResponse : BLIPMessage
    1.87 +{
    1.88 +    @private
    1.89 +    NSError *_error;
    1.90 +    MYTarget *_onComplete;
    1.91 +}
    1.92 +
    1.93 +/** Sends this response. */
    1.94 +- (BOOL) send;
    1.95 +
    1.96 +/** The error returned by the peer, or nil if the response is successful. */
    1.97 +@property (retain) NSError* error;
    1.98 +
    1.99 +/** Sets a target/action to be called when an incoming response is complete.
   1.100 +    Use this on the response returned from -[BLIPRequest send], to be notified when the response is available. */
   1.101 +@property (retain) MYTarget *onComplete;
   1.102 +
   1.103 +
   1.104 +@end