5 // Created by Jens Alfke on 5/22/08.
6 // Copyright 2008 Jens Alfke. All rights reserved.
9 #import "BLIPMessage.h"
10 @class BLIPResponse, MYTarget;
13 /** A Request, or initiating message, in the <a href=".#blipdesc">BLIP</a> protocol. */
14 @interface BLIPRequest : BLIPMessage <NSMutableCopying>
17 BLIPResponse *_response;
20 /** Creates an outgoing request.
22 The request is not associated with any BLIPConnection yet, so you must either set its
23 connection property before calling -send, or pass the request as a parameter to
24 -[BLIPConnection sendRequest:]. */
25 + (BLIPRequest*) requestWithBody: (NSData*)body;
27 /** Creates an outgoing request.
28 This is just like requestWithBody: except that you supply a string. */
29 + (BLIPRequest*) requestWithBodyString: (NSString*)bodyString;
31 /** Creates an outgoing request.
32 The body or properties may be nil.
33 The request is not associated with any BLIPConnection yet, so you must either set its
34 connection property before calling -send, or pass the request as a parameter to
35 -[BLIPConnection sendRequest:]. */
36 + (BLIPRequest*) requestWithBody: (NSData*)body
37 properties: (NSDictionary*)properties;
39 /** BLIPRequest extends the -connection property to be settable.
40 This allows a request to be created without a connection (i.e. before the connection is created).
41 It can later be sent by setting the connection property and calling -send. */
42 @property (retain) BLIPConnection *connection;
44 /** Sends this request over its connection.
45 (Actually, the connection queues it to be sent; this method always returns immediately.)
46 Its matching response object will be returned, or nil if the request couldn't be sent.
47 If this request has not been assigned to a connection, an exception will be raised. */
48 - (BLIPResponse*) send;
50 /** Does this request not need a response?
51 This property can only be set before sending the request. */
52 @property BOOL noReply;
54 /** Returns YES if you've replied to this request (by accessing its -response property.) */
55 @property (readonly) BOOL repliedTo;
57 /** The request's response. This can be accessed at any time, even before sending the request,
58 but the contents of the response won't be filled in until it arrives, of course. */
59 @property (readonly) BLIPResponse *response;
61 /** Call this when a request arrives, to indicate that you want to respond to it later.
62 It will prevent a default empty response from being sent upon return from the request handler. */
63 - (void) deferResponse;
65 /** Shortcut to respond to this request with the given data.
66 The contentType, if not nil, is stored in the "Content-Type" property. */
67 - (void) respondWithData: (NSData*)data contentType: (NSString*)contentType;
69 /** Shortcut to respond to this request with the given string (which will be encoded in UTF-8). */
70 - (void) respondWithString: (NSString*)string;
72 /** Shortcut to respond to this request with an error. */
73 - (void) respondWithError: (NSError*)error;
75 /** Shortcut to respond to this request with the given error code and message.
76 The BLIPErrorDomain is assumed. */
77 - (void) respondWithErrorCode: (int)code message: (NSString*)message; //, ... __attribute__ ((format (__NSString__, 2,3)));;
79 /** Shortcut to respond to this message with an error indicating that an exception occurred. */
80 - (void) respondWithException: (NSException*)exception;
87 /** A reply to a BLIPRequest, in the <a href=".#blipdesc">BLIP</a> protocol. */
88 @interface BLIPResponse : BLIPMessage
92 MYTarget *_onComplete;
95 /** Sends this response. */
98 /** The error returned by the peer, or nil if the response is successful. */
99 @property (retain) NSError* error;
101 /** Sets a target/action to be called when an incoming response is complete.
102 Use this on the response returned from -[BLIPRequest send], to be notified when the response is available. */
103 @property (retain) MYTarget *onComplete;