shibsp/handler/RemotedHandler.h

   1 /*
   2  *  Copyright 2001-2010 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file shibsp/handler/RemotedHandler.h
  19  *
  20  * Base class for handlers that need SP request/response layer to be remoted.
  21  */
  22
  23 #ifndef __shibsp_remhandler_h__
  24 #define __shibsp_remhandler_h__
  25
  26 #include <shibsp/handler/Handler.h>
  27 #include <shibsp/remoting/ListenerService.h>
  28
  29 #include <set>
  30
  31 namespace xmltooling {
  32     class XMLTOOL_API HTTPRequest;
  33     class XMLTOOL_API HTTPResponse;
  34 };
  35
  36 namespace shibsp {
  37
  38     /**
  39      * Base class for handlers that need HTTP request/response layer to be remoted.
  40      */
  41     class SHIBSP_API RemotedHandler : public virtual Handler, public Remoted
  42     {
  43         static std::set<std::string> m_remotedHeaders;
  44
  45     public:
  46         virtual ~RemotedHandler();
  47
  48         /**
  49          * Ensures that a request header will be remoted.
  50          *
  51          * @param header    name of request header to remote
  52          */
  53         static void addRemotedHeader(const char* header);
  54
  55     protected:
  56         RemotedHandler();
  57
  58         /**
  59          * Establishes message remoting using the supplied address.
  60          *
  61          * @param address   a unique "address" for remote message handling
  62          */
  63         void setAddress(const char* address);
  64
  65         /**
  66          * Wraps a request by creating an outgoing data flow with the data needed
  67          * to remote the request information.
  68          *
  69          * @param request   an SPRequest to remote
  70          * @param headers   array of additional request headers to copy to remote request
  71          * @param certs     true iff client certificates should be available for the remote request
  72          * @return  the input dataflow object
  73          */
  74         DDF wrap(const SPRequest& request, const std::vector<std::string>* headers=nullptr, bool certs=false) const;
  75
  76         /**
  77          * Unwraps a response by examining an incoming data flow to determine
  78          * whether a response was produced by the remoted handler.
  79          *
  80          * @param request   SP request context
  81          * @param out       the dataflow object to unpack
  82          * @return  a pair containing a "request completed" indicator and a server-specific response code
  83          */
  84         virtual std::pair<bool,long> unwrap(SPRequest& request, DDF& out) const;
  85
  86         /**
  87          * Builds a new request instance around a remoted data object.
  88          *
  89          * @param in    the dataflow object containing the remoted request
  90          * @return  a call-specific request object based on the input, to be freed by the caller
  91          */
  92         xmltooling::HTTPRequest* getRequest(DDF& in) const;
  93
  94         /**
  95          * Builds a new response instance around an outgoing data object.
  96          *
  97          * @param out   the dataflow object to be returned by the caller
  98          * @return  a call-specific response object, to be freed by the caller
  99          */
 100         xmltooling::HTTPResponse* getResponse(DDF& out) const;
 101
 102         /** Message address for remote half. */
 103         std::string m_address;
 104     };
 105 };
 106
 107 #endif /* __shibsp_remhandler_h__ */