Network/netconnection.h

   1 /*
   2  * Copyright (c) 2000-2001 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18
  19 //
  20 // connection - a (potentially) persistent access path to a (possibly :-) remote entity.
  21 //
  22 // Connection objects are the bearers of actual network (or other) I/O. They are distinct
  23 // from Transfers, which embody an individual activity for a particular client (and Target).
  24 // To do its stuff, a Transfer "docks" with a Connection, uses its resources, then "undocks"
  25 // and leaves the Connection free to dock again with another Transfer (or, eventually, expire).
  26 //
  27 // Access protocols that do not have persistent state connections (e.g. FILE) will not use
  28 // Connections at all; there is no requirement for a Transfer to use a Connection for its work.
  29 //
  30 // Actual Connection objects are specialized per protocol; for example, you'd expect
  31 // an HTTPTransfer to dock to an HTTPConnection. If you subclass an existing protocol,
  32 // you *may* be able to get away with using its Connection objects - but more often you'd
  33 // subclass them in turn.
  34 //
  35 #ifndef _H_NETCONNECTION
  36 #define _H_NETCONNECTION
  37
  38 #include <Security/ip++.h>
  39 #include <Security/hosts.h>
  40 #include <Security/streams.h>
  41 #include "protocol.h"
  42 #include "target.h"
  43 #include "parameters.h"
  44 #include "transfer.h"
  45 #include <set>
  46
  47
  48 using namespace IPPlusPlus;
  49
  50
  51 namespace Security {
  52 namespace Network {
  53
  54
  55 class Manager;
  56 class Protocol;
  57 class Target;
  58
  59
  60 //
  61 // A generic Connection represents a semi-persistent channel of access to something
  62 // identified by a Target.
  63 //
  64 class Connection : public ParameterSource {
  65     friend class Transfer;
  66     friend class Manager;
  67     typedef Protocol::Operation Operation;
  68 public:
  69     Connection(Protocol &proto, const HostTarget &spec);
  70     virtual ~Connection();
  71
  72     Protocol &protocol;
  73     const HostTarget hostTarget;
  74
  75     // dock status
  76     virtual void dock(Transfer *xfer);
  77     virtual void undock();
  78     bool isDocked() const               { return mTransfer; }
  79
  80     template <class XFer>
  81     XFer &transferAs() const    { assert(mTransfer); return *safe_cast<XFer *>(mTransfer); }
  82
  83     // manage persistence
  84     bool retain() const                 { return mRetainMe; }
  85     void retain(bool r)                 { mRetainMe = r; }
  86
  87     // see if we're still alive (after perhaps a delay)
  88     virtual bool validate();
  89
  90     // return our hostTarget or that of the proxy server, if any
  91     const HostTarget &proxyHostTarget() const
  92     { return protocol.isProxy() ? protocol.proxyHost() : hostTarget; }
  93
  94 protected:
  95     Sink &sink() const                          { assert(isDocked()); return mTransfer->sink(); }
  96     Source &source() const                      { assert(isDocked()); return mTransfer->source(); }
  97     const Target &target() const        { assert(isDocked()); return mTransfer->target; }
  98     Operation operation() const         { assert(isDocked()); return mTransfer->operation(); }
  99
 100     ParameterSource *parameters()       { assert(mTransfer); return mTransfer->parameters(); }
 101     bool getParams(Key key, Value &value) const
 102     { assert(mTransfer); return mTransfer->getParams(key, value); }
 103     void observe(Observer::Event event, const void *info = NULL) const
 104     { if (mTransfer) mTransfer->observe(event, info); }
 105
 106     void setError(const char *s, OSStatus err = Transfer::defaultOSStatusError)
 107     { if (mTransfer) mTransfer->setError(s, err); }
 108
 109     void finish();
 110     void fail();
 111
 112     virtual void restart();
 113     void restarting(bool rs)            { mRestarting = rs; }
 114     bool restarting() const                     { return mRestarting; }
 115
 116 private:
 117     Transfer *mTransfer;                                // currently docked transfer (NULL if idle)
 118     bool mRetainMe;                                             // want to be retained in connection pool
 119     bool mRestarting;                                   // restart allowed
 120 };
 121
 122
 123 //
 124 // A Connection that is also a TransferAgent::Client.
 125 // This is a common case (but it isn't always true).
 126 //
 127 class TCPConnection : public Connection,
 128         public TransferEngine::Client, public TCPClientSocket {
 129 public:
 130     TCPConnection(Protocol &proto, const HostTarget &spec)
 131     : Connection(proto, spec) { }
 132     ~TCPConnection();
 133
 134     // remove from I/O hooks and close
 135     void close();
 136
 137     // manage asynchronous connection establishment
 138     void connect(const Host &host, IPPort port);
 139     void connect();
 140
 141     int fileDesc() const;
 142
 143 private:
 144     std::set<IPAddress> mAddressCandidates;
 145     IPPort mPort;
 146
 147     void nextCandidate();
 148 };
 149
 150
 151 }       // end namespace Network
 152 }       // end namespace Security
 153
 154
 155 #endif _H_NETCONNECTION