shibsp/handler/RemotedHandler.h

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