handler.h
Go to the documentation of this file.
1 /*
2 ** Copyright 2014-2016 The Earlham Institute
3 **
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
7 **
8 ** http://www.apache.org/licenses/LICENSE-2.0
9 **
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.
15 */
16 
21 #ifndef GRASSROOTS_HANDLE_H
22 #define GRASSROOTS_HANDLE_H
23 
24 #include <stddef.h>
25 #include <time.h>
26 
27 #include "typedefs.h"
29 #include "plugin.h"
30 #include "data_resource.h"
31 #include "parameter.h"
32 #include "jansson.h"
33 #include "filesystem_utils.h"
34 #include "user_details.h"
35 
42 typedef enum
43 {
46 
49 
52 
56 
57 
58 struct Handler;
59 
60 
72 typedef struct Handler
73 {
79 
91  bool (*ha_init_fn) (struct Handler *handler_p, const UserDetails *user_p);
92 
100  bool (*ha_match_fn) (struct Handler *handler_p, const Resource * resource_p);
101 
111  const char *(*ha_get_protocol_fn) (struct Handler *handler_p);
112 
113 
120  const char *(*ha_get_name_fn) (struct Handler *handler_p);
121 
122 
129  const char *(*ha_get_description_fn) (struct Handler *handler_p);
130 
142  bool (*ha_open_fn) (struct Handler *handler_p, Resource *resource_p, MEM_FLAG resource_mem, const char * const mode_s);
143 
144 
156  size_t (*ha_read_fn) (struct Handler *handler_p, void *buffer_p, const size_t length);
157 
158 
170  size_t (*ha_write_fn) (struct Handler *handler_p, const void *buffer_p, const size_t length);
171 
172 
186  bool (*ha_seek_fn) (struct Handler *handler_p, long offset, int whence);
187 
188 
195  bool (*ha_close_fn) (struct Handler *handler_p);
196 
197 
198 
205  HandlerStatus (*ha_status_fn) (struct Handler *handler_p);
206 
207 
215  bool (*ha_file_info_fn) (struct Handler *handler_p, FileInformation *info_p);
216 
217 
225  void (*ha_free_handler_fn) (struct Handler *handler_p);
226 
231 
236 } Handler;
237 
238 
246 typedef struct HandlerNode
247 {
250 
253 } HandlerNode;
254 
255 
256 #ifdef __cplusplus
257 extern "C"
258 {
259 #endif
260 
293 GRASSROOTS_HANDLER_API void InitialiseHandler (Handler * const handler_p,
294  bool (*init_fn) (struct Handler *handler_p, const UserDetails *user_p),
295  bool (*match_fn) (struct Handler *handler_p, const Resource * resource_p),
296  const char *(*get_protocol_fn) (struct Handler *handler_p),
297  const char *(*get_name_fn) (struct Handler *handler_p),
298  const char *(*get_description_fn) (struct Handler *handler_p),
299  bool (*open_fn) (struct Handler *handler_p, Resource *resource_p, MEM_FLAG resource_mem, const char * const mode_s),
300  size_t (*read_fn) (struct Handler *handler_p, void *buffer_p, const size_t length),
301  size_t (*write_fn) (struct Handler *handler_p, const void *buffer_p, const size_t length),
302  bool (*seek_fn) (struct Handler *handler_p, long offset, int whence),
303  bool (*close_fn) (struct Handler *handler_p),
304  HandlerStatus (*status_fn) (struct Handler *handler_p),
305  bool (*file_info_fn) (struct Handler *handler_p, FileInformation *info_p),
306  void (*free_handler_fn) (struct Handler *handler_p));
307 
308 
321 GRASSROOTS_HANDLER_API bool InitHandler (struct Handler *handler_p, const UserDetails *user_p);
322 
336 GRASSROOTS_HANDLER_API bool OpenHandler (struct Handler *handler_p, Resource *resource_p, MEM_FLAG resource_mem, const char * const mode_s);
337 
338 
351 GRASSROOTS_HANDLER_API size_t ReadFromHandler (struct Handler *handler_p, void *buffer_p, const size_t length);
352 
353 
366 GRASSROOTS_HANDLER_API size_t WriteToHandler (struct Handler *handler_p, const void *buffer_p, const size_t length);
367 
368 
383 GRASSROOTS_HANDLER_API bool SeekHandler (struct Handler *handler_p, size_t offset, int whence);
384 
385 
393 GRASSROOTS_HANDLER_API bool CloseHandler (struct Handler *handler_p);
394 
395 
404 GRASSROOTS_HANDLER_API bool IsHandlerForResource (struct Handler *handler_p, const Resource * resource_p);
405 
406 
414 GRASSROOTS_HANDLER_API const char *GetHandlerName (struct Handler *handler_p);
415 
416 
424 GRASSROOTS_HANDLER_API const char *GetHandlerDescription (struct Handler *handler_p);
425 
426 
427 
438 GRASSROOTS_HANDLER_API const char *GetHandlerProtocol (struct Handler *handler_p);
439 
440 
448 GRASSROOTS_HANDLER_API HandlerStatus GetHandlerStatus (struct Handler *handler_p);
449 
450 
459 GRASSROOTS_HANDLER_API bool CalculateFileInformationFromHandler (struct Handler *handler_p, FileInformation *info_p);
460 
461 
470 GRASSROOTS_HANDLER_API void FreeHandler (struct Handler *handler_p);
471 
472 
480 GRASSROOTS_HANDLER_API HandlerNode *AllocateHandlerNode (struct Handler *handler_p);
481 
482 
492 GRASSROOTS_HANDLER_API void FreeHandlerNode (ListItem *node_p);
493 
494 
502 GRASSROOTS_HANDLER_API Handler *GetHandlerFromPlugin (Plugin * const plugin_p, const UserDetails *user_p, GrassrootsServer *grassroots_p);
503 
504 
511 GRASSROOTS_HANDLER_API bool DeallocatePluginHandler (Plugin * const plugin_p);
512 
513 
514 
515 GRASSROOTS_HANDLER_API GrassrootsServer *GetGrassrootsServerFromHandler (const Handler * const handler_p);
516 
517 
518 #ifdef __cplusplus
519 }
520 #endif
521 
522 
523 #endif /* #ifndef GRASSROOTS_HANDLE_H */
524 
A datatype to hold a collection of metadata about a file.
Definition: filesystem_utils.h:39
Handler * GetHandlerFromPlugin(Plugin *const plugin_p, const UserDetails *user_p, GrassrootsServer *grassroots_p)
Load a Handler from a Plugin.
A doubly-linked node that points to its predecessor and successor.
Definition: linked_list.h:43
bool(* ha_match_fn)(struct Handler *handler_p, const Resource *resource_p)
Determine if the Handler is designed for a given Resource.
Definition: handler.h:100
bool(* ha_seek_fn)(struct Handler *handler_p, long offset, int whence)
Move a Handler to a new position in its stream.
Definition: handler.h:186
MEM_FLAG
An enum specifying the particular status of a piece of dynamically allocated memory for a particular ...
Definition: memory_allocations.h:36
size_t(* ha_read_fn)(struct Handler *handler_p, void *buffer_p, const size_t length)
Read data from a Handler into a buffer.
Definition: handler.h:156
void FreeHandler(struct Handler *handler_p)
Free a Handler.
size_t(* ha_write_fn)(struct Handler *handler_p, const void *buffer_p, const size_t length)
Write data from a buffer into a Handler.
Definition: handler.h:170
HandlerStatus
An enumeration of the possible status values of a stream being used by a Handler.
Definition: handler.h:42
The Handler has encountered an error using the stream.
Definition: handler.h:51
void InitialiseHandler(Handler *const handler_p, bool(*init_fn)(struct Handler *handler_p, const UserDetails *user_p), bool(*match_fn)(struct Handler *handler_p, const Resource *resource_p), const char *(*get_protocol_fn)(struct Handler *handler_p), const char *(*get_name_fn)(struct Handler *handler_p), const char *(*get_description_fn)(struct Handler *handler_p), bool(*open_fn)(struct Handler *handler_p, Resource *resource_p, MEM_FLAG resource_mem, const char *const mode_s), size_t(*read_fn)(struct Handler *handler_p, void *buffer_p, const size_t length), size_t(*write_fn)(struct Handler *handler_p, const void *buffer_p, const size_t length), bool(*seek_fn)(struct Handler *handler_p, long offset, int whence), bool(*close_fn)(struct Handler *handler_p), HandlerStatus(*status_fn)(struct Handler *handler_p), bool(*file_info_fn)(struct Handler *handler_p, FileInformation *info_p), void(*free_handler_fn)(struct Handler *handler_p))
Initialise a Handler from a loaded Plugin.
const char * GetHandlerProtocol(struct Handler *handler_p)
Get the protocol of a Handler.
bool(* ha_open_fn)(struct Handler *handler_p, Resource *resource_p, MEM_FLAG resource_mem, const char *const mode_s)
Open a Resource with the Handler.
Definition: handler.h:142
The stream is in a valid state.
Definition: handler.h:45
Handler * hn_handler_p
The Handler.
Definition: handler.h:252
bool(* ha_file_info_fn)(struct Handler *handler_p, FileInformation *info_p)
Calculate the FileInformation for the current Resource in use by a Handler.
Definition: handler.h:215
HandlerNode * AllocateHandlerNode(struct Handler *handler_p)
Allocate a HandlerNode for the given Handler.
HandlerStatus GetHandlerStatus(struct Handler *handler_p)
Get the HandlerStatus of a Handler.
HandlerStatus(* ha_status_fn)(struct Handler *handler_p)
Get the HandlerStatus of a Handler.
Definition: handler.h:205
bool CloseHandler(struct Handler *handler_p)
Close a Handler.
bool DeallocatePluginHandler(Plugin *const plugin_p)
Free the Plugin associated with a Handler.
struct Plugin * ha_plugin_p
The platform-specific plugin that the code for the Client is stored in.
Definition: handler.h:78
A Plugin is a dynamically-loaded component to provide a piece of functionality.
Definition: plugin.h:151
void FreeHandlerNode(ListItem *node_p)
Free a HandlerNode.
const char * GetHandlerName(struct Handler *handler_p)
Get the name of a Handler.
ListItem hn_node
The base list node.
Definition: handler.h:249
bool(* ha_init_fn)(struct Handler *handler_p, const UserDetails *user_p)
Initialise a Handler ready for use.
Definition: handler.h:91
size_t WriteToHandler(struct Handler *handler_p, const void *buffer_p, const size_t length)
Write data from a buffer into a Handler.
size_t ReadFromHandler(struct Handler *handler_p, void *buffer_p, const size_t length)
Read data from a Handler into a buffer.
A datatype to store user credentials.
Definition: user_details.h:76
MEM_FLAG ha_resource_mem
The MEM_FLAG for the Handler's Resource.
Definition: handler.h:235
The Handler has reached the end of the stream.
Definition: handler.h:48
bool CalculateFileInformationFromHandler(struct Handler *handler_p, FileInformation *info_p)
Calculate the FileInformation for the current Resource in use by a Handler.
const char * GetHandlerDescription(struct Handler *handler_p)
Get the description of a Handler.
A datatype for storing a Handler on a LinkedList.
Definition: handler.h:246
Definition: grassroots_server.h:44
A Handler is a datatype for accessing data.
Definition: handler.h:72
A datatype representing a URI.
Definition: data_resource.h:40
Resource * ha_resource_p
The current Resource for this Handler.
Definition: handler.h:230
void(* ha_free_handler_fn)(struct Handler *handler_p)
Free a Handler.
Definition: handler.h:225
The Handler does not have an open stream.
Definition: handler.h:54
bool IsHandlerForResource(struct Handler *handler_p, const Resource *resource_p)
Determine if the Handler is designed for a given Resource.
bool SeekHandler(struct Handler *handler_p, size_t offset, int whence)
Move a Handler to a new position in its stream.
bool(* ha_close_fn)(struct Handler *handler_p)
Close a Handler.
Definition: handler.h:195
bool OpenHandler(struct Handler *handler_p, Resource *resource_p, MEM_FLAG resource_mem, const char *const mode_s)
Open a Resource with the Handler.
bool InitHandler(struct Handler *handler_p, const UserDetails *user_p)
Initialise a Handler ready for use.