BLIP/BLIPConnection.h
changeset 1 8267d5c429c4
child 2 9fdd8dba529c
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/BLIP/BLIPConnection.h	Sat May 24 13:26:02 2008 -0700
     1.3 @@ -0,0 +1,83 @@
     1.4 +//
     1.5 +//  BLIPConnection.h
     1.6 +//  MYNetwork
     1.7 +//
     1.8 +//  Created by Jens Alfke on 5/10/08.
     1.9 +//  Copyright 2008 Jens Alfke. All rights reserved.
    1.10 +//
    1.11 +
    1.12 +#import "TCPConnection.h"
    1.13 +#import "TCPListener.h"
    1.14 +@class BLIPRequest, BLIPResponse, BLIPDispatcher;
    1.15 +@protocol BLIPConnectionDelegate;
    1.16 +
    1.17 +
    1.18 +/** Represents a connection to a peer, using the BLIP protocol over a TCP socket.
    1.19 +    Outgoing connections are made simply by instantiating a BLIPConnection via -initToAddress:.
    1.20 +    Incoming connections are usually set up by a BLIPListener and passed to the listener's
    1.21 +    delegate.
    1.22 +    Most of the API is inherited from TCPConnection. */
    1.23 +@interface BLIPConnection : TCPConnection
    1.24 +{
    1.25 +    BLIPDispatcher *_dispatcher;
    1.26 +}
    1.27 +
    1.28 +/** The delegate object that will be called when the connection opens, closes or receives messages. */
    1.29 +@property (assign) id<BLIPConnectionDelegate> delegate;
    1.30 +
    1.31 +@property (readonly) BLIPDispatcher *dispatcher;
    1.32 +
    1.33 +/** Creates an outgoing request, with no properties.
    1.34 +    The body may be nil.
    1.35 +    To send it, call -send. */
    1.36 +- (BLIPRequest*) requestWithBody: (NSData*)body;
    1.37 +
    1.38 +/** Creates an outgoing request.
    1.39 +    The body or properties may be nil.
    1.40 +    To send it, call -send. */
    1.41 +- (BLIPRequest*) requestWithBody: (NSData*)body
    1.42 +                      properties: (NSDictionary*)properies;
    1.43 +
    1.44 +/** Sends a request over this connection.
    1.45 +    (Actually, it queues it to be sent; this method always returns immediately.)
    1.46 +    Call this instead of calling -send on the request itself, if the request was created with
    1.47 +    +[BLIPRequest requestWithBody:] and hasn't yet been assigned to any connection.
    1.48 +    This method will assign it to this connection before sending it.
    1.49 +    The request's matching response object will be returned, or nil if the request couldn't be sent. */
    1.50 +- (BLIPResponse*) sendRequest: (BLIPRequest*)request;
    1.51 +@end
    1.52 +
    1.53 +
    1.54 +
    1.55 +/** The delegate messages that BLIPConnection will send,
    1.56 +    in addition to the ones inherited from TCPConnectionDelegate. */
    1.57 +@protocol BLIPConnectionDelegate <TCPConnectionDelegate>
    1.58 +
    1.59 +/** Called when a BLIPRequest is received from the peer, if there is no BLIPDispatcher
    1.60 +    rule to handle it.
    1.61 +    The delegate should get the request's response object, fill in its data and properties
    1.62 +    or error property, and send it.
    1.63 +    If it doesn't explicitly send a response, a default empty one will be sent;
    1.64 +    to prevent this, call -deferResponse on the request if you want to send a response later. */
    1.65 +- (void) connection: (BLIPConnection*)connection receivedRequest: (BLIPRequest*)request;
    1.66 +
    1.67 +@optional
    1.68 +/** Called when a BLIPResponse (to one of your requests) is received from the peer.
    1.69 +    This is called <i>after</i> the response object's onComplete target, if any, is invoked. */
    1.70 +- (void) connection: (BLIPConnection*)connection receivedResponse: (BLIPResponse*)response;
    1.71 +@end
    1.72 +
    1.73 +
    1.74 +
    1.75 +
    1.76 +/** A "server" that listens on a TCP socket for incoming BLIP connections and creates
    1.77 +    BLIPConnection instances to handle them.
    1.78 +    Most of the API is inherited from TCPListener. */
    1.79 +@interface BLIPListener : TCPListener
    1.80 +{
    1.81 +    BLIPDispatcher *_dispatcher;
    1.82 +}
    1.83 +
    1.84 +@property (readonly) BLIPDispatcher *dispatcher;
    1.85 +
    1.86 +@end