A datatype which defines an available service, its capabilities and its parameters. More...

#include <service.h>

Collaboration diagram for Service:

Public Member Functions
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, User user_p, ProvidersStateTable providers_p), ParameterSet (match_fn)(Service service_p, DataResource resource_p, Handler handler_p), ParameterSet (get_parameters_fn)(Service service_p, DataResource resource_p, User 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. More...

struct ServiceJobSet *	RunService (Service service_p, ParameterSet param_set_p, User user_p, ProvidersStateTable providers_p)
	Run a Service. More...

bool	DoesServiceHaveCustomServiceJobSerialisation (struct Service *service_p)
	Does the Service use the default ServiceJob serialisation/deserialisation when storing ServiceJobs in the JobsManager or does it use its own specialised routines? More...

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. More...

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. More...

ParameterSet *	IsServiceMatch (Service service_p, DataResource resource_p, Handler *handler_p)
	Is the Service able to work upon the given Resource. More...

const char *	GetServiceName (const Service *service_p)
	Get the user-friendly name of the service. More...

const char *	GetServiceDescription (const Service *service_p)
	Get the user-friendly description of the service. More...

const char *	GetServiceAlias (const Service *service_p)
	Get the alias of the service. More...

json_t *	GetServiceIndexingData (Service *service_p)
	Get a JSON document containing the data that can be parsed by an indexing app such as Lucene. More...

const char *	GetServiceInformationURI (const Service *service_p)
	Get the address of a web page about the service. More...

ParameterSet *	GetServiceParameters (Service service_p, DataResource resource_p, User *user_p)
	Get a newly-created ParameterSet describing the parameters for a given Service. More...

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. More...

char *	GetServiceUUIDAsString (Service *service_p)
	Get the unique id of a service object. More...

void	FreeService (Service *service_p)
	Free a Service and its associated Parameters and ServiceData. More...

void	ReleaseService (Service *service_p)
	For an asynchronous Service, tell it that it is no longer needed by the Grassroots system. More...

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. More...

bool	CloseService (Service *service_p)
	Close a Service. More...

json_t *	GetServiceAsJSON (Service const service_p, DataResource resource_p, User *user_p, const bool add_id_flag)
	Generate a json-based description of a Service. More...

const char *	GetServiceIcon (const Service *service_p)
	Get the URL of an icon image to use for a given Service. More...

const char *	GetServiceInformationPage (const Service *service_p)
	Get the URL of a web page describing a given Service. 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, DataResource resource_p, User 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...

void	ReleaseServiceParameters (Service service_p, ParameterSet params_p)
	Free a ParameterSet that was got from a call to `GetServiceParameters`. More...

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. More...

OperationStatus	GetCurrentServiceStatus (Service *service_p, const uuid_t service_id)
	Get the OperationStatus for an operation in a Service. More...

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. More...

bool	AddPairedService (Service service_p, PairedService paired_service_p)
	Add a PairedService to a Service. More...

bool	CreateAndAddLinkedService (Service service_p, const json_t service_config_p, GrassrootsServer *grassroots_p)
	Create and add a LinkedService to a Service. More...

bool	AddLinkedService (Service service_p, LinkedService paired_service_p)
	Add a LinkedService to a Service. More...

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 Service to run. More...

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 Service. 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	IsServiceRunning (Service *service_p)
	Check if a Service is currently running any ServiceJobs. More...

void	SetServiceRunning (Service *service_p, bool b)
	Set if a Service is currently running any ServiceJobs or not. More...

void	SetMetadataForService (Service service_p, SchemaTerm category_p, SchemaTerm *subcategory_p)
	Set the values of a Service's ServiceMetadata object. More...

GrassrootsServer *	GetGrassrootsServerFromService (const Service *const service_p)
	Get the GrassrootsServer that the Service is running on. More...

void	LoadMatchingServicesByName (GrassrootsServer grassroots_p, LinkedList services_p, const char service_name_s, const char service_alias_s, User *user_p)
	Load the Service that matches a given service name. More...

void	LoadMatchingServices (GrassrootsServer grassroots_p, LinkedList services_p, DataResource resource_p, Handler handler_p, User *user_p)
	Load the Services that are able to act upon a given Resource. More...

void	LoadKeywordServices (GrassrootsServer grassroots_p, LinkedList services_p, User *user_p)
	Load all Services that can be run upon a keyword parameter. More...

void	AddReferenceServices (GrassrootsServer grassroots_p, LinkedList services_p, const char operation_name_s, User user_p)
	Add any reference Services to the list of available Services. More...

struct Service *	GetServiceByName (GrassrootsServer grassroots_p, const char const service_name_s, const char *const service_alias_s)
	Get a Service by its name. More...

Data Fields
struct Plugin *	se_plugin_p
	The platform-specific plugin that the code for the Service is stored in. More...

bool	se_is_specific_service_flag
	Is the service self-contained. More...

struct ServiceJobSet (	se_run_fn )(struct Service service_p, ParameterSet param_set_p, User user_p, ProvidersStateTable providers_p)
	Run this Service. More...

ParameterSet (	se_match_fn )(struct Service service_p, DataResource resource_p, Handler *handler_p)
	Is the Service able to work upon the given Resource. More...

bool(*	se_has_permissions_fn )(struct Service service_p, ParameterSet params_p, const User *const user_p)
	Check whether the user have permissions to run the Service. More...

const char (	se_get_service_name_fn )(const struct Service *service_p)
	Function to get the user-friendly name of the service. More...

const char (	se_get_service_description_fn )(const struct Service *service_p)
	Function to get the user-friendly description of the service. More...

const char (	se_get_service_alias_fn )(const struct Service *service_p)
	Function to get the alias for a service. More...

const char (	se_get_service_info_uri_fn )(const struct Service *service_p)
	Function to get a web address for more information about the service. More...

ParameterSet (	se_get_params_fn )(struct Service service_p, DataResource resource_p, User *user_p)
	Function to get the ParameterSet for this Service. More...

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. More...

void(*	se_release_params_fn )(struct Service service_p, ParameterSet params_p)
	Function to release the ParameterSet for this Service. More...

bool(*	se_close_fn )(struct Service *service_p)
	Function to close this Service. More...

struct ServiceJob (	se_deserialise_job_json_fn )(struct Service service_p, const json_t service_job_json_p)
	Function to parse a JSON fragment from a previously serialised ServiceJob created by this Service. More...

json_t (	se_serialise_job_json_fn )(struct Service service_p, struct ServiceJob service_job_p, bool omit_results_flag)
	Function to create a JSON fragment representing a serialised ServiceJob. More...

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 for any LinkedServices for this Service. More...

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. More...

Synchronicity	se_synchronous
	The synchronicity for how this Service runs. More...

uuid_t	se_id
	Unique Id for this service. More...

struct ServiceJobSet *	se_jobs_p
	The ServiceJobSet for this Service. More...

LinkedList	se_paired_services
	Any remote Services that are paired with this Service. More...

LinkedList	se_linked_services
	Any LinkedServices that will use the output from running this Service as input for itself. More...

ServiceData *	se_data_p
	Any custom data that the service needs to store. More...

bool	se_running_flag
	A flag to specify whether this Service is currently running. More...

ServiceMetadata *	se_metadata_p
	The ServiceMetadata for this Service. More...

ServiceMetadata (	se_get_metadata_fn )(struct Service *service_p)
	Callback function used to create a Service's ServiceMetadata. More...

SyncData *	se_sync_data_p
	If the Service's synchronicity is set to SY_ASYNCHRONOUS_ATTACHED, this is used as mutex to control access to this Service when needed. More...

void(*	se_release_service_fn )(struct Service *service_p)
	A custom callback function to use to close the service if needed. More...

json_t (	se_get_indexing_data_fn )(struct Service *service_p)
	A custom callback function to get the data that can be be used to import into an indexing app like Lucene. More...

Parameter (	se_custom_parameter_decoder_fn )(struct Service service_p, json_t param_json_p, const bool concise_flag)
	If the service has to have a more complex method of creating parameters from json blobs than the standard method, use this custom callback function. More...

GrassrootsServer *	se_grassroots_p
	The server that this service is running on. More...

Detailed Description

A datatype which defines an available service, its capabilities and its parameters.

Member Function Documentation

◆ InitialiseService()

bool InitialiseService	(	Service *const	service_p,
		const char ()(const Service *service_p)	get_service_name_fn,
		const char ()(const Service *service_p)	get_service_description_fn,
		const char ()(const Service *service_p)	get_service_alias_fn,
		const char ()(const Service *service_p)	get_service_info_uri_fn,
		struct ServiceJobSet ()(Service service_p, ParameterSet param_set_p, User user_p, ProvidersStateTable providers_p)	run_fn,
		ParameterSet ()(Service service_p, DataResource resource_p, Handler *handler_p)	match_fn,
		ParameterSet ()(Service service_p, DataResource resource_p, User *user_p)	get_parameters_fn,
		bool()(const Service service_p, const char param_name_s, ParameterType pt_p)	get_parameter_type_fn,
		void()(Service service_p, ParameterSet *params_p)	release_parameters_fn,
		bool()(Service service_p)	close_fn,
		void()(Service service_p, struct ServiceJob *job_p)	customise_service_job_fn,
		bool	specific_flag,
		Synchronicity	synchronous,
		ServiceData *	data_p,
		ServiceMetadata ()(Service *service_p)	get_metadata_fn,
		json_t ()(Service *service_p)	get_indexing_data_fn,
		GrassrootsServer *	grassroots_p
	)

Initialise the basic structure of a Service.

Parameters

service_p	The Service to initialise.
get_service_name_fn	The callback function that the Service will call to get its name.
get_service_description_fn	The callback function that the Service will call to get its description.
get_service_alias_fn	The callback function that the Service will call to get its alias.
get_service_info_uri_fn	The callback function that the Service will call to get a web address for more information about the Service. This can be `NULL`.
run_fn	The callback function that the Service will call to run itself.
match_fn	The callback function that the Service will call to check whether it is an appropriate Service for a given Resource.
get_parameters_fn	The callback function that the Service will call to get its ParameterSet.
release_parameters_fn	The callback function that the Service will call to free a ParameterSet returned from a previous call to get its ParameterSet.
close_fn	The callback function that the Service will call when the Service is closed.
customise_service_job_fn	If the ServiceJobs that this Service uses are extended from the Base ServiceJob datatype, this function is used to set them up. This can be `NULL`.
specific_flag	`true` if this Service performs a specific analysis. For Services used by scripted reference Services detailed by JSON configuration files, then this should be `false`.
synchronous	The synchronicity for how this Service runs.
data_p	The ServiceData for this Service.
get_metadata_fn	The callback function that the Service will call to create its ServiceMetadata.
get_indexing_data_fn	The callback function that the Service will call to get its JSON data for indexing..
grassroots_p	The GrassrootsServer that this Service will run on.

Returns: true if the Service was set up successfully, false otherwise.

◆ RunService()

struct ServiceJobSet * RunService	(	Service *	service_p,
		ParameterSet *	param_set_p,
		User *	user_p,
		ProvidersStateTable *	providers_p
	)

Run a Service.

This is a convenience wrapper around se_run_fn.

Parameters

service_p	The Service to run.
param_set_p	The ParameterSet to run the Service with.
user_p	An optional set of User as json.
providers_p	The ProvidersStateTable to be used by any RemoteServices.

Returns: A newly-allocated ServiceJobSet containing the details for the new jobs or NULL upon error.

See also: se_run_fn

◆ DoesServiceHaveCustomServiceJobSerialisation()

bool DoesServiceHaveCustomServiceJobSerialisation ( struct Service * service_p )

Does the Service use the default ServiceJob serialisation/deserialisation when storing ServiceJobs in the JobsManager or does it use its own specialised routines?

Parameters

service_p The Service to check.

Returns: true if the Service use custom routines, false if it uses the standard ones.

◆ CreateSerialisedServiceJobFromService()

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.

Parameters

service_p	A Service of the same type that the serialised ServiceJob was run by.
service_job_json_p	The JSON fragment representing the serialised ServiceJob.

Returns: The newly-constructed ServiceJob or NULL upon error.

See also: se_deserialise_job_fn

◆ CreateSerialisedJSONForServiceJobFromService()

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.

Parameters

service_p	A Service of the same type that the serialised ServiceJob was run by.
service_job_p	The ServiceJob to serialise.
omit_results_flag	If this is `true` then just the minimal status information for the ServiceJob will be returned. If it is `false` then the job results will be included too if possible.

Returns: The JSON fragment representing the serialised ServiceJob or NULL upon error.

See also: se_serialise_job_fn

◆ IsServiceMatch()

ParameterSet * IsServiceMatch	(	Service *	service_p,
		DataResource *	resource_p,
		Handler *	handler_p
	)

Is the Service able to work upon the given Resource.

Parameters

service_p	The Service to check.
resource_p	The Resource to check.
handler_p	A custom Handler for accessing the Resource. This can be NULL.

Returns: If the Service can run on the given Resource, it returns a ParameterSet that is partially filled in using the value of the Resource. If the Service cannot run on the given Resource, this will return NULL.

See also: se_match_fn

◆ GetServiceName()

const char * GetServiceName ( const Service * service_p )

Get the user-friendly name of the service.

Parameters

service_p The Service to get the name for.

Returns: The name of Service.

◆ GetServiceDescription()

const char * GetServiceDescription ( const Service * service_p )

Get the user-friendly description of the service.

Parameters

service_p The Service to get the description for.

Returns: The description of Service.

◆ GetServiceAlias()

const char * GetServiceAlias ( const Service * service_p )

Get the alias of the service.

Parameters

service_p The Service to get the alias for.

Returns: The alias of Service.

◆ GetServiceIndexingData()

json_t * GetServiceIndexingData ( Service * service_p )

Get a JSON document containing the data that can be parsed by an indexing app such as Lucene.

Parameters

service_p The Service to get the data for.

Returns: The JSON document.

◆ GetServiceInformationURI()

const char * GetServiceInformationURI ( const Service * service_p )

Get the address of a web page about the service.

Parameters

service_p The Service to get the description for.

Returns: The address of the page or NULL if there isn't one.

◆ GetServiceParameters()

ParameterSet * GetServiceParameters	(	Service *	service_p,
		DataResource *	resource_p,
		User *	user_p
	)

Get a newly-created ParameterSet describing the parameters for a given Service.

Parameters

service_p	The Service to get the ParameterSet for.
resource_p	This is the input to the Service and can be NULL.
user_p	Any user authorisation details that the Service might need. This can be NULL.

Returns: The newly-created ParameterSet or NULL upon error. This ParameterSet will need to be freed once it is no longer needed by calling FreeParameterSet.

See also: FreeParameterSet.

◆ GetParameterTypeForNamedParameter()

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.

Parameters

service_p	The Service to get the ParameterType from.
param_name_s	The name of the Parameter to get the ParameterType of.
pt_p	Pointer to the ParameterType where the value will be stored.

Returns: true if the ParameterType was retrieved successfully, false otherwise.

◆ GetServiceUUIDAsString()

char * GetServiceUUIDAsString ( Service * service_p )

Get the unique id of a service object.

Parameters

service_p The Service to get the id for.

Returns: The string of the id.

◆ FreeService()

void FreeService ( Service * service_p )

Free a Service and its associated Parameters and ServiceData.

Parameters

service_p The Service to free.

◆ ReleaseService()

void ReleaseService ( Service * service_p )

For an asynchronous Service, tell it that it is no longer needed by the Grassroots system.

Parameters

service_p The Service to release.

◆ SetServiceReleaseFunction()

void SetServiceReleaseFunction	(	Service *	service_p,
		void()(Service service_p)	release_fn
	)

For an asynchronous Service, set the function that will be called if ReleaseService() is called.

Parameters

service_p	The Service to set the release function for.
release_fn	The release function to set for the given Service.

◆ CloseService()

bool CloseService ( Service * service_p )

Close a Service.

Parameters

service_p The Service to close.

Returns: true if the Service was closed successfully, false otherwise.

◆ GetServiceAsJSON()

json_t * GetServiceAsJSON	(	Service *const	service_p,
		DataResource *	resource_p,
		User *	user_p,
		const bool	add_id_flag
	)

Generate a json-based description of a Service.

Parameters

service_p	The Service to generate the description for.
resource_p	An optional Resource for the Service to run on. This can be `NULL`.
user_p	Optional user configuration details. This can be NULL.
add_id_flag	If this is `true` then the UUID of the Service will be added to the returned JSON. If this is `false` then it will not.

Returns: The json-based representation of the Service or NULL if there was an error.

◆ GetServiceIcon()

const char * GetServiceIcon ( const Service * service_p )

Get the URL of an icon image to use for a given Service.

Parameters

service_p The Service to get the icon for.

Returns: The URL of the image to use for the Service. This can be NULL.

◆ GetServiceInformationPage()

const char * GetServiceInformationPage ( const Service * service_p )

Get the URL of a web page describing a given Service.

Parameters

service_p The Service to get the page for.

Returns: The URL of the description page for the Service. This can be NULL.

◆ DeallocatePluginService()

bool DeallocatePluginService ( Plugin *const plugin_p )

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

Parameters

plugin_p The Plugin to free the Services from.

Returns: true if the Services were successfully released, false otherwise.

◆ GetServicesListAsJSON()

json_t * GetServicesListAsJSON	(	LinkedList *	services_list_p,
		DataResource *	resource_p,
		User *	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_p	A LinkedList of ServiceNodes detailing the Services to generate the fragment for
resource_p	The Resource of interest to run the Services with. This can be `NULL`.
user_p	Any User for access o potentially restricted Services. This can be `NULL` for only publicly accessible Services.
add_service_ids_flag	If 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_p	This 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

◆ ReleaseServiceParameters()

void ReleaseServiceParameters	(	Service *	service_p,
		ParameterSet *	params_p
	)

Free a ParameterSet that was got from a call to GetServiceParameters.

Parameters

service_p	The Service used for the previous call to `GetServiceParameters`
params_p	The ParameterSet to free.s

See also: GetServiceParameters

◆ AddServiceResponseHeader()

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.

Parameters

service_p	The Service which will have its response amended.
result_json_p	The JSON fragment to add.

Returns: true if the sService response was successfully updated, false otherwise.

◆ GetCurrentServiceStatus()

OperationStatus GetCurrentServiceStatus	(	Service *	service_p,
		const uuid_t	service_id
	)

Get the OperationStatus for an operation in a Service.

Parameters

service_p	The Service to query.
service_id	The uuid_t for the Operation whose OperationStatus is wanted.

Returns: The OperationStatus for the given Operation

◆ CreateAndAddPairedService()

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.

Parameters

service_p	The Service to add the PairedService to.
external_server_p	The ExternalServer that the PairedService runs on.
remote_service_name_s	The name of the PairedService on the ExternalServer.
op_p	The JSON fragment to create the PairedService's ParameterSet from.
provider_p	The JSON fragment representing the Provider.

Returns: true if the PairedService was created and added successfully, false otherwise.

See also: AddPairedService.; AllocatePairedService.; CreateParameterSetFromJSON

◆ AddPairedService()

bool AddPairedService	(	Service *	service_p,
		PairedService *	paired_service_p
	)

Add a PairedService to a Service.

Parameters

service_p	The Service to add the PairedService to.
paired_service_p	The PairedService to add.

Returns: true if the PairedService was added successfully, false otherwise.

◆ CreateAndAddLinkedService()

bool CreateAndAddLinkedService	(	Service *	service_p,
		const json_t *	service_config_p,
		GrassrootsServer *	grassroots_p
	)

Create and add a LinkedService to a Service.

Parameters

service_p	The Service to add the LinkedService to.
service_config_p	The json fragement defining the LinkedService to add.
grassroots_p	The GrassrootsServer that this Service will run on.

Returns: true if the LinkedService was added successfully, false otherwise.

◆ AddLinkedService()

bool AddLinkedService	(	Service *	service_p,
		LinkedService *	paired_service_p
	)

Add a LinkedService to a Service.

Parameters

service_p	The Service to add the LinkedService to.
paired_service_p	The LinkedService to add.

Returns: true if the LinkedService was added successfully, false otherwise.

◆ GetServiceRunRequest()

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 Service to run.

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

Parameters

service_name_s	The name of the Service to get the JSON fragment for.
params_p	The ParameterSet to use. If run_flag is false, then this can be `NULL`.
sv_p	If 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_flag	Whether 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.

◆ GetServiceRefreshRequest()

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 Service.

Get the JSON fragment for sending to a Grassroots Server asking for a service to be refreshed.

Parameters

service_name_s	The name of the Service to get the JSON fragment for.
params_p	The ParameterSet to use. If run_flag is false, then this can be `NULL`.
sv_p	If 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_flag	Whether 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.

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

Parameters

service_name_s	The name of the Service to get the JSON fragment for.
params_p	The ParameterSet to use. If run_flag is false, then this can be `NULL`.
sv_p	If 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_flag	Whether 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_p	The Service that has registered an interest in the given keyword.
keyword_s	The keyword.
params_p	The 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_flag	This 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_p	The Service to set the custom ServiceJob functions for.
job_p	The ServiceJob to customise.

See also: ServiceJob; se_customise_service_job_fn

◆ IsServiceRunning()

bool IsServiceRunning ( Service * service_p )

Check if a Service is currently running any ServiceJobs.

Parameters

service_p The Service to check.

Returns: true if the Service is running, false if it is not.

◆ SetServiceRunning()

void SetServiceRunning	(	Service *	service_p,
		bool	b
	)

Set if a Service is currently running any ServiceJobs or not.

Parameters

service_p	The Service to set.
b	`true` if the Service is running, `false` if it is not.

◆ SetMetadataForService()

void SetMetadataForService	(	Service *	service_p,
		SchemaTerm *	category_p,
		SchemaTerm *	subcategory_p
	)

Set the values of a Service's ServiceMetadata object.

Parameters

service_p	The Service to set.
category_p	The top-level application category to use.
subcategory_p	The application subcategory to use.

Returns: true if the ServiceMetadata was set successfully, false if it was not.

◆ GetGrassrootsServerFromService()

GrassrootsServer * GetGrassrootsServerFromService ( const Service *const service_p )

Get the GrassrootsServer that the Service is running on.

Parameters

service_p The Service to query

Returns: The GrassrootsServer

◆ LoadMatchingServicesByName()

void LoadMatchingServicesByName	(	GrassrootsServer *	grassroots_p,
		LinkedList *	services_p,
		const char *	service_name_s,
		const char *	service_alias_s,
		User *	user_p
	)

Load the Service that matches a given service name.

Parameters

services_p	The List of Services that the named Services will get appended to if it is found successfully.
services_path_s	The directory where the Service modules are stored.
service_name_s	The name of the Service to find.
user_p	Any user configuration details, this can be `NULL`.

◆ LoadMatchingServices()

void LoadMatchingServices	(	GrassrootsServer *	grassroots_p,
		LinkedList *	services_p,
		DataResource *	resource_p,
		Handler *	handler_p,
		User *	user_p
	)

Load the Services that are able to act upon a given Resource.

Parameters

services_p	The List of Services that the named Services will get appended to if it is found successfully.
services_path_s	The directory where the Service modules are stored.
resource_p	The Resource to check for matching Services for.
handler_p	The Handler that is appropriate for the given Resource.
user_p	Any user configuration details, this can be `NULL`.

◆ LoadKeywordServices()

void LoadKeywordServices	(	GrassrootsServer *	grassroots_p,
		LinkedList *	services_p,
		User *	user_p
	)

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

Parameters

services_p	The List of Services that any keyword-aware Services will get appended to.
user_p	Any user configuration details, this can be `NULL`.

◆ AddReferenceServices()

void AddReferenceServices	(	GrassrootsServer *	grassroots_p,
		LinkedList *	services_p,
		const char *	operation_name_s,
		User *	user_p
	)

Add any reference Services to the list of available Services.

Parameters

services_p	The LinkedList of ServiceNodes to add any referred Services to.
references_path_s	The directory containing the JSON definitions of reference services.
services_path_s	The directory containing the Service plugins.
operation_name_s	If 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_p	Any user configuration details, this can be `NULL`.

◆ GetServiceByName()

struct Service * GetServiceByName	(	GrassrootsServer *	grassroots_p,
		const char *const	service_name_s,
		const char *const	service_alias_s
	)

Get a Service by its name.

This will match a Service with its response from getting GetServiceName.

Parameters

service_name_s The name of the Service to find.

Returns: The matching Service or NULL if it could not be found.

Field Documentation

◆ se_plugin_p

struct Plugin* se_plugin_p

The platform-specific plugin that the code for the Service is stored in.

◆ se_is_specific_service_flag

bool se_is_specific_service_flag

Is the service self-contained.

If a Service has a specific task that it can perform then this is true. If it is a utility that is reused for different Services, such as a generic web search service, then this is false

◆ se_run_fn

struct ServiceJobSet*(* se_run_fn) (struct Service *service_p, ParameterSet *param_set_p, User *user_p, ProvidersStateTable *providers_p)

Run this Service.

Parameters

service_p	The Service to run.
param_set_p	The ParameterSet to run the Service with.
credentials_p	An optional set of credentials if the Service requires it.

Returns: A newly-allocated ServiceJobSet with the status of the ServiceJobs started by this call or NULL if there was an error.

See also: RunService

◆ se_match_fn

ParameterSet*(* se_match_fn) (struct Service *service_p, DataResource *resource_p, Handler *handler_p)

Is the Service able to work upon the given Resource.

Parameters

service_p	The Service to check.
resource_p	The Resource to check.
handler_p	A custom Handler for accessing the Resource. This can be NULL.

Returns: If the Service can run on the given Resource, it returns a ParameterSet that is partially filled in using the value of the Resource. If the Service cannot run on the given Resource, this will return NULL.

◆ se_has_permissions_fn

bool(* se_has_permissions_fn) (struct Service *service_p, ParameterSet *params_p, const User *const user_p)

Check whether the user have permissions to run the Service.

Parameters

service_p	This Service.
params_p	The ParameterSet that the user wishes to use. If this is `NULL` which will check whether the user can run the Service with any ParameterSet. If this is set, it will also check whether the user can run the Service with the specific parameters e.g. access to a given input file.
user_p	The User for the user.

Returns: true if the user has permissions, false otherwise.

◆ se_get_service_name_fn

const char*(* se_get_service_name_fn) (const struct Service *service_p)

Function to get the user-friendly name of the service.

◆ se_get_service_description_fn

const char*(* se_get_service_description_fn) (const struct Service *service_p)

Function to get the user-friendly description of the service.

◆ se_get_service_alias_fn

const char*(* se_get_service_alias_fn) (const struct Service *service_p)

Function to get the alias for a service.

◆ se_get_service_info_uri_fn

const char*(* se_get_service_info_uri_fn) (const struct Service *service_p)

Function to get a web address for more information about the service.

◆ se_get_params_fn

ParameterSet*(* se_get_params_fn) (struct Service *service_p, DataResource *resource_p, User *user_p)

Function to get the ParameterSet for this Service.

◆ se_customise_service_job_fn

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.

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

Parameters

service_p	This Service.
job_p	The ServiceJob to customise.

See also: ServiceJob; SetServiceJobCustomFunctions

◆ se_release_params_fn

void(* se_release_params_fn) (struct Service *service_p, ParameterSet *params_p)

Function to release the ParameterSet for this Service.

◆ se_close_fn

bool(* se_close_fn) (struct Service *service_p)

Function to close this Service.

Parameters

service_p This Service.

Returns: true if the Service was closed successfully, false otherwise.

◆ se_deserialise_job_json_fn

struct ServiceJob*(* se_deserialise_job_json_fn) (struct Service *service_p, const json_t *service_job_json_p)

Function to parse a JSON fragment from a previously serialised ServiceJob created by this Service.

Parameters

service_p	A Service of the same type that the serialised ServiceJob was run by.
service_job_json_p	The JSON fragment representing the serialised ServiceJob.

Returns: The newly-constructed ServiceJob or NULL upon error.

See also: CreateSerialisedServiceJobFromService

◆ se_serialise_job_json_fn

json_t*(* se_serialise_job_json_fn) (struct Service *service_p, struct ServiceJob *service_job_p, bool omit_results_flag)

Function to create a JSON fragment representing a serialised ServiceJob.

Parameters

service_p	The Service that created the ServiceJob.
service_job_p	The ServiceJob to serialise.

Returns: TThe JSON fragment representing the serialised ServiceJob or NULL upon error.

See also: CreateSerialisedJSONFromServiceJob

◆ se_process_linked_services_fn

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 for any LinkedServices for this Service.

Parameters

service_p	This Service.
job_p	The ServiceJob whose results will be processed.
linked_service_p	The LinkedService defining how to generate the Parameters for the Service to run based upon the given ServiceJob's results

Returns: true if the LinkedService was processed successfully, false otherwise.

◆ se_get_parameter_type_fn

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.

Parameters

service_p	This Service.
param_name_s	The name of the Parameter to get the ParameterType of.
pt_p	Pointer to the ParameterType where the value will be stored.

Returns: true if the ParameterType was retrieved successfully, false otherwise.

◆ se_synchronous

Synchronicity se_synchronous

The synchronicity for how this Service runs.

◆ se_id

uuid_t se_id

Unique Id for this service.

◆ se_jobs_p

struct ServiceJobSet* se_jobs_p

The ServiceJobSet for this Service.

◆ se_paired_services

LinkedList se_paired_services

Any remote Services that are paired with this Service.

◆ se_linked_services

LinkedList se_linked_services

Any LinkedServices that will use the output from running this Service as input for itself.

◆ se_data_p

ServiceData* se_data_p

Any custom data that the service needs to store.

◆ se_running_flag

bool se_running_flag

A flag to specify whether this Service is currently running.

Do not access this value directly, use the API methods IsServiceRunning() and SetServiceRunning() instead.

◆ se_metadata_p

ServiceMetadata* se_metadata_p

The ServiceMetadata for this Service.

◆ se_get_metadata_fn

ServiceMetadata*(* se_get_metadata_fn) (struct Service *service_p)

Callback function used to create a Service's ServiceMetadata.

Parameters

service_p This Service.

Returns: true if the Service's ServiceMetadata was created successfully, false otherwise.

◆ se_sync_data_p

SyncData* se_sync_data_p

If the Service's synchronicity is set to SY_ASYNCHRONOUS_ATTACHED, this is used as mutex to control access to this Service when needed.

◆ se_release_service_fn

void(* se_release_service_fn) (struct Service *service_p)

A custom callback function to use to close the service if needed.

Parameters

service_p This Service.

◆ se_get_indexing_data_fn

json_t*(* se_get_indexing_data_fn) (struct Service *service_p)

A custom callback function to get the data that can be be used to import into an indexing app like Lucene.

Parameters

service_p This Service.

◆ se_custom_parameter_decoder_fn

Parameter*(* se_custom_parameter_decoder_fn) (struct Service *service_p, json_t *param_json_p, const bool concise_flag)

If the service has to have a more complex method of creating parameters from json blobs than the standard method, use this custom callback function.

◆ se_grassroots_p

GrassrootsServer* se_grassroots_p

The server that this service is running on.

The documentation for this struct was generated from the following files:

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

◆ InitialiseService()

◆ RunService()

◆ DoesServiceHaveCustomServiceJobSerialisation()

◆ CreateSerialisedServiceJobFromService()

◆ CreateSerialisedJSONForServiceJobFromService()

◆ IsServiceMatch()

◆ GetServiceName()

◆ GetServiceDescription()

◆ GetServiceAlias()

◆ GetServiceIndexingData()

◆ GetServiceInformationURI()

◆ GetServiceParameters()

◆ GetParameterTypeForNamedParameter()

◆ GetServiceUUIDAsString()

◆ FreeService()

◆ ReleaseService()

◆ SetServiceReleaseFunction()

◆ CloseService()

◆ GetServiceAsJSON()

◆ GetServiceIcon()

◆ GetServiceInformationPage()

◆ DeallocatePluginService()

◆ GetServicesListAsJSON()

◆ ReleaseServiceParameters()

◆ AddServiceResponseHeader()

◆ GetCurrentServiceStatus()

◆ CreateAndAddPairedService()

◆ AddPairedService()

◆ CreateAndAddLinkedService()

◆ AddLinkedService()

◆ GetServiceRunRequest()

◆ GetServiceRefreshRequest()

◆ GetInterestedServiceJSON()

◆ SetServiceJobCustomFunctions()

◆ IsServiceRunning()

◆ SetServiceRunning()

◆ SetMetadataForService()

◆ GetGrassrootsServerFromService()

◆ LoadMatchingServicesByName()

◆ LoadMatchingServices()

◆ LoadKeywordServices()

◆ AddReferenceServices()

◆ GetServiceByName()

Field Documentation

◆ se_plugin_p

◆ se_is_specific_service_flag

◆ se_run_fn

◆ se_match_fn

◆ se_has_permissions_fn

◆ se_get_service_name_fn

◆ se_get_service_description_fn

◆ se_get_service_alias_fn

◆ se_get_service_info_uri_fn

◆ se_get_params_fn

◆ se_customise_service_job_fn

◆ se_release_params_fn

◆ se_close_fn

◆ se_deserialise_job_json_fn

◆ se_serialise_job_json_fn

◆ se_process_linked_services_fn

◆ se_get_parameter_type_fn

◆ se_synchronous

◆ se_id

◆ se_jobs_p

◆ se_paired_services

◆ se_linked_services

◆ se_data_p

◆ se_running_flag

◆ se_metadata_p

◆ se_get_metadata_fn

◆ se_sync_data_p

◆ se_release_service_fn

◆ se_get_indexing_data_fn

◆ se_custom_parameter_decoder_fn

◆ se_grassroots_p