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 namespace xmltooling {
  30     class XMLTOOL_API HTTPRequest;
  31     class XMLTOOL_API HTTPResponse;
  32 };
  33
  34 namespace shibsp {
  35
  36     /**
  37      * Base class for handlers that need HTTP request/response layer to be remoted.
  38      */
  39     class SHIBSP_API RemotedHandler : public virtual Handler, public Remoted
  40     {
  41     public:
  42         virtual ~RemotedHandler();
  43
  44     protected:
  45         RemotedHandler();
  46
  47         /**
  48          * Establishes message remoting using the supplied address.
  49          *
  50          * @param address   a unique "address" for remote message handling
  51          */
  52         void setAddress(const char* address);
  53
  54         /**
  55          * Wraps a request by creating an outgoing data flow with the data needed
  56          * to remote the request information.
  57          *
  58          * @param request   an SPRequest to remote
  59          * @param headers   array of request headers to copy to remote request
  60          * @param certs     true iff client certificates should be available for the remote request
  61          * @return  the input dataflow object
  62          */
  63         DDF wrap(const SPRequest& request, const std::vector<std::string>* headers=nullptr, bool certs=false) const;
  64
  65         /**
  66          * Unwraps a response by examining an incoming data flow to determine
  67          * whether a response was produced by the remoted handler.
  68          *
  69          * @param request   SP request context
  70          * @param out       the dataflow object to unpack
  71          * @return  a pair containing a "request completed" indicator and a server-specific response code
  72          */
  73         virtual std::pair<bool,long> unwrap(SPRequest& request, DDF& out) const;
  74
  75         /**
  76          * Builds a new request instance around a remoted data object.
  77          *
  78          * @param in    the dataflow object containing the remoted request
  79          * @return  a call-specific request object based on the input, to be freed by the caller
  80          */
  81         xmltooling::HTTPRequest* getRequest(DDF& in) const;
  82
  83         /**
  84          * Builds a new response instance around an outgoing data object.
  85          *
  86          * @param out   the dataflow object to be returned by the caller
  87          * @return  a call-specific response object, to be freed by the caller
  88          */
  89         xmltooling::HTTPResponse* getResponse(DDF& out) const;
  90
  91         /** Message address for remote half. */
  92         std::string m_address;
  93     };
  94 };
  95
  96 #endif /* __shibsp_remhandler_h__ */