service.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 
17 
22 #ifndef GRASSROOTS_SERVICE_H
23 #define GRASSROOTS_SERVICE_H
24 
26 
27 #include "byte_buffer.h"
28 #include "linked_list.h"
29 #include "parameter_set.h"
30 #include "typedefs.h"
31 #include "handler.h"
32 #include "user_details.h"
33 #include "operation.h"
34 #include "paired_service.h"
35 #include "linked_service.h"
36 #include "uuid/uuid.h"
37 #include "service_metadata.h"
38 #include "sync_data.h"
39 
40 #include "jansson.h"
41 
42 #include "providers_state_table.h"
43 
44 struct ExternalServer;
45 
46 /*
47  * The following preprocessor macros allow us to declare
48  * and define the variables in the same place. By default,
49  * they will expand to
50  *
51  * extern const char *SERVICE_NAME_S;
52  *
53  * however if ALLOCATE_JSON_TAGS is defined then it will
54  * become
55  *
56  * const char *SERVICE_NAME_S = "path";
57  *
58  * ALLOCATE_PATH_TAGS must be defined only once prior to
59  * including this header file. Currently this happens in
60  * service.c.
61  */
62 #ifndef DOXYGEN_SHOULD_SKIP_THIS
63 
64 #ifdef ALLOCATE_PATH_TAGS
65  #define PATH_PREFIX GRASSROOTS_SERVICE_API
66  #define PATH_VAL(x) = x
67 #else
68  #define PATH_PREFIX extern
69  #define PATH_VAL(x)
70 #endif
71 
72 #endif
73 
78 PATH_PREFIX const char *SERVICES_PATH_S PATH_VAL("services");
79 
80 
81 #define SERVICE_GROUP_ALIAS_SEPARATOR "-"
82 
89 /* forward declarations */
90 struct Plugin;
91 struct Service;
92 struct ServiceJob;
93 struct ServiceJobSet;
94 
95 
101 typedef enum
102 {
105 
111 
117 } Synchronicity;
118 
119 
126 typedef struct ServiceData
127 {
130 
135  json_t *sd_config_p;
136 
142 } ServiceData;
143 
144 
145 
146 
153 typedef struct Service
154 {
160 
169 
180  struct ServiceJobSet *(*se_run_fn) (struct Service *service_p, ParameterSet *param_set_p, UserDetails *user_p, ProvidersStateTable *providers_p);
181 
193  ParameterSet *(*se_match_fn) (struct Service *service_p, Resource *resource_p, Handler *handler_p);
194 
206  bool (*se_has_permissions_fn) (struct Service *service_p, ParameterSet *params_p, const UserDetails * const user_p);
207 
208 
212  const char *(*se_get_service_name_fn) (const struct Service *service_p);
213 
217  const char *(*se_get_service_description_fn) (const struct Service *service_p);
218 
219 
223  const char *(*se_get_service_alias_fn) (const struct Service *service_p);
224 
228  const char *(*se_get_service_info_uri_fn) (const struct Service *service_p);
229 
230 
234  ParameterSet *(*se_get_params_fn) (struct Service *service_p, Resource *resource_p, UserDetails *user_p);
235 
236 
247  void (*se_customise_service_job_fn) (struct Service *service_p, struct ServiceJob *job_p);
248 
249 
253  void (*se_release_params_fn) (struct Service *service_p, ParameterSet *params_p);
254 
262  bool (*se_close_fn) (struct Service *service_p);
263 
264 
274  struct ServiceJob *(*se_deserialise_job_json_fn) (struct Service *service_p, const json_t *service_job_json_p);
275 
276 
285  json_t *(*se_serialise_job_json_fn) (struct Service *service_p, struct ServiceJob *service_job_p, bool omit_results_flag);
286 
298  bool (*se_process_linked_services_fn) (struct Service *service_p, struct ServiceJob *job_p, LinkedService *linked_service_p);
299 
300 
310  bool (*se_get_parameter_type_fn) (const struct Service *service_p, const char *param_name_s, ParameterType *pt_p);
311 
312 
317 
319  uuid_t se_id;
320 
323 
326 
332 
337 
344 
349 
350 
358  ServiceMetadata *(*se_get_metadata_fn) (struct Service *service_p);
359 
365 
371  void (*se_release_service_fn) (struct Service *service_p);
372 
373 
380  json_t *(*se_get_indexing_data_fn) (struct Service *service_p);
381 
382 
383 } Service;
384 
385 
393 typedef struct
394 {
397 
400 } ServiceNode;
401 
402 
408 typedef struct ServicesArray
409 {
412 
415 } ServicesArray;
416 
417 
418 
419 
420 
421 #ifdef __cplusplus
422 extern "C"
423 {
424 #endif
425 
434 GRASSROOTS_SERVICE_API ServicesArray *GetReferrableServicesFromPlugin (Plugin * const plugin_p, UserDetails *user_p, const json_t *service_config_p);
435 
443 GRASSROOTS_SERVICE_API ServicesArray *GetServicesFromPlugin (Plugin * const plugin_p, UserDetails *user_p);
444 
445 
471 GRASSROOTS_SERVICE_API bool InitialiseService (Service * const service_p,
472  const char *(*get_service_name_fn) (const Service *service_p),
473  const char *(*get_service_description_fn) (const Service *service_p),
474  const char *(*get_service_alias_fn) (const Service *service_p),
475  const char *(*get_service_info_uri_fn) (const Service *service_p),
476  struct ServiceJobSet *(*run_fn) (Service *service_p, ParameterSet *param_set_p, UserDetails *user_p, ProvidersStateTable *providers_p),
477  ParameterSet *(*match_fn) (Service *service_p, Resource *resource_p, Handler *handler_p),
478  ParameterSet *(*get_parameters_fn) (Service *service_p, Resource *resource_p, UserDetails *user_p),
479  bool (*get_parameter_type_fn) (const Service *service_p, const char *param_name_s, ParameterType *pt_p),
480  void (*release_parameters_fn) (Service *service_p, ParameterSet *params_p),
481  bool (*close_fn) (Service *service_p),
482  void (*customise_service_job_fn) (Service *service_p, struct ServiceJob *job_p),
483  bool specific_flag,
484  Synchronicity synchronous,
485  ServiceData *data_p,
486  ServiceMetadata *(*get_metadata_fn) (Service *service_p),
487  json_t *(*get_indexing_data_fn) (Service *service_p),
488  GrassrootsServer *grassroots_p
489 );
490 
491 
506 GRASSROOTS_SERVICE_API struct ServiceJobSet *RunService (Service *service_p, ParameterSet *param_set_p, UserDetails *user_p, ProvidersStateTable *providers_p);
507 
508 
517 GRASSROOTS_SERVICE_API bool DoesServiceHaveCustomServiceJobSerialisation (struct Service *service_p);
518 
519 
529 GRASSROOTS_SERVICE_API struct ServiceJob *CreateSerialisedServiceJobFromService (struct Service *service_p, const json_t *service_job_json_p);
530 
531 
543 GRASSROOTS_SERVICE_API json_t *CreateSerialisedJSONForServiceJobFromService (struct Service *service_p, struct ServiceJob *service_job_p, bool omit_results_flag);
544 
545 
555 GRASSROOTS_SERVICE_API Service *GetServiceByName (GrassrootsServer *grassroots_p, const char * const service_name_s, const char * const service_alias_s);
556 
557 
570 GRASSROOTS_SERVICE_API ParameterSet *IsServiceMatch (Service *service_p, Resource *resource_p, Handler *handler_p);
571 
572 
580 GRASSROOTS_SERVICE_API const char *GetServiceName (const Service *service_p);
581 
582 
590 GRASSROOTS_SERVICE_API const char *GetServiceDescription (const Service *service_p);
591 
592 
593 
594 GRASSROOTS_SERVICE_API const char *GetServiceAlias (const Service *service_p);
595 
604 GRASSROOTS_SERVICE_API json_t *GetServiceIndexingData (Service *service_p);
605 
606 
614 GRASSROOTS_SERVICE_API const char *GetServiceInformationURI (const Service *service_p);
615 
627 GRASSROOTS_SERVICE_API ParameterSet *GetServiceParameters (Service *service_p, Resource *resource_p, UserDetails *user_p);
628 
629 
630 
641 GRASSROOTS_SERVICE_API bool GetParameterTypeForNamedParameter (const struct Service *service_p, const char *param_name_s, ParameterType *pt_p);
642 
643 
651 GRASSROOTS_SERVICE_API char *GetServiceUUIDAsString (Service *service_p);
652 
653 
660 GRASSROOTS_SERVICE_API void FreeService (Service *service_p);
661 
662 
670 GRASSROOTS_SERVICE_API void ReleaseService (Service *service_p);
671 
672 
673 
683 GRASSROOTS_SERVICE_API void SetServiceReleaseFunction (Service *service_p, void (*release_fn) (Service *service_p));
684 
685 
695 GRASSROOTS_SERVICE_LOCAL void ReleaseServiceData (ServiceData *data_p);
696 
704 GRASSROOTS_SERVICE_API ServiceNode *AllocateServiceNode (Service *service_p);
705 
706 
713 GRASSROOTS_SERVICE_API void FreeServiceNode (ListItem *node_p);
714 
715 
724 GRASSROOTS_SERVICE_API void LoadMatchingServicesByName (GrassrootsServer *grassroots_p, LinkedList *services_p, const char * const services_path_s, const char *service_name_s, const char *service_alias_s, UserDetails *user_p);
725 
726 
736 GRASSROOTS_SERVICE_API void LoadMatchingServices (GrassrootsServer *grassroots_p, LinkedList *services_p, const char * const services_path_s, Resource *resource_p, Handler *handler_p, UserDetails *user_p);
737 
738 
746 GRASSROOTS_SERVICE_API void LoadKeywordServices (GrassrootsServer *grassroots_p, LinkedList *services_p, const char * const services_path_s, UserDetails *user_p);
747 
748 
759 GRASSROOTS_SERVICE_API void AddReferenceServices (GrassrootsServer *grassroots_p, LinkedList *services_p, const char * const references_path_s, const char * const services_path_s, const char *operation_name_s, UserDetails *user_p);
760 
761 
769 GRASSROOTS_SERVICE_API bool CloseService (Service *service_p);
770 
771 
779 GRASSROOTS_SERVICE_API bool IsServiceLive (Service *service_p);
780 
781 
795 GRASSROOTS_SERVICE_API json_t *GetServiceAsJSON (Service * const service_p, Resource *resource_p, UserDetails *user_p, const bool add_id_flag);
796 
797 
805 GRASSROOTS_SERVICE_API const char *GetServiceIcon (const Service *service_p);
806 
807 
808 
816 GRASSROOTS_SERVICE_API const char *GetServiceInformationPage (const Service *service_p);
817 
818 
825 GRASSROOTS_SERVICE_API bool DeallocatePluginService (Plugin * const plugin_p);
826 
827 
844 GRASSROOTS_SERVICE_API json_t *GetServicesListAsJSON (LinkedList *services_list_p, Resource *resource_p, UserDetails *user_p, const bool add_service_ids_flag, ProvidersStateTable *providers_p);
845 
846 
855 GRASSROOTS_SERVICE_API void ReleaseServiceParameters (Service *service_p, ParameterSet *params_p);
856 
857 
864 GRASSROOTS_SERVICE_API void FreeServicesArray (ServicesArray *services_p);
865 
866 
875 GRASSROOTS_SERVICE_API ServicesArray *AllocateServicesArray (const uint32 num_services);
876 
877 
885 GRASSROOTS_SERVICE_LOCAL void AssignPluginForServicesArray (ServicesArray *services_p, Plugin *plugin_p);
886 
887 
896 GRASSROOTS_SERVICE_API bool AddServiceResponseHeader (Service *service_p, json_t *result_json_p);
897 
898 
909 GRASSROOTS_SERVICE_API ServicesArray *GetReferenceServicesFromJSON (json_t *config_p, const char *plugin_name_s, Service *(*get_service_fn) (json_t *config_p, size_t i, GrassrootsServer *grassroots_p), GrassrootsServer *grassroots_p);
910 
911 
920 GRASSROOTS_SERVICE_API OperationStatus GetCurrentServiceStatus (Service *service_p, const uuid_t service_id);
921 
922 
930 GRASSROOTS_SERVICE_LOCAL OperationStatus DefaultGetServiceStatus (Service *service_p, const uuid_t service_id);
931 
932 
947 GRASSROOTS_SERVICE_API bool CreateAndAddPairedService (Service *service_p, struct ExternalServer *external_server_p, const char *remote_service_name_s, const json_t *op_p, const json_t *provider_p);
948 
949 
958 GRASSROOTS_SERVICE_API bool AddPairedService (Service *service_p, PairedService *paired_service_p);
959 
960 
969 GRASSROOTS_SERVICE_API bool CreateAndAddLinkedService (Service *service_p, const json_t *service_config_p, GrassrootsServer *grassroots_p);
970 
971 
980 GRASSROOTS_SERVICE_API bool AddLinkedService (Service *service_p, LinkedService *paired_service_p);
981 
982 
983 
998 GRASSROOTS_SERVICE_API json_t *GetServiceRunRequest (const char * const service_name_s, const ParameterSet *params_p, const SchemaVersion *sv_p, const bool run_flag, const ParameterLevel level);
999 
1000 
1014 GRASSROOTS_SERVICE_API json_t *GetServiceRefreshRequest (const char * const service_name_s, const ParameterSet *params_p, const SchemaVersion *sv_p, const bool run_flag, const ParameterLevel level);
1015 
1016 
1031 GRASSROOTS_SERVICE_API json_t *GetServiceRefreshRequest (const char * const service_name_s, const ParameterSet *params_p, const SchemaVersion *sv_p, const bool run_flag, const ParameterLevel level);
1032 
1033 
1034 
1054 GRASSROOTS_SERVICE_API json_t *GetInterestedServiceJSON (Service *service_p, const char *keyword_s, const ParameterSet * const params_p, const bool full_definition_flag);
1055 
1056 
1067 GRASSROOTS_SERVICE_API void SetServiceJobCustomFunctions (Service *service_p, struct ServiceJob *job_p);
1068 
1069 
1077 GRASSROOTS_SERVICE_API bool IsServiceRunning (Service *service_p);
1078 
1079 
1087 GRASSROOTS_SERVICE_API void SetServiceRunning (Service *service_p, bool b);
1088 
1089 
1099 GRASSROOTS_SERVICE_API void SetMetadataForService (Service *service_p, SchemaTerm *category_p, SchemaTerm *subcategory_p);
1100 
1101 
1102 
1103 
1113 GRASSROOTS_SERVICE_API bool AddServiceJobToService (Service *service_p, ServiceJob *job_p);
1114 
1115 
1125 GRASSROOTS_SERVICE_API bool RemoveServiceJobFromService (Service *service_p, ServiceJob *job_p);
1126 
1127 
1128 
1137 GRASSROOTS_SERVICE_API int32 GetNumberOfLiveJobs (Service *service_p);
1138 
1139 
1148 GRASSROOTS_SERVICE_API bool IsServiceLockable (const Service *service_p);
1149 
1150 
1160 GRASSROOTS_SERVICE_API bool LockService (Service *service_p);
1161 
1162 
1172 GRASSROOTS_SERVICE_API bool UnlockService (Service *service_p);
1173 
1174 
1175 GRASSROOTS_SERVICE_API bool SortServicesListByName (LinkedList *services_list_p);
1176 
1177 
1178 GRASSROOTS_SERVICE_API json_t *GetBaseServiceDataAsJSON (Service * const service_p, UserDetails *user_p);
1179 
1180 
1181 GRASSROOTS_SERVICE_API GrassrootsServer *GetGrassrootsServerFromService (const Service * const service_p);
1182 
1183 #ifdef __cplusplus
1184 }
1185 #endif
1186 
1187 
1188 #endif /* #ifndef GRASSROOTS_SERVICE_H */
OperationStatus GetCurrentServiceStatus(Service *service_p, const uuid_t service_id)
Get the OperationStatus for an operation in a Service.
bool se_running_flag
A flag to specify whether this Service is currently running.
Definition: service.h:343
ServicesArray * GetServicesFromPlugin(Plugin *const plugin_p, UserDetails *user_p)
Get the ServicesArray from a given Plugin.
void(* se_customise_service_job_fn)(struct Service *service_p, struct ServiceJob *job_p)
This function is used to customise any ServiceJob objects that this Service creates.
Definition: service.h:247
A datatype for specifying ontological terms as a way to describe the data that each of the Services c...
Definition: schema_term.h:38
bool AddPairedService(Service *service_p, PairedService *paired_service_p)
Add a PairedService to a Service.
A doubly-linked node that points to its predecessor and successor.
Definition: linked_list.h:43
A datatype for describing the type of application that a Service provides.
Definition: service_metadata.h:39
ParameterType
The different types that a Parameter can take.
Definition: parameter_type.h:35
uint32 sa_num_services
The number of Services in the array.
Definition: service.h:414
bool IsServiceLockable(const Service *service_p)
Is a given Service lockable with a mutex for use in a multi-threaded situation.
json_t * GetServiceIndexingData(Service *service_p)
Get a JSON document containing the data that can be parsed by an indexing app such as Lucene.
ServiceMetadata * se_metadata_p
The ServiceMetadata for this Service.
Definition: service.h:348
bool InitialiseService(Service *const service_p, const char *(*get_service_name_fn)(const Service *service_p), const char *(*get_service_description_fn)(const Service *service_p), const char *(*get_service_alias_fn)(const Service *service_p), const char *(*get_service_info_uri_fn)(const Service *service_p), struct ServiceJobSet *(*run_fn)(Service *service_p, ParameterSet *param_set_p, UserDetails *user_p, ProvidersStateTable *providers_p), ParameterSet *(*match_fn)(Service *service_p, Resource *resource_p, Handler *handler_p), ParameterSet *(*get_parameters_fn)(Service *service_p, Resource *resource_p, UserDetails *user_p), bool(*get_parameter_type_fn)(const Service *service_p, const char *param_name_s, ParameterType *pt_p), void(*release_parameters_fn)(Service *service_p, ParameterSet *params_p), bool(*close_fn)(Service *service_p), void(*customise_service_job_fn)(Service *service_p, struct ServiceJob *job_p), bool specific_flag, Synchronicity synchronous, ServiceData *data_p, ServiceMetadata *(*get_metadata_fn)(Service *service_p), json_t *(*get_indexing_data_fn)(Service *service_p), GrassrootsServer *grassroots_p)
Initialise the basic structure of a Service.
void LoadKeywordServices(GrassrootsServer *grassroots_p, LinkedList *services_p, const char *const services_path_s, UserDetails *user_p)
Load all Services that can be run upon a keyword parameter.
bool(* se_has_permissions_fn)(struct Service *service_p, ParameterSet *params_p, const UserDetails *const user_p)
Check whether the user have permissions to run the Service.
Definition: service.h:206
A datatype for describing a remote Service that can be used in conjunction with a local Service.
Definition: paired_service.h:59
A task that runs synchronously.
Definition: service.h:104
ServicesArray * GetReferenceServicesFromJSON(json_t *config_p, const char *plugin_name_s, Service *(*get_service_fn)(json_t *config_p, size_t i, GrassrootsServer *grassroots_p), GrassrootsServer *grassroots_p)
Get the ServicesArray generated from a Services reference file.
json_t * GetServiceRefreshRequest(const char *const service_name_s, const ParameterSet *params_p, const SchemaVersion *sv_p, const bool run_flag, const ParameterLevel level)
Get the JSON fragment for sending to a Grassroots Server detailing how to update the parameters for a...
void LoadMatchingServices(GrassrootsServer *grassroots_p, LinkedList *services_p, const char *const services_path_s, Resource *resource_p, Handler *handler_p, UserDetails *user_p)
Load the Services that are able to act upon a given Resource.
struct ServiceJob * CreateSerialisedServiceJobFromService(struct Service *service_p, const json_t *service_job_json_p)
Function to parse a JSON fragment from a previously serialised ServiceJob.
json_t * GetServiceAsJSON(Service *const service_p, Resource *resource_p, UserDetails *user_p, const bool add_id_flag)
Generate a json-based description of a Service.
bool UnlockService(Service *service_p)
Release the lock for a given Service in a multi-threaded situation.
bool IsServiceRunning(Service *service_p)
Check if a Service is currently running any ServiceJobs.
A datatype to represent a collection of ServiceJobs.
Definition: service_job.h:182
void LoadMatchingServicesByName(GrassrootsServer *grassroots_p, LinkedList *services_p, const char *const services_path_s, const char *service_name_s, const char *service_alias_s, UserDetails *user_p)
Load the Service that matches a given service name.
void ReleaseServiceParameters(Service *service_p, ParameterSet *params_p)
Free a ParameterSet that was got from a call to GetServiceParameters.
void FreeService(Service *service_p)
Free a Service and its associated Parameters and ServiceData.
json_t * GetServicesListAsJSON(LinkedList *services_list_p, Resource *resource_p, UserDetails *user_p, const bool add_service_ids_flag, ProvidersStateTable *providers_p)
Get the JSON fragment for exposing a list of Services to any interested Clients or ExternalServcers.
bool DeallocatePluginService(Plugin *const plugin_p)
Close a Services-based Plugin and free all of the Services.
const char * GetServiceInformationPage(const Service *service_p)
Get the URL of a web page describing a given Service.
bool(* se_get_parameter_type_fn)(const struct Service *service_p, const char *param_name_s, ParameterType *pt_p)
Callback function used to get the ParameterType of a named Parameter used by the given Service.
Definition: service.h:310
A datatype to allow access to an external Grassroots Server.
Definition: servers_manager.h:48
SyncData * se_sync_data_p
If the Service's synchronicity is set to SY_ASYNCHRONOUS_ATTACHED, this is used as mutex to control a...
Definition: service.h:364
struct ServiceJobSet * se_jobs_p
The ServiceJobSet for this Service.
Definition: service.h:322
struct Service * sd_service_p
The service that owns this data.
Definition: service.h:129
Synchronicity
A datatye to define how a Service runs.
Definition: service.h:101
void FreeServiceNode(ListItem *node_p)
Free a ServiceNode.
void FreeServicesArray(ServicesArray *services_p)
Free a ServicesArray and each of its Services.
Service ** sa_services_pp
An array of pointers to Services.
Definition: service.h:411
const char * GetServiceInformationURI(const Service *service_p)
Get the address of a web page about the service.
const char * GetServiceIcon(const Service *service_p)
Get the URL of an icon image to use for a given Service.
Synchronicity se_synchronous
The synchronicity for how this Service runs.
Definition: service.h:316
This is a datatype to store the versioning details for the Grassroots JSON schema that is being used.
Definition: schema_version.h:44
void SetServiceReleaseFunction(Service *service_p, void(*release_fn)(Service *service_p))
For an asynchronous Service, set the function that will be called if ReleaseService() is called.
ServicesArray * AllocateServicesArray(const uint32 num_services)
Allocate an empty ServicesArray.
ListItem sn_node
The List Node.
Definition: service.h:396
bool IsServiceLive(Service *service_p)
Has the Service got any jobs still running?
struct Plugin * se_plugin_p
The platform-specific plugin that the code for the Service is stored in.
Definition: service.h:159
int32 GetNumberOfLiveJobs(Service *service_p)
Check if any ServiceJobs within Service are still running.
A doubly-linked list.
bool CloseService(Service *service_p)
Close a Service.
A datatype for holding the configuration data for a Service.
Definition: service.h:126
bool CreateAndAddLinkedService(Service *service_p, const json_t *service_config_p, GrassrootsServer *grassroots_p)
Create and add a LinkedService to a Service.
A datatype which defines an available service, its capabilities and its parameters.
Definition: service.h:153
bool se_is_specific_service_flag
Is the service self-contained.
Definition: service.h:168
bool AddServiceResponseHeader(Service *service_p, json_t *result_json_p)
Add a JSON fragment to the response for a given Service that has been run.
void ReleaseService(Service *service_p)
For an asynchronous Service, tell it that it is no longer needed by the Grassroots system.
A doubly-linked list that can be traversed in either direction.
Definition: linked_list.h:56
ParameterSet * GetServiceParameters(Service *service_p, Resource *resource_p, UserDetails *user_p)
Get a newly-created ParameterSet describing the parameters for a given Service.
A Plugin is a dynamically-loaded component to provide a piece of functionality.
Definition: plugin.h:151
ParameterSet * IsServiceMatch(Service *service_p, Resource *resource_p, Handler *handler_p)
Is the Service able to work upon the given Resource.
bool CreateAndAddPairedService(Service *service_p, struct ExternalServer *external_server_p, const char *remote_service_name_s, const json_t *op_p, const json_t *provider_p)
Create a new PairedService and add it to a Service.
A task that runs asynchronously outside of the Grassroots system such as e.g drmaa jobs.
Definition: service.h:110
bool AddLinkedService(Service *service_p, LinkedService *paired_service_p)
Add a LinkedService to a Service.
uuid_t se_id
Unique Id for this service.
Definition: service.h:319
ParameterLevel
The ParameterLevel defines the level that a user should be to adjust the Parameter.
Definition: parameter.h:52
Service * GetServiceByName(GrassrootsServer *grassroots_p, const char *const service_name_s, const char *const service_alias_s)
Get a Service by its name.
A task runs asynchronously within the Grassroots system such as e.g threaded jobs.
Definition: service.h:116
bool(* se_close_fn)(struct Service *service_p)
Function to close this Service.
Definition: service.h:262
json_t * CreateSerialisedJSONForServiceJobFromService(struct Service *service_p, struct ServiceJob *service_job_p, bool omit_results_flag)
Function to create a JSON fragment representing a serialised ServiceJob.
GRASSROOTS_SERVICE_API const char * SERVICES_PATH_S
This specifies the relative filesystem path to where the Service plugins are stored.
Definition: service.h:78
OperationStatus
The current status of an Operation.
Definition: operation.h:98
bool AddServiceJobToService(Service *service_p, ServiceJob *job_p)
Add a ServiceJob to a Service.
char * GetServiceUUIDAsString(Service *service_p)
Get the unique id of a service object.
ServiceData * se_data_p
Any custom data that the service needs to store.
Definition: service.h:336
bool GetParameterTypeForNamedParameter(const struct Service *service_p, const char *param_name_s, ParameterType *pt_p)
Get the ParameterType of a named Parameter used by the given Service.
bool DoesServiceHaveCustomServiceJobSerialisation(struct Service *service_p)
Does the Service use the default ServiceJob serialisation/deserialisation when storing ServiceJobs in...
A datatype that allows data to be shared between tasks (e.g.
Definition: unix_sync_data.h:30
void SetServiceJobCustomFunctions(Service *service_p, struct ServiceJob *job_p)
This function is used to customise any ServiceJob objects that a given Service creates.
A datatype to represent a running task.
Definition: service_job.h:72
A datatype for having a set of Services.
Definition: service.h:408
A datatype for storing Services on a LinkedList.
Definition: service.h:393
struct ServiceJobSet * RunService(Service *service_p, ParameterSet *param_set_p, UserDetails *user_p, ProvidersStateTable *providers_p)
Run a Service.
A datatype to store user credentials.
Definition: user_details.h:76
void SetServiceRunning(Service *service_p, bool b)
Set if a Service is currently running any ServiceJobs or not.
LinkedList se_paired_services
Any remote Services that are paired with this Service.
Definition: service.h:325
void(* se_release_params_fn)(struct Service *service_p, ParameterSet *params_p)
Function to release the ParameterSet for this Service.
Definition: service.h:253
void SetMetadataForService(Service *service_p, SchemaTerm *category_p, SchemaTerm *subcategory_p)
Set the values of a Service's ServiceMetadata object.
This is a datatype that is used to keep track of which servers and services have already been process...
Definition: providers_state_table.h:49
const char * GetServiceName(const Service *service_p)
Get the user-friendly name of the service.
bool RemoveServiceJobFromService(Service *service_p, ServiceJob *job_p)
Remove a ServiceJob from a Service.
bool(* se_process_linked_services_fn)(struct Service *service_p, struct ServiceJob *job_p, LinkedService *linked_service_p)
Callback function used when processing the results from running ServiceJobs for this Service as input...
Definition: service.h:298
bool sd_config_flag
If this is true, then this ServiceData will decrease the reference count on sd_config_p when this Ser...
Definition: service.h:141
Definition: grassroots_server.h:44
const char * GetServiceDescription(const Service *service_p)
Get the user-friendly description of the service.
A Handler is a datatype for accessing data.
Definition: handler.h:72
A datatype representing a URI.
Definition: data_resource.h:40
json_t * GetInterestedServiceJSON(Service *service_p, const char *keyword_s, const ParameterSet *const params_p, const bool full_definition_flag)
Get the JSON fragment for a job result list registering that a Service could be run against the user'...
bool LockService(Service *service_p)
Lock a given Service with a mutex for use in a multi-threaded situation.
ServicesArray * GetReferrableServicesFromPlugin(Plugin *const plugin_p, UserDetails *user_p, const json_t *service_config_p)
Get the ServicesArray from a given Plugin.
Service * sn_service_p
The Service.
Definition: service.h:399
LinkedList se_linked_services
Any LinkedServices that will use the output from running this Service as input for itself.
Definition: service.h:331
json_t * sd_config_p
If this service has an entry in global server config it will be stored here.
Definition: service.h:135
A set of Parameters along with an optional name and description.
Definition: parameter_set.h:46
This datatype stores the data needed to get the required information from the output of one Service t...
Definition: linked_service.h:50
void(* se_release_service_fn)(struct Service *service_p)
A custom callback function to use to close the service if needed.
Definition: service.h:371
ServiceNode * AllocateServiceNode(Service *service_p)
Allocate a ServiceNode pointing to the given Service.
json_t * GetServiceRunRequest(const char *const service_name_s, const ParameterSet *params_p, const SchemaVersion *sv_p, const bool run_flag, const ParameterLevel level)
Get the JSON fragment for sending to a Grassroots Server detailing whether and how a user wants a Ser...
void AddReferenceServices(GrassrootsServer *grassroots_p, LinkedList *services_p, const char *const references_path_s, const char *const services_path_s, const char *operation_name_s, UserDetails *user_p)
Add any reference Services to the list of available Services.