Qore YamlRpcHandler Module Reference  1.0
 All Classes Namespaces Functions Variables Pages
YamlRpcHandler.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
3 
4 /* YamlRpcHandler.qm Copyright 2012 - 2013 David Nichols
5 
6  Permission is hereby granted, free of charge, to any person obtaining a
7  copy of this software and associated documentation files (the "Software"),
8  to deal in the Software without restriction, including without limitation
9  the rights to use, copy, modify, merge, publish, distribute, sublicense,
10  and/or sell copies of the Software, and to permit persons to whom the
11  Software is furnished to do so, subject to the following conditions:
12 
13  The above copyright notice and this permission notice shall be included in
14  all copies or substantial portions of the Software.
15 
16  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22  DEALINGS IN THE SOFTWARE.
23 */
24 
25 // minimum qore version
26 
27 // requires the binary yaml module
28 
29 // need mime definitions
30 
31 // need HttpServer definitions
32 
33 
34 /* Version History
35  * 2012-05-24 v1.0: David Nichols <david@qore.org>: updated to a user module
36  * 2013-09-24 v1.1: David Nichols <david@qore.org>: added optional log closure to constructor
37 */
38 
80 namespace YamlRpcHandler {
83 
85 class YamlRpcHandler : public AbstractHttpRequestHandler {
86 
87 public:
89  const Version = "1.0";
90 
92  const InternalMethods = (
93  ("function": "help",
94  "help" : "shows a list of YAML-RPC methods registered with this handler",
95  "text" : "help",
96  "logopt" : 2
97  ),
98  ("function": "listMethods",
99  "help" : "lists YAML-RPC method names registered with this handler",
100  "text" : "system.listMethods",
101  "logopt" : 2
102  ),
103  ("function": "system_describe",
104  "help" : "returns a service description object, like the one specified by the JSON-RPC 1.1 spec (even though we use YAML instead of JSON)",
105  "text" : "system.describe",
106  "logopt" : 2
107  ),
108  );
109 
111  private :
112  list methods = ();
113  hash mi;
114  int loglevel;
115 
116  // if True then verbose exception info will be logged
117  bool debug;
118 
119  // prefix to add to derived methods with GET requests if no "." characters are in the path
120  *string get_prefix;
121 
122  // a closure/call reference to get the log message and/or process arguments in incoming requests
123  *code getLogMessage;
124 
125  // a closure/call reference for logging (when set this is used instead of the HTTP server's logfunc for logging)
126  *code log;
127 
128 public:
130 
132 
146  constructor(AbstractAuthenticator auth, list methods, *code getLogMessage, bool dbg = False, *string get_prefix, *code log);
147 
148 
150 
157  addMethod(string name, code func, string text, string help, any logopt, any cmark);
158 
159 
161  setDebug(bool dbg = True);
162 
163 
165  bool getDebug();
166 
167 
169  static string makeResponse(any response, int flags = YAML::None);
170 
172  static string makeErrorResponse(int code, string mess, any err, int flags = YAML::None);
173 
175  // method called by HttpServer to handle a request
176  // don't reimplement this method; fix/enhance it in the module
177  final hash handleRequest(hash cx, hash hdr, *data body);
178 
179 
180  // don't reimplement this method; fix/enhance it in the module
181 
182 private:
183  final addMethodInternal(hash h);
184 public:
185 
186 
187 
188 private:
189  hash help();
190 public:
191 
192 
193 
194 private:
195  hash system_describe();
196 public:
197 
198 
199 
200 private:
201  list listMethods();
202 public:
203 
204 
205 
206 private:
207  log(hash cx, string str);
208 public:
209 
210 
211  // don't reimplement this method; fix/enhance it in the module
212 
213 private:
214  final hash callMethod(hash cx, any params);
215 public:
216 
218  };
219 };
addMethod(string name, code func, string text, string help, any logopt, any cmark)
adds a method to the handler dynamically
setDebug(bool dbg=True)
turns on or off debugging; when debugging is enabled more verbose error messages are reported ...
static string makeErrorResponse(int code, string mess, any err, int flags=YAML::None)
serializes an error reponse in YAML-RPC format given the arguments
bool getDebug()
returns the current status of the debug flag
constructor(AbstractAuthenticator auth, list methods, *code getLogMessage, bool dbg=False, *string get_prefix, *code log)
creates the handler with the given method list
static string makeResponse(any response, int flags=YAML::None)
serializes a reponse in YAML-RPC format given the arguments
const InternalMethods
internal methods of the handler (introspection)
Definition: YamlRpcHandler.qm.dox.h:92
YamlRpcHandler class definition; to be registered as a handler in the HttpServer class.
Definition: YamlRpcHandler.qm.dox.h:85
const Version
implementation of the handler
Definition: YamlRpcHandler.qm.dox.h:89