5 // Created by Jens Alfke on 5/10/08.
6 // Copyright 2008 Jens Alfke. All rights reserved.
9 #import <Foundation/Foundation.h>
10 @class BLIPConnection, BLIPProperties, BLIPMutableProperties;
13 /** NSError domain and codes for BLIP */
14 extern NSString* const BLIPErrorDomain;
16 kBLIPError_BadData = 1,
18 kBLIPError_Disconnected,
19 kBLIPError_PeerNotAllowed,
23 // errors returned in responses:
24 kBLIPError_BadRequest = 400,
25 kBLIPError_Forbidden = 403,
26 kBLIPError_NotFound = 404,
27 kBLIPError_BadRange = 416,
29 kBLIPError_HandlerFailed = 501,
30 kBLIPError_Unspecified = 599 // peer didn't send any detailed error info
33 NSError *BLIPMakeError( int errorCode, NSString *message, ... ) __attribute__ ((format (__NSString__, 2, 3)));
36 /** Abstract superclass for <a href=".#blipdesc">BLIP</a> requests and responses. */
37 @interface BLIPMessage : NSObject
39 BLIPConnection *_connection;
42 BLIPProperties *_properties;
44 NSMutableData *_encodedBody;
45 NSMutableData *_mutableBody;
46 BOOL _isMine, _isMutable, _sent, _propertiesAvailable, _complete;
48 id _representedObject;
51 /** The BLIPConnection associated with this message. */
52 @property (readonly,retain) BLIPConnection *connection;
54 /** This message's serial number in its connection.
55 A BLIPRequest's number is initially zero, then assigned when it's sent.
56 A BLIPResponse is automatically assigned the same number as the request it replies to. */
57 @property (readonly) UInt32 number;
59 /** Is this a message sent by me (as opposed to the peer)? */
60 @property (readonly) BOOL isMine;
62 /** Has this message been sent yet? (Only makes sense when isMe is set.) */
63 @property (readonly) BOOL sent;
65 /** Has enough of the message arrived to read its properies? */
66 @property (readonly) BOOL propertiesAvailable;
68 /** Has the entire message, including the body, arrived? */
69 @property (readonly) BOOL complete;
71 /** Should the message body be compressed with gzip?
72 This property can only be set <i>before</i> sending the message. */
73 @property BOOL compressed;
75 /** Should the message be sent ahead of normal-priority messages?
76 This property can only be set <i>before</i> sending the message. */
77 @property BOOL urgent;
79 /** Can this message be changed? (Only true for outgoing messages, before you send them.) */
80 @property (readonly) BOOL isMutable;
82 /** The message body, a blob of arbitrary data. */
83 @property (copy) NSData *body;
85 /** Appends data to the body. */
86 - (void) addToBody: (NSData*)data;
88 /** The message body as an NSString.
89 The UTF-8 character encoding is used to convert. */
90 @property (copy) NSString *bodyString;
92 /** An arbitrary object that you can associate with this message for your own purposes.
93 The message retains it, but doesn't do anything else with it. */
94 @property (retain) id representedObject;
96 #pragma mark PROPERTIES:
98 /** The message's properties, a dictionary-like object.
99 Message properties are much like the headers in HTTP, MIME and RFC822. */
100 @property (readonly) BLIPProperties* properties;
102 /** Mutable version of the message's properties; only available if this mesage is mutable. */
103 @property (readonly) BLIPMutableProperties* mutableProperties;
105 /** The value of the "Content-Type" property, which is by convention the MIME type of the body. */
106 @property (copy) NSString *contentType;
108 /** The value of the "Profile" property, which by convention identifies the purpose of the message. */
109 @property (copy) NSString *profile;
111 /** A shortcut to get the value of a property. */
112 - (NSString*) valueOfProperty: (NSString*)property;
114 /** A shortcut to set the value of a property. A nil value deletes that property. */
115 - (void) setValue: (NSString*)value ofProperty: (NSString*)property;
117 /** Similar to -description, but also shows the properties and their values. */
118 @property (readonly) NSString* descriptionWithProperties;