service.h

Go to the documentation of this file.

/*
** Copyright 2014-2016 The Earlham Institute
** 
** Licensed under the Apache License, Version 2.0 (the "License");
** you may not use this file except in compliance with the License.
** You may obtain a copy of the License at
** 
**     http://www.apache.org/licenses/LICENSE-2.0
** 
** Unless required by applicable law or agreed to in writing, software
** distributed under the License is distributed on an "AS IS" BASIS,
** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
** See the License for the specific language governing permissions and
** limitations under the License.
*/
 
 
#ifndef GRASSROOTS_SERVICE_H
#define GRASSROOTS_SERVICE_H
 
#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_defs.h"
#include "service_metadata.h"
#include "sync_data.h"
 
#include "jansson.h"
 
#include "providers_state_table.h"
 
struct ExternalServer;
 
/*
 * The following preprocessor macros allow us to declare
 * and define the variables in the same place. By default,
 * they will expand to 
 * 
 *    extern const char *SERVICE_NAME_S;
 * 
 * however if ALLOCATE_JSON_TAGS is defined then it will 
 * become
 * 
 *    const char *SERVICE_NAME_S = "path";
 * 
 * ALLOCATE_PATH_TAGS must be defined only once prior to
 * including this header file. Currently this happens in
 * service.c.
 */
#ifndef DOXYGEN_SHOULD_SKIP_THIS
 
#ifdef ALLOCATE_PATH_TAGS
  #define PATH_PREFIX GRASSROOTS_SERVICE_API
  #define PATH_VAL(x) = x
#else
  #define PATH_PREFIX extern GRASSROOTS_SERVICE_API
  #define PATH_VAL(x)
#endif
 
#endif
 
//PATH_PREFIX const char *SERVICES_PATH_S PATH_VAL("services");
 
 
#define SERVICE_GROUP_ALIAS_SEPARATOR "-"
 
/* forward declarations */
struct Plugin;
struct Service;
struct ServiceJob;
struct ServiceJobSet;
 
 
typedef enum
{
  SY_SYNCHRONOUS,          
 
  SY_ASYNCHRONOUS_DETACHED,
 
  SY_ASYNCHRONOUS_ATTACHED 
} Synchronicity;
 
 
typedef struct ServiceData
{
  struct Service *sd_service_p;
 
  json_t *sd_config_p;
 
  bool sd_config_flag;
} ServiceData;
 
 
 
 
typedef struct Service
{
  struct Plugin *se_plugin_p;
 
  bool se_is_specific_service_flag;
 
  struct ServiceJobSet *(*se_run_fn) (struct Service *service_p, ParameterSet *param_set_p, User *user_p, ProvidersStateTable *providers_p);
 
  ParameterSet *(*se_match_fn) (struct Service *service_p, DataResource *resource_p, Handler *handler_p);
 
  bool (*se_has_permissions_fn) (struct Service *service_p, ParameterSet *params_p, const User * const user_p);
 
 
  const char *(*se_get_service_name_fn) (const struct Service *service_p);
 
  const char *(*se_get_service_description_fn) (const struct Service *service_p);
 
 
  const char *(*se_get_service_alias_fn) (const struct Service *service_p);
 
  const char *(*se_get_service_info_uri_fn) (const struct Service *service_p);
 
 
  ParameterSet *(*se_get_params_fn) (struct Service *service_p, DataResource *resource_p, User *user_p);
 
 
  void (*se_customise_service_job_fn) (struct Service *service_p, struct ServiceJob *job_p);
 
 
  void (*se_release_params_fn) (struct Service *service_p, ParameterSet *params_p);
 
  bool (*se_close_fn) (struct Service *service_p);
 
 
  struct ServiceJob *(*se_deserialise_job_json_fn) (struct Service *service_p, const json_t *service_job_json_p);
 
 
  json_t *(*se_serialise_job_json_fn) (struct Service *service_p, struct ServiceJob *service_job_p, bool omit_results_flag);
 
  bool (*se_process_linked_services_fn) (struct Service *service_p, struct ServiceJob *job_p, LinkedService *linked_service_p);
 
 
  bool (*se_get_parameter_type_fn) (const struct Service *service_p, const char *param_name_s, ParameterType *pt_p);
 
 
  Synchronicity se_synchronous;
 
  uuid_t se_id;
 
  struct ServiceJobSet *se_jobs_p;
 
  LinkedList se_paired_services;
 
  LinkedList se_linked_services;
 
  ServiceData *se_data_p;
 
  bool se_running_flag;
 
  ServiceMetadata *se_metadata_p;
 
 
  ServiceMetadata *(*se_get_metadata_fn) (struct Service *service_p);
 
  SyncData *se_sync_data_p;
 
  void (*se_release_service_fn) (struct Service *service_p);
 
 
  json_t *(*se_get_indexing_data_fn) (struct Service *service_p);
 
 
  Parameter *(*se_custom_parameter_decoder_fn) (struct Service *service_p, json_t *param_json_p, const bool concise_flag);
 
  GrassrootsServer *se_grassroots_p;
 
 
 
} Service;
 
 
typedef struct
{
  ListItem sn_node;
 
  Service *sn_service_p;
} ServiceNode;
 
 
typedef struct ServicesArray
{
  Service **sa_services_pp;
 
  uint32 sa_num_services; 
} ServicesArray;
 
 
 
 
 
