2 * Copyright 2001-2009 Internet2
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file shibsp/remoting/ListenerService.h
20 * Interprocess remoting engine.
23 #ifndef __shibsp_listener_h__
24 #define __shibsp_listener_h__
26 #include <shibsp/remoting/ddf.h>
32 * Interface to a remoted service
34 * Classes that support remoted messages delivered by the Listener runtime
35 * support this interface and register themselves with the runtime to receive
36 * particular messages.
38 class SHIBSP_API Remoted
40 MAKE_NONCOPYABLE(Remoted);
47 * Remoted classes implement this method to process incoming messages.
49 * @param in incoming DDF message
50 * @param out stream to write outgoing DDF message to
52 virtual void receive(DDF& in, std::ostream& out)=0;
55 #if defined (_MSC_VER)
56 #pragma warning( push )
57 #pragma warning( disable : 4250 4251 )
61 * Interface to a remoting engine.
63 * A ListenerService supports the remoting of DDF objects, which are dynamic data trees
64 * that other class implementations can use to remote themselves by calling an
65 * out-of-process peer implementation with arbitrary data to carry out tasks
66 * on the implementation's behalf that require isolation from the dynamic process
67 * fluctuations that web servers are prone to. The ability to pass arbitrary data
68 * trees across the boundary allows arbitrary separation of duty between the
69 * in-process and out-of-process "halves". The ListenerService is responsible
70 * for marshalling and transmitting messages, as well as managing connections
71 * and communication errors.
73 class SHIBSP_API ListenerService : public virtual Remoted
76 virtual ~ListenerService() {}
79 * Send a remoted message and return the response.
81 * @param in input message to send
82 * @return response from remote service
84 virtual DDF send(const DDF& in)=0;
86 void receive(DDF& in, std::ostream& out);
88 // Remoted classes register and unregister for messages using these methods.
89 // Registration returns any existing listeners, allowing message hooking.
92 * Register for a message. Returns existing remote service, allowing message hooking.
94 * @param address message address to register
95 * @param svc pointer to remote service
96 * @return previous service registered for message, if any
98 virtual Remoted* regListener(const char* address, Remoted* svc);
101 * Unregisters service from an address, possibly restoring an original.
103 * @param address message address to modify
104 * @param current pointer to unregistering service
105 * @param restore service to "restore" registration for
106 * @return true iff the current service was still registered
108 virtual bool unregListener(const char* address, Remoted* current, Remoted* restore=NULL);
111 * Returns current service registered at an address, if any.
113 * @param address message address to access
114 * @return registered service, or NULL
116 virtual Remoted* lookup(const char* address) const;
119 * OutOfProcess servers can implement server-side transport handling by
120 * calling the run method and supplying a flag to monitor for shutdown.
122 * @param shutdown pointer to flag that caller will set when shutdown is required
123 * @return true iff the service execution was successful
125 virtual bool run(bool* shutdown)=0;
128 std::map<std::string,Remoted*> m_listenerMap;
131 #if defined (_MSC_VER)
132 #pragma warning( pop )
136 * Registers ListenerService classes into the runtime.
138 void SHIBSP_API registerListenerServices();
140 /** Listener based on TCP socket remoting. */
141 #define TCP_LISTENER_SERVICE "TCPListener"
143 /** Listener based on UNIX domain socket remoting. */
144 #define UNIX_LISTENER_SERVICE "UnixListener"
147 #endif /* __shibsp_listener_h__ */