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.
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 * @file shibsp/remoting/ListenerService.h
24 * Interprocess remoting engine.
27 #ifndef __shibsp_listener_h__
28 #define __shibsp_listener_h__
30 #include <shibsp/remoting/ddf.h>
36 * Interface to a remoted service
38 * Classes that support remoted messages delivered by the Listener runtime
39 * support this interface and register themselves with the runtime to receive
40 * particular messages.
42 class SHIBSP_API Remoted
44 MAKE_NONCOPYABLE(Remoted);
51 * Remoted classes implement this method to process incoming messages.
53 * @param in incoming DDF message
54 * @param out stream to write outgoing DDF message to
56 virtual void receive(DDF& in, std::ostream& out)=0;
59 #if defined (_MSC_VER)
60 #pragma warning( push )
61 #pragma warning( disable : 4250 4251 )
65 * Interface to a remoting engine.
67 * A ListenerService supports the remoting of DDF objects, which are dynamic data trees
68 * that other class implementations can use to remote themselves by calling an
69 * out-of-process peer implementation with arbitrary data to carry out tasks
70 * on the implementation's behalf that require isolation from the dynamic process
71 * fluctuations that web servers are prone to. The ability to pass arbitrary data
72 * trees across the boundary allows arbitrary separation of duty between the
73 * in-process and out-of-process "halves". The ListenerService is responsible
74 * for marshalling and transmitting messages, as well as managing connections
75 * and communication errors.
77 class SHIBSP_API ListenerService : public virtual Remoted
82 virtual ~ListenerService();
85 * Send a remoted message and return the response.
87 * @param in input message to send
88 * @return response from remote service
90 virtual DDF send(const DDF& in)=0;
92 void receive(DDF& in, std::ostream& out);
94 // Remoted classes register and unregister for messages using these methods.
95 // Registration returns any existing listeners, allowing message hooking.
98 * Register for a message. Returns existing remote service, allowing message hooking.
100 * @param address message address to register
101 * @param svc pointer to remote service
102 * @return previous service registered for message, if any
104 virtual Remoted* regListener(const char* address, Remoted* svc);
107 * Unregisters service from an address, possibly restoring an original.
109 * @param address message address to modify
110 * @param current pointer to unregistering service
111 * @param restore service to "restore" registration for
112 * @return true iff the current service was still registered
114 virtual bool unregListener(const char* address, Remoted* current, Remoted* restore=nullptr);
117 * Returns current service registered at an address, if any.
119 * @param address message address to access
120 * @return registered service, or nullptr
122 virtual Remoted* lookup(const char* address) const;
125 * OutOfProcess servers can implement server-side initialization that should occur
126 * before daemonization.
128 * <p>The parameter applies to implementations that can detect and remove
129 * the results of ungraceful shutdowns of previous executions and continue
130 * successfully. File-based sockets are the most common example.
132 * @param force true iff remnant network state should be forcibly cleared
133 * @return true iff the service initialization was successful
135 virtual bool init(bool force);
138 * OutOfProcess servers can implement server-side transport handling by
139 * calling the run method and supplying a flag to monitor for shutdown.
141 * @param shutdown pointer to flag that caller will set when shutdown is required
142 * @return true iff the service execution was successful
144 virtual bool run(bool* shutdown)=0;
147 * OutOfProcess servers can implement server-side termination/cleanup.
152 std::map<std::string,Remoted*> m_listenerMap;
155 #if defined (_MSC_VER)
156 #pragma warning( pop )
160 * Registers ListenerService classes into the runtime.
162 void SHIBSP_API registerListenerServices();
164 /** Listener based on TCP socket remoting. */
165 #define TCP_LISTENER_SERVICE "TCPListener"
167 /** Listener based on UNIX domain socket remoting. */
168 #define UNIX_LISTENER_SERVICE "UnixListener"
171 #endif /* __shibsp_listener_h__ */