BLIP/BLIPConnection.h
author Jens Alfke <jens@mooseyard.com>
Sun Jul 13 10:42:50 2008 -0700 (2008-07-13)
changeset 22 8b883753394a
parent 18 3be241de1630
child 26 cb9cdf247239
permissions -rw-r--r--
* Fixed: Responses still pending when a connection closed were not calling their onComplete targets.
* Fixed: BLIPTestClient target failed to build because it didn't link against zlib.
* If TCPListener.bonjourServiceName is changed while the listener is open, it now re-publishes the service with the new name.
* Added a TCPListener.bonjourService property.
* Added a BLIPMessage.representedObject property.
* Fixed a memory leak.
     1 //
     2 //  BLIPConnection.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 "TCPConnection.h"
    10 #import "TCPListener.h"
    11 @class BLIPRequest, BLIPResponse, BLIPDispatcher;
    12 @protocol BLIPConnectionDelegate;
    13 
    14 
    15 /** Represents a connection to a peer, using the <a href=".#blipdesc">BLIP</a> protocol over a TCP socket.
    16     Outgoing connections are made simply by instantiating a BLIPConnection via -initToAddress:.
    17     Incoming connections are usually set up by a BLIPListener and passed to the listener's
    18     delegate.
    19     Most of the API is inherited from TCPConnection. */
    20 @interface BLIPConnection : TCPConnection
    21 {
    22     BLIPDispatcher *_dispatcher;
    23     BOOL _blipClosing;
    24 }
    25 
    26 /** The delegate object that will be called when the connection opens, closes or receives messages. */
    27 @property (assign) id<BLIPConnectionDelegate> delegate;
    28 
    29 /** The connection's request dispatcher. By default it's not configured to do anything; but you
    30     can add rules to the dispatcher to call specific target methods based on properties of the
    31     incoming requests.
    32  
    33     Requests that aren't handled by the dispatcher (i.e. all of them, by default) will be
    34     passed to the delegate's connection:receivedRequest: method; or if there's no delegate,
    35     a generic error response will be returned. */
    36 @property (readonly) BLIPDispatcher *dispatcher;
    37 
    38 /** Creates a new, empty outgoing request.
    39     You should add properties and/or body data to the request, before sending it by
    40     calling its -send method. */
    41 - (BLIPRequest*) request;
    42 
    43 /** Creates a new outgoing request.
    44     The body or properties may be nil; you can add additional data or properties by calling
    45     methods on the request itself, before sending it by calling its -send method. */
    46 - (BLIPRequest*) requestWithBody: (NSData*)body
    47                       properties: (NSDictionary*)properies;
    48 
    49 /** Sends a request over this connection.
    50     (Actually, it queues it to be sent; this method always returns immediately.)
    51     Call this instead of calling -send on the request itself, if the request was created with
    52     +[BLIPRequest requestWithBody:] and hasn't yet been assigned to any connection.
    53     This method will assign it to this connection before sending it.
    54     The request's matching response object will be returned, or nil if the request couldn't be sent. */
    55 - (BLIPResponse*) sendRequest: (BLIPRequest*)request;
    56 @end
    57 
    58 
    59 
    60 /** The delegate messages that BLIPConnection will send,
    61     in addition to the ones inherited from TCPConnectionDelegate.
    62     All methods are optional. */
    63 @protocol BLIPConnectionDelegate <TCPConnectionDelegate>
    64 @optional
    65 
    66 /** Called when a BLIPRequest is received from the peer, if there is no BLIPDispatcher
    67     rule to handle it.
    68     The delegate should get the request's response object, fill in its data and properties
    69     or error property, and send it.
    70     If it doesn't explicitly send a response, a default empty one will be sent;
    71     to prevent this, call -deferResponse on the request if you want to send a response later. */
    72 - (void) connection: (BLIPConnection*)connection receivedRequest: (BLIPRequest*)request;
    73 
    74 /** Called when a BLIPResponse (to one of your requests) is received from the peer.
    75     This is called <i>after</i> the response object's onComplete target, if any, is invoked.*/
    76 - (void) connection: (BLIPConnection*)connection receivedResponse: (BLIPResponse*)response;
    77 
    78 /** Called when the peer wants to close the connection. Return YES to allow, NO to prevent. */
    79 - (BOOL) connectionReceivedCloseRequest: (BLIPConnection*)connection;
    80 
    81 /** Called if the peer refuses a close request. 
    82     The typical error is kBLIPError_Forbidden. */
    83 - (void) connection: (BLIPConnection*)connection closeRequestFailedWithError: (NSError*)error;
    84 @end
    85 
    86 
    87 
    88 
    89 /** A "server" that listens on a TCP socket for incoming <a href=".#blipdesc">BLIP</a> connections and creates
    90     BLIPConnection instances to handle them.
    91     Most of the API is inherited from TCPListener. */
    92 @interface BLIPListener : TCPListener
    93 {
    94     BLIPDispatcher *_dispatcher;
    95 }
    96 
    97 /** The default request dispatcher that will be inherited by all BLIPConnections opened by this
    98     listener.
    99     If a connection's own dispatcher doesn't have a rule to match a message, this inherited
   100     dispatcher will be checked next. Only if it fails too will the delegate be called. */
   101 @property (readonly) BLIPDispatcher *dispatcher;
   102 
   103 @end