jens@0: //
jens@0: //  BLIPConnection.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 "TCPConnection.h"
jens@0: #import "TCPListener.h"
jens@0: @class BLIPRequest, BLIPResponse, BLIPDispatcher;
jens@0: @protocol BLIPConnectionDelegate;
jens@0: 
jens@0: 
jens@5: /** Represents a connection to a peer, using the <a href=".#blipdesc">BLIP</a> protocol over a TCP socket.
jens@0:     Outgoing connections are made simply by instantiating a BLIPConnection via -initToAddress:.
jens@0:     Incoming connections are usually set up by a BLIPListener and passed to the listener's
jens@0:     delegate.
jens@0:     Most of the API is inherited from TCPConnection. */
jens@0: @interface BLIPConnection : TCPConnection
jens@0: {
jens@26:     @private
jens@0:     BLIPDispatcher *_dispatcher;
jens@18:     BOOL _blipClosing;
jens@0: }
jens@0: 
jens@0: /** The delegate object that will be called when the connection opens, closes or receives messages. */
jens@0: @property (assign) id<BLIPConnectionDelegate> delegate;
jens@0: 
jens@2: /** The connection's request dispatcher. By default it's not configured to do anything; but you
jens@2:     can add rules to the dispatcher to call specific target methods based on properties of the
jens@2:     incoming requests.
jens@2:  
jens@2:     Requests that aren't handled by the dispatcher (i.e. all of them, by default) will be
jens@2:     passed to the delegate's connection:receivedRequest: method; or if there's no delegate,
jens@2:     a generic error response will be returned. */
jens@0: @property (readonly) BLIPDispatcher *dispatcher;
jens@0: 
jens@5: /** Creates a new, empty outgoing request.
jens@5:     You should add properties and/or body data to the request, before sending it by
jens@5:     calling its -send method. */
jens@5: - (BLIPRequest*) request;
jens@0: 
jens@5: /** Creates a new outgoing request.
jens@5:     The body or properties may be nil; you can add additional data or properties by calling
jens@5:     methods on the request itself, before sending it by calling its -send method. */
jens@0: - (BLIPRequest*) requestWithBody: (NSData*)body
jens@0:                       properties: (NSDictionary*)properies;
jens@0: 
jens@0: /** Sends a request over this connection.
jens@0:     (Actually, it queues it to be sent; this method always returns immediately.)
jens@0:     Call this instead of calling -send on the request itself, if the request was created with
jens@0:     +[BLIPRequest requestWithBody:] and hasn't yet been assigned to any connection.
jens@0:     This method will assign it to this connection before sending it.
jens@0:     The request's matching response object will be returned, or nil if the request couldn't be sent. */
jens@0: - (BLIPResponse*) sendRequest: (BLIPRequest*)request;
jens@0: @end
jens@0: 
jens@0: 
jens@0: 
jens@0: /** The delegate messages that BLIPConnection will send,
jens@3:     in addition to the ones inherited from TCPConnectionDelegate.
jens@3:     All methods are optional. */
jens@0: @protocol BLIPConnectionDelegate <TCPConnectionDelegate>
jens@3: @optional
jens@0: 
jens@0: /** Called when a BLIPRequest is received from the peer, if there is no BLIPDispatcher
jens@0:     rule to handle it.
jens@0:     The delegate should get the request's response object, fill in its data and properties
jens@0:     or error property, and send it.
jens@0:     If it doesn't explicitly send a response, a default empty one will be sent;
jens@0:     to prevent this, call -deferResponse on the request if you want to send a response later. */
jens@0: - (void) connection: (BLIPConnection*)connection receivedRequest: (BLIPRequest*)request;
jens@0: 
jens@0: /** Called when a BLIPResponse (to one of your requests) is received from the peer.
jens@3:     This is called <i>after</i> the response object's onComplete target, if any, is invoked.*/
jens@0: - (void) connection: (BLIPConnection*)connection receivedResponse: (BLIPResponse*)response;
jens@18: 
jens@18: /** Called when the peer wants to close the connection. Return YES to allow, NO to prevent. */
jens@18: - (BOOL) connectionReceivedCloseRequest: (BLIPConnection*)connection;
jens@18: 
jens@18: /** Called if the peer refuses a close request. 
jens@19:     The typical error is kBLIPError_Forbidden. */
jens@18: - (void) connection: (BLIPConnection*)connection closeRequestFailedWithError: (NSError*)error;
jens@0: @end
jens@0: 
jens@0: 
jens@0: 
jens@0: 
jens@5: /** A "server" that listens on a TCP socket for incoming <a href=".#blipdesc">BLIP</a> connections and creates
jens@0:     BLIPConnection instances to handle them.
jens@0:     Most of the API is inherited from TCPListener. */
jens@0: @interface BLIPListener : TCPListener
jens@0: {
jens@0:     BLIPDispatcher *_dispatcher;
jens@0: }
jens@0: 
jens@2: /** The default request dispatcher that will be inherited by all BLIPConnections opened by this
jens@2:     listener.
jens@2:     If a connection's own dispatcher doesn't have a rule to match a message, this inherited
jens@2:     dispatcher will be checked next. Only if it fails too will the delegate be called. */
jens@0: @property (readonly) BLIPDispatcher *dispatcher;
jens@0: 
jens@0: @end