Network/transfer.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 // transfer - the embodiment of a single transfer transaction
  21 //
  22 #ifndef _H_TRANSFER
  23 #define _H_TRANSFER
  24
  25 #include <Security/streams.h>
  26 #include <Security/ip++.h>
  27 #include "protocol.h"
  28 #include "target.h"
  29 #include "parameters.h"
  30 #include "observer.h"
  31
  32
  33 using namespace IPPlusPlus;
  34
  35
  36 namespace Security {
  37 namespace Network {
  38
  39
  40 class Protocol;
  41
  42
  43 //
  44 // A Transfer is a single transaction with a target. It usually performs
  45 // a data transfer (upload or download), though it could also be some
  46 // administrative action such as creating or deleting (remote) directories.
  47 //
  48 class Transfer : public ParameterPointer {
  49     friend class Manager;
  50     friend class Connection;
  51 public:
  52     typedef Protocol::Operation Operation;
  53
  54     Transfer(Protocol &proto, const Target &tgt, Operation op, IPPort defaultPort = 0);
  55     virtual ~Transfer();
  56
  57     Protocol &protocol;
  58     const Target target;
  59
  60     enum State {
  61         cold,                                                   // queued
  62         warm,                                                   // (not yet used)
  63         active,                                                 // in progress
  64         frozen,                                                 // (not yet used)
  65         finished,                                               // successfully finished
  66         failed                                                  // failed
  67     };
  68
  69     enum ResultClass {
  70         success,                                                // seems to have worked
  71         localFailure,                                   // local error
  72         networkFailure,                                 // failure talking to remote partner
  73         remoteFailure,                                  // failure reported by remote partner
  74         authorizationFailure,                   // remote reject our authorization
  75         abortedFailure,                                 // transfer was aborted intentionally
  76         unclassifiedFailure                             // something else went wrong
  77     };
  78
  79     State state() const                         { return mState; }
  80     Operation operation() const         { return mOperation; }
  81
  82     // valid only if state() is finished or failed
  83     virtual ResultClass resultClass() const;    // classify outcome
  84
  85     // call these ONLY if state() == failed
  86     virtual OSStatus errorStatus() const;               // OSStatus short form of error condition
  87     virtual string errorDescription() const;    // string form of error condition
  88
  89     template <class Conn>
  90     Conn &connectionAs() const
  91     { assert(mConnection); return *safe_cast<Conn *>(mConnection); }
  92
  93     bool isDocked() const                               { return mConnection; }
  94
  95     Sink &sink() const                                  { assert(mSink); return *mSink; }
  96     Source &source() const                              { assert(mSource); return *mSource; }
  97     void sink(Sink &snk)                                { assert(!mSink); mSink = &snk; }
  98     void source(Source &src)                    { assert(!mSource); mSource = &src; }
  99     bool hasSink() const                                { return mSink; }
 100     bool hasSource() const                              { return mSource; }
 101
 102     // get/set the Observer. Observer is initially inherited from Manager
 103     Observer *observer() const                  { return mObserver; }
 104     void observer(Observer *ob)                 { mObserver = ob; }
 105
 106     // get/set connection reuse feature
 107     bool shareConnections() const               { return mShareConnections; }
 108     void shareConnections(bool share)   { mShareConnections = share; }
 109
 110     // return our hostTarget or that of the proxy server, if any
 111     const HostTarget &proxyHostTarget() const
 112     { return protocol.isProxy() ? protocol.proxyHost() : target; }
 113
 114     // last resort OSStatus to return for failure, if nothing better is known
 115     static const OSStatus defaultOSStatusError = -30785;        //@@@ not a good choice, but what?
 116
 117 protected:
 118     virtual void start() = 0;                   // engage!
 119     virtual void abort();                               // abort while running
 120
 121     void restart();
 122     void observe(Observer::Events events, const void *info = NULL);
 123
 124     void setError(const char *s, OSStatus err = defaultOSStatusError)
 125     { if (s) mErrorStatus = err; mErrorDescription = s; }
 126
 127     void finish();
 128     void fail();
 129
 130 private:
 131     State mState;                                               // current state
 132     Operation mOperation;                               // operation type
 133     Connection *mConnection;                    // docked connection (NULL if none)
 134     Observer *mObserver;                                // observer (NULL if none)
 135     Source *mSource;                                    // origin data source (NULL if N/A)
 136     Sink *mSink;                                                // destination data sink (NULL if N/A)
 137     bool mShareConnections;                             // participate in Connection pool (reuse)
 138
 139     OSStatus mErrorStatus;                              // OSStatus to return by default
 140     string mErrorDescription;                   // error string to return by default
 141 };
 142
 143
 144 }       // end namespace Network
 145 }       // end namespace Security
 146
 147
 148 #endif /* _H_TRANSFER */