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