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@0: /** Represents a connection to a peer, using the BLIP 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@0:     BLIPDispatcher *_dispatcher;
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@0: @property (readonly) BLIPDispatcher *dispatcher;
jens@0: 
jens@0: /** Creates an outgoing request, with no properties.
jens@0:     The body may be nil.
jens@0:     To send it, call -send. */
jens@0: - (BLIPRequest*) requestWithBody: (NSData*)body;
jens@0: 
jens@0: /** Creates an outgoing request.
jens@0:     The body or properties may be nil.
jens@0:     To send it, call -send. */
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@0:     in addition to the ones inherited from TCPConnectionDelegate. */
jens@0: @protocol BLIPConnectionDelegate <TCPConnectionDelegate>
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: @optional
jens@0: /** Called when a BLIPResponse (to one of your requests) is received from the peer.
jens@0:     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@0: @end
jens@0: 
jens@0: 
jens@0: 
jens@0: 
jens@0: /** A "server" that listens on a TCP socket for incoming BLIP 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@0: @property (readonly) BLIPDispatcher *dispatcher;
jens@0: 
jens@0: @end