BLIP/BLIPMessage.h
author Jens Alfke <jens@mooseyard.com>
Sun May 10 19:00:50 2009 -0700 (2009-05-10)
changeset 45 8efb48eabd08
parent 22 8b883753394a
permissions -rw-r--r--
Fixed MYAddressLookup to allocate an NSSet, and to send correct KV notifications. (Based on Jim Roepke's patch, but outsourcing the KV grunge to CollectionUtils.)
     1 //
     2 //  BLIPMessage.h
     3 //  MYNetwork
     4 //
     5 //  Created by Jens Alfke on 5/10/08.
     6 //  Copyright 2008 Jens Alfke. All rights reserved.
     7 //
     8 
     9 #import <Foundation/Foundation.h>
    10 @class BLIPConnection, BLIPProperties, BLIPMutableProperties;
    11 
    12 
    13 /** NSError domain and codes for BLIP */
    14 extern NSString* const BLIPErrorDomain;
    15 enum {
    16     kBLIPError_BadData = 1,
    17     kBLIPError_BadFrame,
    18     kBLIPError_Disconnected,
    19     kBLIPError_PeerNotAllowed,
    20     
    21     kBLIPError_Misc = 99,
    22     
    23     // errors returned in responses:
    24     kBLIPError_BadRequest = 400,
    25     kBLIPError_Forbidden = 403,
    26     kBLIPError_NotFound = 404,
    27     kBLIPError_BadRange = 416,
    28     
    29     kBLIPError_HandlerFailed = 501,
    30     kBLIPError_Unspecified = 599            // peer didn't send any detailed error info
    31 };
    32 
    33 NSError *BLIPMakeError( int errorCode, NSString *message, ... ) __attribute__ ((format (__NSString__, 2, 3)));
    34 
    35 
    36 /** Abstract superclass for <a href=".#blipdesc">BLIP</a> requests and responses. */
    37 @interface BLIPMessage : NSObject 
    38 {
    39     @protected
    40     BLIPConnection *_connection;
    41     UInt16 _flags;
    42     UInt32 _number;
    43     BLIPProperties *_properties;
    44     NSData *_body;
    45     NSMutableData *_encodedBody;
    46     NSMutableData *_mutableBody;
    47     BOOL _isMine, _isMutable, _sent, _propertiesAvailable, _complete;
    48     SInt32 _bytesWritten;
    49     id _representedObject;
    50 };
    51 
    52 /** The BLIPConnection associated with this message. */
    53 @property (readonly,retain) BLIPConnection *connection;
    54 
    55 /** This message's serial number in its connection.
    56     A BLIPRequest's number is initially zero, then assigned when it's sent.
    57     A BLIPResponse is automatically assigned the same number as the request it replies to. */
    58 @property (readonly) UInt32 number;
    59 
    60 /** Is this a message sent by me (as opposed to the peer)? */
    61 @property (readonly) BOOL isMine;
    62 
    63 /** Has this message been sent yet? (Only makes sense when isMe is set.) */
    64 @property (readonly) BOOL sent;
    65 
    66 /** Has enough of the message arrived to read its properies? */
    67 @property (readonly) BOOL propertiesAvailable;
    68 
    69 /** Has the entire message, including the body, arrived? */
    70 @property (readonly) BOOL complete;
    71 
    72 /** Should the message body be compressed with gzip?
    73     This property can only be set <i>before</i> sending the message. */
    74 @property BOOL compressed;
    75 
    76 /** Should the message be sent ahead of normal-priority messages?
    77     This property can only be set <i>before</i> sending the message. */
    78 @property BOOL urgent;
    79 
    80 /** Can this message be changed? (Only true for outgoing messages, before you send them.) */
    81 @property (readonly) BOOL isMutable;
    82 
    83 /** The message body, a blob of arbitrary data. */
    84 @property (copy) NSData *body;
    85 
    86 /** Appends data to the body. */
    87 - (void) addToBody: (NSData*)data;
    88 
    89 /** The message body as an NSString.
    90     The UTF-8 character encoding is used to convert. */
    91 @property (copy) NSString *bodyString;
    92 
    93 /** An arbitrary object that you can associate with this message for your own purposes.
    94     The message retains it, but doesn't do anything else with it. */
    95 @property (retain) id representedObject;
    96 
    97 #pragma mark PROPERTIES:
    98 
    99 /** The message's properties, a dictionary-like object.
   100     Message properties are much like the headers in HTTP, MIME and RFC822. */
   101 @property (readonly) BLIPProperties* properties;
   102 
   103 /** Mutable version of the message's properties; only available if this mesage is mutable. */
   104 @property (readonly) BLIPMutableProperties* mutableProperties;
   105 
   106 /** The value of the "Content-Type" property, which is by convention the MIME type of the body. */
   107 @property (copy) NSString *contentType;
   108 
   109 /** The value of the "Profile" property, which by convention identifies the purpose of the message. */
   110 @property (copy) NSString *profile;
   111 
   112 /** A shortcut to get the value of a property. */
   113 - (NSString*) valueOfProperty: (NSString*)property;
   114 
   115 /** A shortcut to set the value of a property. A nil value deletes that property. */
   116 - (void) setValue: (NSString*)value ofProperty: (NSString*)property;
   117 
   118 /** Similar to -description, but also shows the properties and their values. */
   119 @property (readonly) NSString* descriptionWithProperties;
   120 
   121 
   122 @end