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