1 #pragma once
2 
3 #ifndef HANDLER_H_BZ8DT5WS
4 #define HANDLER_H_BZ8DT5WS
5 
6 #include <memory>
7 
8 #include "rpc/config.h"
9 #include "rpc/msgpack.hpp"
10 
11 #include "rpc/detail/util.h"
12 
13 namespace rpc {
14 
15 namespace detail {
16 class server_session;
17 class handler_error {};
18 class handler_spec_response {};
19 }
20 
21 //! \brief Encapsulates information about the currently executing
22 //! handler. This is the interface through which bound functions
23 //! may return errors, arbitrary type responses or prohibit sending a response.
24 //! \note Setting each property of the handler is only relevant
25 //! for one call in one thread. If the same handler is executing concurrently
26 //! in a different thread, you can safely set different properties
27 //! and everything will "just work".
28 class this_handler_t {
29 public:
30     //! \brief Sets an arbitrary object to be sent back as an error
31     //! response to the client.
32     //! \param err_obj The error object. This can be anything that
33     //! is possible to encode with messagepack (even custom structures).
34     //! \tparam T The type of the error object.
35     template <typename T> void respond_error(T &&err_obj);
36 
37     //! \brief Sets an arbitrary object to be sent back as the response
38     //! to the call.
39     //! \param resp_obj The response object. This can be anything that
40     //! is possible to encode with messagepack (even custom structures).
41     //! \tparam T The type of the response object.
42     //! \note The normal return value of the function (if any) will be
43     //! ignored if a special response is set.
44     //! \note You can use clear_special_response() to clear the special
45     //! response and use the normal return value.
46     template <typename T> void respond(T &&resp_obj);
47 
48     //! \brief Instructs the server to not send a response to the client
49     //! (ignoring any errors and return values).
50     //! \note It is unusual to not send a response to requests, and doing so
51     //! might cause problems in the client (depending on its implementation).
52     void disable_response();
53 
54     //! \brief Enables sending a response to the call. Sending the response
55     //! is by default enabled. Enabling the response multiple times have
56     //! no effect.
57     void enable_response();
58 
59     //! \brief Sets all state of the object to default.
60     void clear();
61 
62     friend class rpc::detail::server_session;
63 
64 private:
65     RPCLIB_MSGPACK::object_handle error_, resp_;
66     bool resp_enabled_ = true;
67 };
68 }
69 
70 #include "this_handler.inl"
71 
72 namespace rpc {
73 //! \brief A thread-local object that can be used to control
74 //! the behavior of the server w.r.t. the handler. Accessing this object
75 //! from handlers that execute the same function concurrently is safe.
76 //! \note Accessing this object outside of handlers while a server is
77 //! running is potentially unsafe.
78 this_handler_t &this_handler();
79 }
80 
81 #endif /* end of include guard: HANDLER_H_BZ8DT5WS */
82 
83