#ifdef __cplusplus
extern "C"
{
#endif
 
GRASSROOTS_SERVICE_API ServicesArray *GetReferrableServicesFromPlugin (Plugin * const plugin_p, User *user_p, const json_t *service_config_p);
 
GRASSROOTS_SERVICE_API ServicesArray *GetServicesFromPlugin (Plugin * const plugin_p, User *user_p);
 
 
GRASSROOTS_SERVICE_API 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
);
 
 
GRASSROOTS_SERVICE_API struct ServiceJobSet *RunService (Service *service_p, ParameterSet *param_set_p, User *user_p, ProvidersStateTable *providers_p);
 
 
GRASSROOTS_SERVICE_API bool DoesServiceHaveCustomServiceJobSerialisation (struct Service *service_p);
 
 
GRASSROOTS_SERVICE_API struct ServiceJob *CreateSerialisedServiceJobFromService (struct Service *service_p, const json_t *service_job_json_p);
 
 
GRASSROOTS_SERVICE_API json_t *CreateSerialisedJSONForServiceJobFromService (struct Service *service_p, struct ServiceJob *service_job_p, bool omit_results_flag);
 
 
 
GRASSROOTS_SERVICE_API ParameterSet *IsServiceMatch (Service *service_p, DataResource *resource_p, Handler *handler_p);
 
 
GRASSROOTS_SERVICE_API const char *GetServiceName (const Service *service_p);
 
 
GRASSROOTS_SERVICE_API const char *GetServiceDescription (const Service *service_p);
 
 
GRASSROOTS_SERVICE_API const char *GetServiceAlias (const Service *service_p);
 
 
GRASSROOTS_SERVICE_API json_t *GetServiceIndexingData (Service *service_p);
 
 
GRASSROOTS_SERVICE_API const char *GetServiceInformationURI (const Service *service_p);
 
GRASSROOTS_SERVICE_API ParameterSet *GetServiceParameters (Service *service_p, DataResource *resource_p,  User *user_p);
 
 
 
GRASSROOTS_SERVICE_API bool GetParameterTypeForNamedParameter (const struct Service *service_p, const char *param_name_s, ParameterType *pt_p);
 
 
GRASSROOTS_SERVICE_API char *GetServiceUUIDAsString (Service *service_p);
 
 
GRASSROOTS_SERVICE_API void FreeService (Service *service_p);
 
 
GRASSROOTS_SERVICE_API void ReleaseService (Service *service_p);
 
 
 
GRASSROOTS_SERVICE_API void SetServiceReleaseFunction (Service *service_p, void (*release_fn) (Service *service_p));
 
 
GRASSROOTS_SERVICE_LOCAL void ReleaseServiceData (ServiceData *data_p);
 
GRASSROOTS_SERVICE_API ServiceNode *AllocateServiceNode (Service *service_p);
 
 
GRASSROOTS_SERVICE_API void FreeServiceNode (ListItem *node_p);
 
 
GRASSROOTS_SERVICE_API bool CloseService (Service *service_p);
 
 
 
 
GRASSROOTS_SERVICE_API json_t *GetServiceAsJSON (Service * const service_p, DataResource *resource_p, User *user_p, const bool add_id_flag);
 
 
GRASSROOTS_SERVICE_API const char *GetServiceIcon (const Service *service_p);
 
 
 
