service.h File Reference
#include "grassroots_service_library.h"
#include "byte_buffer.h"
#include "linked_list.h"
#include "parameter_set.h"
#include "typedefs.h"
#include "handler.h"
#include "user_details.h"
#include "operation.h"
#include "paired_service.h"
#include "linked_service.h"
#include "uuid/uuid.h"
#include "service_metadata.h"
#include "sync_data.h"
#include "jansson.h"
#include "providers_state_table.h"
Include dependency graph for service.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ServiceData
 A datatype for holding the configuration data for a Service. More...
 
struct  Service
 A datatype which defines an available service, its capabilities and its parameters. More...
 
struct  ServiceNode
 A datatype for storing Services on a LinkedList. More...
 
struct  ServicesArray
 A datatype for having a set of Services. More...
 

Enumerations

enum  Synchronicity { SY_SYNCHRONOUS, SY_ASYNCHRONOUS_DETACHED, SY_ASYNCHRONOUS_ATTACHED }
 A datatye to define how a Service runs. More...
 

Functions

ServicesArrayGetReferrableServicesFromPlugin (Plugin *const plugin_p, UserDetails *user_p, const json_t *service_config_p)
 Get the ServicesArray from a given Plugin. More...
 
ServicesArrayGetServicesFromPlugin (Plugin *const plugin_p, UserDetails *user_p)
 Get the ServicesArray from a given Plugin. More...
 
void LoadMatchingServicesByName (LinkedList *services_p, const char *relative_url_s, const char *const services_path_s, const char *service_name_s, UserDetails *user_p)
 Load the Service that matches a given service name. More...
 
