jens@0: //
jens@0: //  BLIPRequest.h
jens@0: //  MYNetwork
jens@0: //
jens@0: //  Created by Jens Alfke on 5/22/08.
jens@0: //  Copyright 2008 Jens Alfke. All rights reserved.
jens@0: //
jens@0: 
jens@0: #import "BLIPMessage.h"
jens@0: @class BLIPResponse, MYTarget;
jens@0: 
jens@0: 
jens@5: /** A Request, or initiating message, in the <a href=".#blipdesc">BLIP</a> protocol. */
jens@49: @interface BLIPRequest : BLIPMessage <NSMutableCopying>
jens@0: {
jens@0:     @private
jens@0:     BLIPResponse *_response;
jens@0: }
jens@0: 
jens@0: /** Creates an outgoing request.
jens@0:     The body may be nil.
jens@0:     The request is not associated with any BLIPConnection yet, so you must either set its
jens@0:     connection property before calling -send, or pass the request as a parameter to
jens@0:     -[BLIPConnection sendRequest:]. */
jens@0: + (BLIPRequest*) requestWithBody: (NSData*)body;
jens@0: 
jens@0: /** Creates an outgoing request.
jens@49:     This is just like requestWithBody: except that you supply a string. */
jens@49: + (BLIPRequest*) requestWithBodyString: (NSString*)bodyString;
jens@49: 
jens@49: /** Creates an outgoing request.
jens@0:     The body or properties may be nil.
jens@0:     The request is not associated with any BLIPConnection yet, so you must either set its
jens@0:     connection property before calling -send, or pass the request as a parameter to
jens@0:     -[BLIPConnection sendRequest:]. */
jens@0: + (BLIPRequest*) requestWithBody: (NSData*)body
jens@0:                       properties: (NSDictionary*)properties;
jens@0: 
jens@0: /** BLIPRequest extends the -connection property to be settable.
jens@0:     This allows a request to be created without a connection (i.e. before the connection is created).
jens@0:     It can later be sent by setting the connection property and calling -send. */
jens@0: @property (retain) BLIPConnection *connection;
jens@0: 
jens@0: /** Sends this request over its connection.
jens@0:     (Actually, the connection queues it to be sent; this method always returns immediately.)
jens@2:     Its matching response object will be returned, or nil if the request couldn't be sent.
jens@2:     If this request has not been assigned to a connection, an exception will be raised. */
jens@0: - (BLIPResponse*) send;
jens@0: 
jens@0: /** Does this request not need a response?
jens@0:     This property can only be set before sending the request. */
jens@0: @property BOOL noReply;
jens@0: 
jens@0: /** Returns YES if you've replied to this request (by accessing its -response property.) */
jens@0: @property (readonly) BOOL repliedTo;
jens@0: 
jens@0: /** The request's response. This can be accessed at any time, even before sending the request,
jens@0:     but the contents of the response won't be filled in until it arrives, of course. */
jens@0: @property (readonly) BLIPResponse *response;
jens@0: 
jens@0: /** Call this when a request arrives, to indicate that you want to respond to it later.
jens@0:     It will prevent a default empty response from being sent upon return from the request handler. */
jens@0: - (void) deferResponse;
jens@0: 
jens@2: /** Shortcut to respond to this request with the given data.
jens@2:     The contentType, if not nil, is stored in the "Content-Type" property. */
jens@2: - (void) respondWithData: (NSData*)data contentType: (NSString*)contentType;
jens@0: 
jens@0: /** Shortcut to respond to this request with the given string (which will be encoded in UTF-8). */
jens@0: - (void) respondWithString: (NSString*)string;
jens@0: 
jens@0: /** Shortcut to respond to this request with an error. */
jens@0: - (void) respondWithError: (NSError*)error;
jens@0: 
jens@0: /** Shortcut to respond to this request with the given error code and message.
jens@0:     The BLIPErrorDomain is assumed. */
jens@0: - (void) respondWithErrorCode: (int)code message: (NSString*)message; //, ... __attribute__ ((format (__NSString__, 2,3)));;
jens@0: 
jens@0: /** Shortcut to respond to this message with an error indicating that an exception occurred. */
jens@0: - (void) respondWithException: (NSException*)exception;
jens@0: 
jens@0: @end
jens@0: 
jens@0: 
jens@0: 
jens@0: 
jens@5: /** A reply to a BLIPRequest, in the <a href=".#blipdesc">BLIP</a> protocol. */
jens@0: @interface BLIPResponse : BLIPMessage
jens@0: {
jens@0:     @private
jens@0:     NSError *_error;
jens@0:     MYTarget *_onComplete;
jens@0: }
jens@0: 
jens@0: /** Sends this response. */
jens@0: - (BOOL) send;
jens@0: 
jens@0: /** The error returned by the peer, or nil if the response is successful. */
jens@0: @property (retain) NSError* error;
jens@0: 
jens@0: /** Sets a target/action to be called when an incoming response is complete.
jens@0:     Use this on the response returned from -[BLIPRequest send], to be notified when the response is available. */
jens@0: @property (retain) MYTarget *onComplete;
jens@0: 
jens@0: 
jens@0: @end