GRASSROOTS_SERVICE_API const char *GetServiceInformationPage (const Service *service_p);
 
 
GRASSROOTS_SERVICE_API bool DeallocatePluginService (Plugin * const plugin_p);
 
 
GRASSROOTS_SERVICE_API json_t *GetServicesListAsJSON (LinkedList *services_list_p, DataResource *resource_p, User *user_p, const bool add_service_ids_flag, ProvidersStateTable *providers_p);
 
 
GRASSROOTS_SERVICE_API void ReleaseServiceParameters (Service *service_p, ParameterSet *params_p);
 
 
GRASSROOTS_SERVICE_API void FreeServicesArray (ServicesArray *services_p);
 
 
GRASSROOTS_SERVICE_API ServicesArray *AllocateServicesArray (const uint32 num_services);
 
 
GRASSROOTS_SERVICE_LOCAL void AssignPluginForServicesArray (ServicesArray *services_p, Plugin *plugin_p);
 
 
GRASSROOTS_SERVICE_API bool AddServiceResponseHeader (Service *service_p, json_t *result_json_p);
 
 
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);
 
 
GRASSROOTS_SERVICE_API OperationStatus GetCurrentServiceStatus (Service *service_p, const uuid_t service_id);
 
 
GRASSROOTS_SERVICE_LOCAL OperationStatus DefaultGetServiceStatus (Service *service_p, const uuid_t service_id);
 
 
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);
 
 
GRASSROOTS_SERVICE_API bool AddPairedService (Service *service_p, PairedService *paired_service_p);
 
 
GRASSROOTS_SERVICE_API bool CreateAndAddLinkedService (Service *service_p, const json_t *service_config_p, GrassrootsServer *grassroots_p);
 
 
GRASSROOTS_SERVICE_API bool AddLinkedService (Service *service_p, LinkedService *paired_service_p);
 
 
 
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);
 
 
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);
 
 
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);
 
 
 
GRASSROOTS_SERVICE_API json_t *GetInterestedServiceJSON (Service *service_p, const char *keyword_s, const ParameterSet * const params_p, const bool full_definition_flag);
 
 
GRASSROOTS_SERVICE_API void SetServiceJobCustomFunctions (Service *service_p, struct ServiceJob *job_p);
 
 
GRASSROOTS_SERVICE_API bool IsServiceRunning (Service *service_p);
 
 
GRASSROOTS_SERVICE_API void SetServiceRunning (Service *service_p, bool b);
 
 
GRASSROOTS_SERVICE_API void SetMetadataForService (Service *service_p, SchemaTerm *category_p, SchemaTerm *subcategory_p);
 
 
 
 
 
 
 
GRASSROOTS_SERVICE_API bool SortServicesListByName (LinkedList *services_list_p);
 
 
GRASSROOTS_SERVICE_API json_t *GetBaseServiceDataAsJSON (Service * const service_p, User *user_p);
 
 
GRASSROOTS_SERVICE_API GrassrootsServer *GetGrassrootsServerFromService (const Service * const service_p);
 
 
GRASSROOTS_SERVICE_API json_t *GetServiceRefreshRequestFromJSON (const char * const service_name_s, json_t *param_set_json_p, const SchemaVersion *sv_p, const bool run_flag, const ParameterLevel level);
 
 
GRASSROOTS_SERVICE_API json_t *GetServiceRunRequestFromJSON (const char * const service_name_s, json_t *param_set_json_p, const SchemaVersion *sv_p, const bool run_flag, const ParameterLevel level);
 
 
GRASSROOTS_SERVICE_API bool DefaultGetParameterTypeForNamedParameter (const char *param_name_s, ParameterType *pt_p, const NamedParameterType *params_p);
 
 
GRASSROOTS_SERVICE_API bool AddServiceJobToService (Service *service_p, ServiceJob *job_p);
 
 
GRASSROOTS_SERVICE_API bool RemoveServiceJobFromService (Service *service_p, ServiceJob *job_p);
 
 
#ifdef __cplusplus
}
#endif
 
 
#endif    /* #ifndef GRASSROOTS_SERVICE_H */