void LoadMatchingServices (LinkedList *services_p, const char *relative_url_s, 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. More...
 
void LoadKeywordServices (LinkedList *services_p, const char *relative_url_s, const char *const services_path_s, UserDetails *user_p)
 Load all Services that can be run upon a keyword parameter. More...
 
void AddReferenceServices (LinkedList *services_p, const char *relative_url_s, 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. More...
 
bool DeallocatePluginService (Plugin *const plugin_p)
 Close a Services-based Plugin and free all of the Services. More...
 
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. More...
 
json_t * GetServiceRunRequest (const char *const service_name_s, const ParameterSet *params_p, const SchemaVersion *sv_p, const bool run_flag)
 Get the JSON fragment for sending to a Grassroots Server detailing whether and how a user wants a Service to run. More...
 
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's parameters. More...
 
void SetServiceJobCustomFunctions (Service *service_p, struct ServiceJob *job_p)
 This function is used to customise any ServiceJob objects that a given Service creates. More...
 
bool SortServicesListByName (LinkedList *services_list_p)
 
json_t * GetBaseServiceDataAsJSON (Service *const service_p, UserDetails *user_p)
 

Variables

GRASSROOTS_SERVICE_API const char * SERVICES_PATH_S = "services"
 This specifies the relative filesystem path to where the Service plugins are stored. More...
 
GRASSROOTS_SERVICE_API const char * REFERENCES_PATH_S = "references"
 This specifies the relative filesystem path to where the Referred Service configuration files are stored. More...
 

Function Documentation

◆ GetReferrableServicesFromPlugin()

ServicesArray* GetReferrableServicesFromPlugin ( Plugin *const  plugin_p,
UserDetails user_p,
const json_t *  service_config_p 
)

Get the ServicesArray from a given Plugin.

Parameters
plugin_pThe Plugin to get the ServicesArray from.
user_pAny user configuration details. This can be NULL.
service_config_pAny service configuration details.
Returns
The ServicesArray or NULL upon error.

◆ GetServicesFromPlugin()

ServicesArray* GetServicesFromPlugin ( Plugin *const  plugin_p,
UserDetails user_p 
)

Get the ServicesArray from a given Plugin.

Parameters
plugin_pThe Plugin to get the ServicesArray from.
user_pAny user configuration details. This can be NULL.
Returns
The ServicesArray or NULL upon error.

◆ LoadMatchingServicesByName()

void LoadMatchingServicesByName ( LinkedList services_p,
const char *  relative_url_s,
const char *const  services_path_s,
const char *  service_name_s,
UserDetails user_p 
)

Load the Service that matches a given service name.

Parameters
services_pThe List of Services that the named Services will get appended to if it is found successfully.
services_path_sThe directory where the Service modules are stored.
service_name_sThe name of the Service to find.
user_pAny user configuration details, this can be NULL.

◆ LoadMatchingServices()

void LoadMatchingServices ( LinkedList services_p,
const char *  relative_url_s,
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.

Parameters
services_pThe List of Services that the named Services will get appended to if it is found successfully.
services_path_sThe directory where the Service modules are stored.
resource_pThe Resource to check for matching Services for.
handler_pThe Handler that is appropriate for the given Resource.
user_pAny user configuration details, this can be NULL.

◆ LoadKeywordServices()

void LoadKeywordServices ( LinkedList services_p,
const char *  relative_url_s,
const char *const  services_path_s,
UserDetails user_p 
)

Load all Services that can be run upon a keyword parameter.

Parameters
services_pThe List of Services that any keyword-aware Services will get appended to.
services_path_sThe directory where the Service modules are stored.
user_pAny user configuration details, this can be NULL.

◆ AddReferenceServices()

void AddReferenceServices ( LinkedList services_p,
const char *  relative_url_s,
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.

Parameters
services_pThe LinkedList of ServiceNodes to add any referred Services to.
references_path_sThe directory containing the JSON definitions of reference services.
services_path_sThe directory containing the Service plugins.
operation_name_sIf this value is set, only referred Services that have an Operation with this name will be added to Services list. If this is NULL then all possible reference Services will be added.
user_pAny user configuration details, this can be NULL.

◆ DeallocatePluginService()

bool DeallocatePluginService ( Plugin *const  plugin_p)

Close a Services-based Plugin and free all of the Services.

Parameters
plugin_pThe Plugin to free the Services from.
Returns
true if the Services were successfully released, false otherwise.

◆ GetServicesListAsJSON()

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.

Parameters
services_list_pA LinkedList of ServiceNodes detailing the Services to generate the fragment for
resource_pThe Resource of interest to run the Services with. This can be NULL.
user_pAny UserDetails for access o potentially restricted Services. This can be NULL for only publicly accessible Services.
add_service_ids_flagIf this is true then the UUID of the Service will be added to the returned JSON. If this is false then it will not.
providers_pThis is used to keep track of which ExternalServers and their Services have already been processed when generating the JSON fragment.
Returns
The json-based representation of the Service or NULL if there was an error.
See also
GetServiceAsJSON

◆ GetServiceRunRequest()

json_t* GetServiceRunRequest ( const char *const  service_name_s,
const ParameterSet params_p,
const SchemaVersion sv_p,
const bool  run_flag 
)

Get the JSON fragment for sending to a Grassroots Server detailing whether and how a user wants a Service to run.

This object needs to be within a JSON array which is what the Server requires.

Parameters
service_name_sThe name of the Service to get the JSON fragment for.
params_pThe ParameterSet to use. If run_flag is false, then this can be NULL.
sv_pIf you wish to create a JSON fragment for a different version of the Grassroots system, then you can set this value to the version that you require. If this is NULL, then the current version of the running Grassroots system will be used.
run_flagWhether the Service should be run or not.
Returns
The JSON fragment to be added to an array to send to the Server or NULL upon error.

◆ GetInterestedServiceJSON()

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's parameters.

This is of use when running a keyword search and specifying that a Service knows of this keyword but cannot run on it directly. For example, a Blast Service might know that the keyword refers to some if its databases.

Parameters
service_pThe Service that has registered an interest in the given keyword.
keyword_sThe keyword.
params_pThe parameters to encode within the JSON fragment. This will be set up based upon the keyword used to check whether the Service was interested.
full_definition_flagThis should be set to true when a Server is exposing its Services and false when a request to run a Service is being generated. See GetParameterAsJSON for more information.
Returns
The JSON fragment to send to the Server or NULL upon error.
See also
IsServiceMatch
GetParameterAsJSON

◆ SetServiceJobCustomFunctions()

void SetServiceJobCustomFunctions ( Service service_p,
struct ServiceJob job_p 
)

This function is used to customise any ServiceJob objects that a given Service creates.

It is often used to automatically set the sj_update_fn and sj_free_fn members of a ServiceJob.

Parameters
service_pThe Service to set the custom ServiceJob functions for.
job_pThe ServiceJob to customise.
See also
ServiceJob
se_customise_service_job_fn

Variable Documentation

◆ SERVICES_PATH_S

GRASSROOTS_SERVICE_API const char* SERVICES_PATH_S = "services"

This specifies the relative filesystem path to where the Service plugins are stored.

◆ REFERENCES_PATH_S

GRASSROOTS_SERVICE_API const char* REFERENCES_PATH_S = "references"

This specifies the relative filesystem path to where the Referred Service configuration files are stored.