jens@0: //
jens@0: //  BLIPMessage.h
jens@0: //  MYNetwork
jens@0: //
jens@0: //  Created by Jens Alfke on 5/10/08.
jens@0: //  Copyright 2008 Jens Alfke. All rights reserved.
jens@0: //
jens@0: 
jens@0: #import <Foundation/Foundation.h>
jens@0: @class BLIPConnection, BLIPProperties, BLIPMutableProperties;
jens@0: 
jens@0: 
jens@0: /** NSError domain and codes for BLIP */
jens@0: extern NSString* const BLIPErrorDomain;
jens@0: enum {
jens@0:     kBLIPError_BadData = 1,
jens@0:     kBLIPError_BadFrame,
jens@0:     kBLIPError_Disconnected,
jens@0:     kBLIPError_PeerNotAllowed,
jens@0:     
jens@0:     kBLIPError_Misc = 99,
jens@0:     
jens@0:     // errors returned in responses:
jens@0:     kBLIPError_BadRequest = 400,
jens@0:     kBLIPError_Forbidden = 403,
jens@0:     kBLIPError_NotFound = 404,
jens@0:     kBLIPError_BadRange = 416,
jens@0:     
jens@0:     kBLIPError_HandlerFailed = 501,
jens@0:     kBLIPError_Unspecified = 599            // peer didn't send any detailed error info
jens@0: };
jens@0: 
jens@16: NSError *BLIPMakeError( int errorCode, NSString *message, ... ) __attribute__ ((format (__NSString__, 2, 3)));
jens@16: 
jens@0: 
jens@5: /** Abstract superclass for <a href=".#blipdesc">BLIP</a> requests and responses. */
jens@0: @interface BLIPMessage : NSObject 
jens@0: {
jens@0:     BLIPConnection *_connection;
jens@0:     UInt16 _flags;
jens@0:     UInt32 _number;
jens@0:     BLIPProperties *_properties;
jens@0:     NSData *_body;
jens@0:     NSMutableData *_encodedBody;
jens@0:     NSMutableData *_mutableBody;
jens@0:     BOOL _isMine, _isMutable, _sent, _propertiesAvailable, _complete;
jens@0:     SInt32 _bytesWritten;
jens@0: };
jens@0: 
jens@0: /** The BLIPConnection associated with this message. */
jens@0: @property (readonly,retain) BLIPConnection *connection;
jens@0: 
jens@0: /** This message's serial number in its connection.
jens@0:     A BLIPRequest's number is initially zero, then assigned when it's sent.
jens@0:     A BLIPResponse is automatically assigned the same number as the request it replies to. */
jens@0: @property (readonly) UInt32 number;
jens@0: 
jens@0: /** Is this a message sent by me (as opposed to the peer)? */
jens@0: @property (readonly) BOOL isMine;
jens@0: 
jens@0: /** Has this message been sent yet? (Only makes sense when isMe is set.) */
jens@0: @property (readonly) BOOL sent;
jens@0: 
jens@0: /** Has enough of the message arrived to read its properies? */
jens@0: @property (readonly) BOOL propertiesAvailable;
jens@0: 
jens@0: /** Has the entire message, including the body, arrived? */
jens@0: @property (readonly) BOOL complete;
jens@0: 
jens@2: /** Should the message body be compressed with gzip?
jens@2:     This property can only be set <i>before</i> sending the message. */
jens@0: @property BOOL compressed;
jens@0: 
jens@0: /** Should the message be sent ahead of normal-priority messages?
jens@2:     This property can only be set <i>before</i> sending the message. */
jens@0: @property BOOL urgent;
jens@0: 
jens@0: /** Can this message be changed? (Only true for outgoing messages, before you send them.) */
jens@0: @property (readonly) BOOL isMutable;
jens@0: 
jens@0: /** The message body, a blob of arbitrary data. */
jens@0: @property (copy) NSData *body;
jens@0: 
jens@0: /** Appends data to the body. */
jens@0: - (void) addToBody: (NSData*)data;
jens@0: 
jens@3: /** The message body as an NSString.
jens@3:     The UTF-8 character encoding is used to convert. */
jens@3: @property (copy) NSString *bodyString;
jens@3: 
jens@0: #pragma mark PROPERTIES:
jens@0: 
jens@2: /** The message's properties, a dictionary-like object.
jens@2:     Message properties are much like the headers in HTTP, MIME and RFC822. */
jens@0: @property (readonly) BLIPProperties* properties;
jens@0: 
jens@0: /** Mutable version of the message's properties; only available if this mesage is mutable. */
jens@0: @property (readonly) BLIPMutableProperties* mutableProperties;
jens@0: 
jens@0: /** The value of the "Content-Type" property, which is by convention the MIME type of the body. */
jens@0: @property (copy) NSString *contentType;
jens@0: 
jens@0: /** The value of the "Profile" property, which by convention identifies the purpose of the message. */
jens@0: @property (copy) NSString *profile;
jens@0: 
jens@0: /** A shortcut to get the value of a property. */
jens@0: - (NSString*) valueOfProperty: (NSString*)property;
jens@0: 
jens@0: /** A shortcut to set the value of a property. A nil value deletes that property. */
jens@0: - (void) setValue: (NSString*)value ofProperty: (NSString*)property;
jens@0: 
jens@0: /** Similar to -description, but also shows the properties and their values. */
jens@0: @property (readonly) NSString* descriptionWithProperties;
jens@0: 
jens@0: 
jens@0: @end