Qorus Integration Engine®  4.0.3.p2_git
OMQ::UserApi::Service::ServiceApi Class Reference

primary service API class More...

Inheritance diagram for OMQ::UserApi::Service::ServiceApi:
OMQ::UserApi::UserApi

Static Public Member Methods

static checkAuthorization ()
 checks user authorization for all permissions passed to the method; throws an exception if the user is not authorized More...
 
static checkAuthorizationArgs (softlist< string > args)
 checks user authorization for all permissions passed to the method; throws an exception if the user is not authorized More...
 
static checkAuthorizationOr ()
 checks user authorization for at least one of list of permissions passed to the method; throws an exception if the user is not authorized More...
 
static checkAuthorizationOrArgs (softlist< string > args)
 checks user authorization for at least one of list of permissions passed to the method; throws an exception if the user is not authorized More...
 
static bool testAuthorization ()
 tests user authorization for all of permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testAuthorizationArgs (softlist< string > args)
 tests user authorization for all of permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testAuthorizationOr ()
 tests user authorization for at least one of the permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testAuthorizationOrArgs (softlist< string > args)
 tests user authorization for at least one of the permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static checkWorkflowAccess (list< auto > ids)
 checks if the current user has access to the given list of workflow IDs; throws an exception if the user is not authorized More...
 
static checkWorkflowAccess (softint id)
 checks if the current user has access to the given single workflow ID; throws an exception if the user is not authorized More...
 
static bool testWorkflowAccess (list< auto > ids)
 tests if the current user has access to the given list of workflow IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testWorkflowAccess (softint id)
 tests if the current user has access to the given single workflow ID and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getWorkflowAccessList ()
 returns a list of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getWorkflowAccessHash ()
 returns a hash of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static checkWorkflowInstanceAccess (softstring wfiid)
 checks if the current user has access to the given workflow_instanceid; throws an exception if the user is not authorized More...
 
static checkServiceAccess (list< auto > ids)
 checks if the current user has access to the given list of serviceids; throws an exception if the user is not authorized More...
 
static checkServiceAccess (softint id)
 checks if the current user has access to the given single serviceid; throws an exception if the user is not authorized More...
 
static checkQueueAccess (softint queueid, string key)
 checks if the current user has access to the given queue entry (as determined through the workflow access list); throws an exception if the user is not authorized More...
 
static bool testServiceAccess (list< auto > ids)
 tests if the current user has access to the given list of serviceids and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testServiceAccess (softint id)
 tests if the current user has access to the given single serviceid and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getServiceAccessList ()
 returns a list of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned More...
 
static *hash< auto > getServiceAccessHash ()
 returns a hash of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned More...
 
static checkJobAccess (list< auto > ids)
 checks if the current user has access to the given list of job IDs; throws an exception if the user is not authorized More...
 
static checkJobAccess (softint id)
 checks if the current user has access to the given single job ID; throws an exception if the user is not authorized More...
 
static bool testJobAccess (list< auto > ids)
 tests if the current user has access to the given list of job IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testJobAccess (softint id)
 tests if the current user has access to the given single job ID and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getJobAccessList ()
 returns a list of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getJobAccessHash ()
 returns a hash of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static checkJobInstanceAccess (softstring jiid)
 checks if the current user has access to the given job_instanceid; throws an exception if the user is not authorized More...
 
static checkMapperAccess (list< auto > ids)
 checks if the current user has access to the given list of mapper IDs; throws an exception if the user is not authorized More...
 
static checkMapperAccess (softint id)
 checks if the current user has access to the given single mapper ID; throws an exception if the user is not authorized More...
 
static bool testMapperAccess (list< auto > ids)
 tests if the current user has access to the given list of mapper IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testMapperAccess (softint id)
 tests if the current user has access to the given single mapper ID and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getMapperAccessList ()
 returns a list of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getMapperAccessHash ()
 returns a hash of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static checkVmapAccess (list< auto > ids)
 checks if the current user has access to the given list of value map IDs; throws an exception if the user is not authorized More...
 
static checkVmapAccess (softint id)
 checks if the current user has access to the given single value map ID; throws an exception if the user is not authorized More...
 
static bool testVmapAccess (list< auto > ids)
 tests if the current user has access to the given list of value map IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testVmapAccess (softint id)
 tests if the current user has access to the given single value map ID and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getVmapAccessList ()
 returns a list of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getVmapAccessHash ()
 returns a hash of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static registerSoapHandler (hash< auto > h)
 registers the current service as a SOAP service and exports its methods that map to SOAP operations in the given WSDL to be called from the Qorus HttpServer with the SOAP protocol More...
 
static *hash< auto > getHttpCallContext ()
 returns a hash with HTTP call context information More...
 
static hash< auto > getLastEvents (softint count)
 returns the last system events More...
 
static hash< auto > getLastEventsOr (softint count, auto filter, auto and_not)
 gets the last system events that meet any of the filter criteria and none of the "and_not" criteria, if present More...
 
static hash< auto > getLastEventsAnd (softint count, auto filter, auto or_not)
 gets the last system events that meet all of the filter criteria or none of the "or_not" criteria, if present More...
 
static hash< auto > waitForEvents (softint min_id=1, timeout timeout_ms=0)
 return available system events More...
 
static hash< auto > waitForEventsOr (softint min_id=1, auto filter, timeout timeout_ms=0, auto and_not)
 return system events that meet any of the given criteria and none of the optional "and not" criteria More...
 
static hash< auto > waitForEventsAnd (softint min_id=1, auto filter, timeout timeout_ms=0, auto or_not)
 return system events that meet all of the given criteria or none of the optional "or not" criteria More...
 
static int startThread (auto code)
 starts a service thread; passes the remaining arguments to the function to the new thread More...
 
static int startThreadArgs (auto code, auto args)
 starts a service thread; uses the second argument as the argument list to pass to the new thread More...
 
static hash< auto > getServiceInfo (*hash< auto > cx)
 returns information about the current service More...
 
static bindFtp (OMQ::AbstractFtpHandler handler)
 binds an FTP handler to the service; listeners are started according to the listener information in the OMQ::AbstractFtpHandler argument More...
 
static list< stringbindHttp (OMQ::AbstractServiceHttpHandler handler, hash< HttpBindOptionInfo > opts=< HttpBindOptionInfo >{})
 binds an HTTP handler to the service More...
 
static bindHandler (string name, OMQ::AbstractServiceHttpHandler handler)
 binds a new handler to a dedicated HTTP service listener by name More...
 
static bindHandler (string name, HttpServer::AbstractHttpRequestHandler handler, string url, *softlist< auto > content_type, *softlist< auto > special_headers, bool isregex=True)
 binds a new handler to a dedicated HTTP service listener by name More...
 
static *hash< auto > getCallContext ()
 returns contextual information about the current call More...
 
static string getCallContextString (*hash< auto > cx)
 returns a string describing the current call context More...
 
static auto callApiAsCurrentUser (string call, softlist< auto > args)
 calls a system API with the argument list to the API method as a top-level argument to this method as the current user More...
 
static *hash< auto > getServiceInfoAsCurrentUser (string type, string name, *hash< auto > cx)
 returns information about the given service from the service name (if it's currently loaded) and if the calling user can access the service More...
 
static *hash< auto > getServiceInfoAsCurrentUser (softint id, *hash< auto > cx)
 returns information about the given service from the serviceid (if it's currently loaded) and if the calling user can access the service More...
 
static list< hash< auto > > getRunningWorkflowListAsCurrentUser (string name, *string ver)
 returns a list of hashes giving information about the currently-running workflow execution instances if the current user can access them More...
 
static hash< auto > getActiveJobsAsCurrentUser ()
 Returns information on all active jobs visible to the given user. More...
 
static hash< auto > getResource (string name, hash< auto > ctx, int code=200, *hash< auto > hdr)
 Returns the given text or binary file resource as its native type in the "body" key of a hash along with an HTTP response code and optionally HTTP headers; if a template exists, then the template is rendered and returned, if the given resource does not exist, then an exception is raised. More...
 
static *hash< auto > tryGetResource (string name, hash< auto > ctx, int code=200, *hash< auto > hdr)
 Returns the given text or binary file resource as its native type in the "body" key of a hash along with an HTTP response code and optionally HTTP headers; if a template exists, then the template is rendered and returned, if the given resource does not exist, then NOTHING is returned. More...
 
static *hash< auto > getResourceHash ()
 returns a hash of the service's file resources (hash keys are service file resource names) or NOTHING if the service has none More...
 
static list< stringgetResourceList ()
 returns a list of the service's file resources or NOTHING if the service has none More...
 
static data getResourceData (string name, *hash< auto > ctx)
 Returns the given text or binary file resource as its native type; if a template exists, then the template is rendered and returned, if the given resource does not exist, then an exception is raised. More...
 
static WSDL::WebService getResourceWsdl (string name, *hash< auto > ctx)
 Returns the given file resource as a WSDL::WebService object; any XSD imports are resolved as service resources; if a template exists, then the template is rendered and returned, if the given resource does not exist, then an exception is raised. More...
 
static *data tryGetResourceData (string name, *hash< auto > ctx)
 Returns the given text or binary file resource as its native type; if a template exists, then the template is rendered and returned, if the given resource does not exist, then NOTHING is returned. More...
 
static bool hasResource (string name)
 returns True if the given service file resource exists, False if not More...
 
static hash< auto > renderTemplate (string name, hash< auto > ctx)
 explicitly renders a template file resource given the template argument hash More...
 
static *hash< auto > tryRenderTemplate (string name, hash< auto > ctx)
 render a template file resource and returns the rendered template if the template exists, otherwise returns NOTHING More...
 
static *hash< auto > getTemplateHash ()
 returns a hash of the service's template file resources (hash keys are service template resource names) or NOTHING if the service has none More...
 
static list< stringgetTemplateList ()
 returns a list of the service's template file resources or NOTHING if the service has none More...
 
static bool hasTemplate (string name)
 returns True if the given service template file resource exists, False if not More...
 
static uiExtensionRegister (OMQ::QorusExtensionHandler handler)
 registers the service as an extension of the system UI More...
 
static uiExtensionRegister (OMQ::QorusExtensionHandler handler, string url_name)
 registers the service as an extension of the system UI with deterministic URL path More...
 
static streamRegister (string name, string method, code factory, string desc)
 registers an HTTP chunked data handler as a service resource More...
 
static persistenceRegister (code factory)
 registers the service as providing persistent/dedicated HTTP connection support More...
 
static persistenceThreadTerminate ()
 terminates a persistent connection in the current thread More...
 
static list< hash< auto > > startListeners (softstring bind, *string cert_path, *string key_path, *string key_password, *string name, int family=AF_UNSPEC)
 starts one or more new global HTTP listeners; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given More...
 
static stopListener (softstring name)
 stops a single listener based on its name or bind address; does not return until all connections on the listener have closed More...
 
static stopListenerId (softint id)
 stops a single listener based on its listener ID; does not return until all connections on the listener have closed More...
 
static list< stringregisterSoapListener (hash< auto > sh, softstring bind, int family=AF_UNSPEC, *HttpServer::AbstractAuthenticator auth, hash< HttpBindOptionInfo > opts=< HttpBindOptionInfo >{})
 starts a dedicated SOAP listener with the given WSDL and registers the current service as a SOAP service and exports its methods that map to SOAP operations in the given WSDL to be called from the Qorus HttpServer with the SOAP protocol More...
 
static list< stringregisterSoapListeners (list< auto > sl, softstring bind, *hash< auto > lh, int family=AF_UNSPEC, *HttpServer::AbstractAuthenticator auth, hash< HttpBindOptionInfo > opts=< HttpBindOptionInfo >{})
 starts a dedicated SOAP listener with one or more WSDLs and registers the current service as a SOAP service and exports all methods that map to SOAP operations in the given WSDLs to be called from the Qorus HttpServer with the SOAP protocol More...
 
static *hash< auto > tryGetWfStaticData ()
 return the static data hash for the current workflow order if the service call was made from a workflow order, otherwise return NOTHING More...
 
static *hash< auto > tryGetWfDynamicData ()
 return the dynamic data hash for the current workflow order if the service call was made from a workflow order, otherwise return NOTHING More...
 
static *hash< auto > tryGetWfTempData ()
 return the temp data hash for the current workflow order if the service call was made from a workflow order, otherwise return NOTHING More...
 
static saveStateData (*hash< auto > data)
 serializes the given hash and stores against the service's state data in SERVICE_STATE_DATA More...
 
static *hash< auto > getStateData ()
 returns any service state state data stored with saveStateData() More...
 
static setOption (hash< auto > opts)
 Changes option values on a service. More...
 
static setOption (string option, auto value)
 Changes a single option value on a service. More...
 
static auto getOption ()
 Returns the value of the named service option(s) More...
 
static auto getOptionArgs (*softlist< string > args)
 Returns the value of the named service option or options. More...
 
static int sleep (softint arg)
 puts the current thread to sleep for a certain number of seconds More...
 
static int usleep (softint arg)
 puts the current thread to sleep for a certain number of microseconds More...
 
static int usleep (date arg)
 puts the current thread to sleep for a certain number of microseconds More...
 
static auto getConfigItemValue (string item, *hash< auto > local_context)
 returns the value of the given service configuration item More...
 
static hash< auto > getConfigItemHash (*hash< auto > local_context)
 returns a hash of all configuration items for the current service More...
 
- Static Public Member Methods inherited from OMQ::UserApi::UserApi
static *hash< auto > getUserServiceInfo (string name)
 returns information about the given user service (if it's currently loaded) More...
 
static SqlUtil::AbstractTable getSqlTable (string datasource, string table_name, bool register_dependency=True)
 get a cached table object (suitable for DML) if present, otherwise it creates one from scratch More...
 
static SqlUtil::AbstractTable getSqlTable (AbstractDatasource datasource, string table_name, bool register_dependency=True)
 get a cached table object (suitable for DML) if present, otherwise it creates one from scratch More...
 
static hash< auto > getSqlCacheInfo ()
 get information about cached object More...
 
static clearSqlTableCache (string datasource, *string table_name)
 clears all objects for given datasource from the cache (for example, if database objects have been updated in the dataserver) More...
 
static clearSqlTableCache (AbstractDatasource datasource, *string table_name)
 clears cached objects for given datasource (for example, if database objects have been updated in the dataserver) More...
 
static auto getValueMap (string mapname, string key)
 Gets a lookup value from the value map by a key; the value map must be registered to the current interface. More...
 
static list< auto > getValueMaps ()
 Gets all value maps valid for the current interface. More...
 
static bool postSlaEventSuccess (string sla, number value)
 posts a successful SLA event for SLA monitoring and performance tracking More...
 
static bool postSlaEventError (string sla, number value, string err, string desc)
 posts an unsuccessful SLA event for SLA monitoring and performance tracking More...
 
static flushSlaEvents ()
 flushes all pending SLA events to disk and returns after the data has been committed More...
 
static *hash< auto > getSystemServiceInfo (string name)
 returns information about the given system service (if it's currently loaded) More...
 
static *hash getServiceInfo (string type, string name)
 returns information about the given service (if it's currently loaded) More...
 
static list getRunningWorkflowList (*string name, *string ver)
 returns a list of hashes giving information about the currently-running workflow execution instances More...
 
static hash getRunningWorkflowInfo (softint id)
 returns a hash of the workflow execution instance info if the ID is valid or an empty hash if not More...
 
static softint createOrder (string name, *string version, hash params, string status=StatReady)
 creates a workflow order data instance in the database More...
 
static softint createRemoteOrder (string remote, string name, *string version, hash params, string status=StatReady, bool register_dependency=True)
 creates a workflow order data instance in a remote Qorus instance More...
 
static hash< auto > execSynchronousWorkflow (string name, *string version, hash sdata, *hash opts, *hash ddata, softint priority=DefaultOrderPriority, *hash orderkeys, *softstring external_order_instanceid, *softint parent_workflow_instanceid)
 executes a workflow order synchronously and returns the final status and order ID in a hash More...
 
static int postUserEvent (string severity, auto info)
 posts an application event of class QE_CLASS_USER More...
 
static hash runtimeProperties ()
 returns Qorus runtime properties as a hash More...
 
static auto callNetworkApiArgsWithAuthentication (string user, string pass, string call, softlist args)
 calls a system RPC API with authentication information (username and password) More...
 
static auto callNetworkApiArgs (string call, softlist args)
 calls a system RPC API with the argument list to the API method as a top-level argument to this method; the API is called with system permissions (no restrictions) More...
 
static auto callNetworkApi (string call)
 calls a system RPC API and returns the result; the API is called with system permissions (no restrictions) More...
 
static auto callRestApi (string method, string path, *hash< auto > body_args)
 calls a system REST API method and returns the result; the API is called with system permissions (no restrictions) More...
 
static auto callRestApiWithAuthentication (string user, string pass, string method, string path, *hash< auto > body_args)
 calls a system REST API method with authentication information (username and password) and returns the result More...
 
static hash getSystemInfo ()
 returns a hash of system info More...
 
static int getSessionId ()
 returns the current Qorus application session ID More...
 
static logFatal (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logError (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logWarn (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logInfo (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logDebug (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logTrace (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsFatal (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsError (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsWarn (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsInfo (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsDebug (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsTrace (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static *int auditUserEvent (string user_event, *string info1, *string info2)
 creates a user audit event (with audit event code AE_USER_EVENT) against the workflow, service, or job instance More...
 
static bool auditCheckEventString (string opt)
 checks if the given audit event (given as a string) is enabled More...
 
static bool auditCheckEvent (softint opt)
 checks if the given audit event (given as an integer code) is enabled More...
 
static int auditGetMask ()
 returns the audit event mask More...
 
static int sleep (softint arg)
 puts the current thread to sleep for a certain number of seconds More...
 
static int usleep (softint arg)
 puts the current thread to sleep for a certain number of microseconds More...
 
static auto getQorusOptions ()
 returns the value of the given system option or options More...
 
static hash< auto > getQorusOptionInfo ()
 returns a hash giving information about system options More...
 
static hash< auto > getQorusOptionInfoArgs (*list< auto > args)
 returns a hash giving information about system options More...
 
static auto getQorusOptionsArgs (softlist args)
 returns the value of the given system option or options More...
 
static hash< auto > getActiveJobs ()
 Returns information on all active jobs visible to the calling user. More...
 
static object getUserConnection (string name, bool connect=True, bool register_dependency=True, *hash< auto > rtopts)
 Returns an object corresponding to a defined user connection. More...
 
static Qore::SQL::Datasource getDatasourceDedicated (string name, bool register_dependency=True)
 returns a new, dedicated Datasource object, suitable for transaction management for long-running transactions More...
 
static AbstractDatasource getDatasourcePool (string name, bool register_dependency=True)
 returns a DatasourcePool object for the given datasource name More...
 
static hash< auto > getDatasourceInfo (string name)
 returns a hash of information for the given datasource, if known, otherwise throws an exception More...
 
static QorusSystemAPIHelper getRemoteRpcConnection (string name, bool connect=True, bool register_dependency=True)
 Returns a new QorusSystemAPIHelper object corresponding to a defined Qorus remote connection. More...
 
static QorusSystemRestHelper getRemoteRestConnection (string name, bool connect=True, bool register_dependency=True)
 Returns a new QorusSystemRestHelper object corresponding to a defined Qorus remote connection. More...
 
static raiseTransientAlert (string alert, string reason, *hash< auto > info)
 raises a transient system alert from a workflow, service, or job More...
 
static string qorusGetLocalUrl (*string username, *string password)
 returns a string giving the local system URL More...
 
static setOption (hash< auto > hash)
 Changes option values on a workflow, service, or job. More...
 
static auto getOption ()
 Returns the value of the named workflow, service, or job option or options. More...
 
static auto getOptionArgs (*softlist< string > args)
 Returns the value of the named workflow, service, or job option or options. More...
 
static hash< auto > blockOrder (softint wfiid)
 block the given workflow order data instance More...
 
static hash< auto > unblockOrder (softint wfiid, *hash< auto > tempdata, *hash< auto > orderkeys)
 unblocks the given workflow order data instance More...
 
static hash< auto > cancelOrder (softint wfiid)
 cancel the given workflow order data instance More...
 
static hash< auto > uncancelOrder (softint wfiid, *hash< auto > tempdata)
 uncancels the given workflow order data instance More...
 
static *hash< auto > getUserContextInfo ()
 returns a hash for the current user context More...
 
static auto getConfigItemValue (string cfg_item, *hash< auto > local_context)
 returns config item value in the current user context More...
 
static hash< auto > getConfigItemHash (*hash< auto > local_context)
 returns a hash of all configuration items for the current interface More...
 
static auto getGlobalConfigItemValue (string item, *hash< auto > local_context)
 returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item More...
 
static auto getGlobalConfigItemValueWithDefault (string item, auto default_value, *hash< auto > local_context)
 returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item More...
 
static Mapper::Mapper getMapper (string name, *hash< auto > rtopts)
 returns the given mapper if registered for the current interface More...
 
static Qore::AbstractIterator getMapperIterator (string name, Qore::AbstractIterator input, *hash< auto > rtopts)
 returns an iterator for the named mapper using the iterator argument for input More...
 
static bool postSyncEvent (string eventtype, string eventkey)
 posts a workflow synchronization event given the event type name and the unique event key More...
 
static hash< auto > propGet ()
 returns a hash of all system properties in all domains More...
 
static *hash< auto > propGet (string domain)
 returns a hash of all key-value pairs in the given domain or NOTHING if the system property domain does not exist More...
 
static auto propGet (string domain, string key)
 returns the value of the given system property key in the given domain or NOTHING if the system property does not exist More...
 
static string propUpdate (string domain, softstring key, auto value)
 changes (inserts, updates, or deletes) the value of a single system property More...
 
static hash< auto > propUpdate (hash< auto > h)
 changes (inserts, updates, or deletes) the value of one or more system properties according to a hash argument More...
 
static softint getNextSequenceValue (AbstractDatasource ds, string name)
 returns the next sequence value for the given datasource and sequence More...
 
static softint getNextSequenceValue (string ds, string name)
 returns the next sequence value for the given datasource and sequence More...
 
static string serializeQorusData (auto d)
 returns a string giving the default serialization of the given data structure for storage in Qorus More...
 
static string serializeQorusDataWithNothing (auto d)
 returns a string giving the default serialization of the given data structure for storage in Qorus More...
 
static auto deserializeQorusData (string data)
 parses serialized data in either XML-RPC or YAML format and returns the corresponding qore data More...
 
static auto deserializeQorusData (null data)
 deserializing a NULL value from the DB returns no value
 
static *string restartTransaction (string driver, hash< auto > ex)
 returns a string error message if any exception in the chain passed was caused by a recoverable DB error, otherwise returns NOTHING More...
 
static bool isInternalSystemDebuggingEnabled ()
 returns True if internal system debugging is enabled
 
static auto getHashDotValue (*hash< auto > var_data, string var_name)
 returns the value of the given key from the given hash, respects dot notation in the key name More...
 
static auto expandOneVariable (string str, string var_context, string var_name, *hash< auto > local_context, *bool brackets)
 expands one variable in a templated string More...
 
static bool isSingleTemplatedString (auto value)
 checks if the given value is a templated string with only one expandable variable More...
 
static auto expandTemplatedValue (auto value, *hash< auto > local_context)
 expands all variables in a templated string More...
 
static hash< BbVariable > bbParseExactlyOneVariable (string str)
 parses one template variable and returns a hash with its parts More...
 
static auto getInputData (string field_name, *hash< auto > local_context, *hash< auto > input_data_cfg)
 returns specified input data field's value More...
 
static hash< auto > getInputData (*hash< auto > input_data_cfg, *hash< auto > local_context)
 returns all input data More...
 
static *hash< auto > updateHashDotValue (*hash< auto > var_data, string var_name, auto value)
 updates the given hash with a key in dot notation with the given value More...
 
static updateOutputData (string field_name, auto output_data, *hash< auto > output_data_cfg)
 updates specified output data field's value More...
 
static updateOutputData (hash< auto > all_output_data, hash< auto > output_data_cfg=UserApi::getConfigItemValue(BB_OUTPUT_DATA_CFG_KEY))
 updates all output data More...
 
static string getTextFileFromLocation (string location)
 returns string data for the given file location More...
 
static binary getBinaryFileFromLocation (string location)
 returns binary data for the given file location More...
 

Public Attributes

const ServiceCallContextKeys = ("socket", "socket-info", "peer-info", "url", "id", "ssl", "user", "client-cert")
 keys returned from the cx hash in getCallContext() if present More...
 

Detailed Description

primary service API class

Member Function Documentation

◆ bindFtp()

static OMQ::UserApi::Service::ServiceApi::bindFtp ( OMQ::AbstractFtpHandler  handler)
static

binds an FTP handler to the service; listeners are started according to the listener information in the OMQ::AbstractFtpHandler argument

Parameters
handlerdefines parameters and callback routines for the system FTP server
Exceptions
SERVICE-FTP-ERRORno listeners set in OMQ::AbstractFtpHandler, error starting listener
See also
svc_bind_ftp()

◆ bindHandler() [1/2]

static OMQ::UserApi::Service::ServiceApi::bindHandler ( string  name,
OMQ::AbstractServiceHttpHandler  handler 
)
static

binds a new handler to a dedicated HTTP service listener by name

Parameters
namethe name of the service resource for the dedicated service listener
handlerdefines parameters and callback routines for the system HTTP server
Exceptions
BIND-HANDLER-ERRORcannot bind a handler with listeners to an existing HTTP service handler
See also
svc_bind_handler()

◆ bindHandler() [2/2]

static OMQ::UserApi::Service::ServiceApi::bindHandler ( string  name,
HttpServer::AbstractHttpRequestHandler  handler,
string  url,
*softlist< auto >  content_type,
*softlist< auto >  special_headers,
bool  isregex = True 
)
static

binds a new handler to a dedicated HTTP service listener by name

Parameters
namethe name of the service resource for the dedicated service listener
handlerdefines parameters and callback routines for the system HTTP server
urla regex for the URL to service
content_typean optional list of Content-Types to match
special_headersan optional list of special headers to match
isregexdefines if url is a regular expression or not
See also
svc_bind_handler()

◆ bindHttp()

static list<string> OMQ::UserApi::Service::ServiceApi::bindHttp ( OMQ::AbstractServiceHttpHandler  handler,
hash< HttpBindOptionInfo opts = HttpBindOptionInfo >{} 
)
static

binds an HTTP handler to the service

If any listener information is present, then existing listeners with same bind value are reused or new listeners are started according to the listener information in the AbstractHttpHandler argument.

Parameters
handlerdefines parameters and callback routines for the system HTTP server
optsadditional options for the HTTP handler binding process
Returns
a list of service resource names bound to the service; multiple resource names are returned only if there are multiple listeners defined in the handler argument
Exceptions
SERVICE-HTTP-ERRORerror starting listener, error binding URL
LISTENER-SHARING-NOT-ALLOWED-ERRORthere is already a listener with same bind value and either the service that started it does not allow sharing of it, or the allow_listener_sharing option is set to False
See also
svc_bind_http()
OMQ::HttpBindOptionInfo

◆ callApiAsCurrentUser()

static auto OMQ::UserApi::Service::ServiceApi::callApiAsCurrentUser ( string  call,
softlist< auto >  args 
)
static

calls a system API with the argument list to the API method as a top-level argument to this method as the current user

Parameters
callthe full api method name (ex: "omq.system.exec-synchronous-exiting"); see Network System API for a full list
argsany arguments to the method; if multiple argument should be passed to the method, use a list of arguments here
Returns
the return value of the method
Exceptions
UNKNOWN-API-CALLinvalid API method
INVALID-INTERNAL-API-CALLAPI may not be called internally (ex: omq.system.shutdown-wait())
See also

◆ checkAuthorization()

static OMQ::UserApi::Service::ServiceApi::checkAuthorization ( )
static

checks user authorization for all permissions passed to the method; throws an exception if the user is not authorized

If current user does not have all of the given permissions, an exception is thrown.

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors; an appropriate exception is thrown.

Exceptions
AUTHORIZATION-ERRORno authentication information supplied or user does not have all required permissions
See also

◆ checkAuthorizationArgs()

static OMQ::UserApi::Service::ServiceApi::checkAuthorizationArgs ( softlist< string args)
static

checks user authorization for all permissions passed to the method; throws an exception if the user is not authorized

If current user does not have all of the given permissions, an exception is thrown.

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors; an appropriate exception is thrown.

Exceptions
AUTHORIZATION-ERRORno authentication information supplied or user does not have all required permissions
See also

◆ checkAuthorizationOr()

static OMQ::UserApi::Service::ServiceApi::checkAuthorizationOr ( )
static

checks user authorization for at least one of list of permissions passed to the method; throws an exception if the user is not authorized

If current user does not have at least one of the given permissions, an exception is thrown.

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors; an appropriate exception is thrown.

Exceptions
AUTHORIZATION-ERRORno authentication information supplied or user does not have any of the permissions given
See also

◆ checkAuthorizationOrArgs()

static OMQ::UserApi::Service::ServiceApi::checkAuthorizationOrArgs ( softlist< string args)
static

checks user authorization for at least one of list of permissions passed to the method; throws an exception if the user is not authorized

If current user does not have at least one of the given permissions, an exception is thrown.

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors; an appropriate exception is thrown.

Exceptions
AUTHORIZATION-ERRORno authentication information supplied or user does not have any of the permissions given
See also

◆ checkJobAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkJobAccess ( list< auto >  ids)
static

checks if the current user has access to the given list of job IDs; throws an exception if the user is not authorized

Parameters
idsa list of jobids to check
Exceptions
JOB-ACCESS-ERRORthe user does not have access to one or more of the given jobs
See also
svc_check_job_access()

◆ checkJobAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkJobAccess ( softint  id)
static

checks if the current user has access to the given single job ID; throws an exception if the user is not authorized

Parameters
idthe jobid to check
Exceptions
JOB-ACCESS-ERRORthe user does not have access to the given job
See also
svc_check_job_access()

◆ checkJobInstanceAccess()

static OMQ::UserApi::Service::ServiceApi::checkJobInstanceAccess ( softstring  jiid)
static

checks if the current user has access to the given job_instanceid; throws an exception if the user is not authorized

Parameters
jiidthe job_instanceid to check
Exceptions
JOB-ACCESS-ERRORthe user does not have access to the given job
See also
svc_check_job_instance_access()

◆ checkMapperAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkMapperAccess ( list< auto >  ids)
static

checks if the current user has access to the given list of mapper IDs; throws an exception if the user is not authorized

Parameters
idsa list of mapperids to check
Exceptions
MAPPER-ACCESS-ERRORthe user does not have access to one or more of the given mappers
See also
svc_check_mapper_access()

◆ checkMapperAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkMapperAccess ( softint  id)
static

checks if the current user has access to the given single mapper ID; throws an exception if the user is not authorized

Parameters
idthe mapperid to check
Exceptions
MAPPER-ACCESS-ERRORthe user does not have access to the given mapper
See also
svc_check_mapper_access()

◆ checkQueueAccess()

static OMQ::UserApi::Service::ServiceApi::checkQueueAccess ( softint  queueid,
string  key 
)
static

checks if the current user has access to the given queue entry (as determined through the workflow access list); throws an exception if the user is not authorized

Parameters
queueidthe queue ID to check
keythe key value in queue given by the first argument to check
Exceptions
WORKFLOW-ACCESS-ERRORno authentication information supplied or user does not have access to the given workflow
See also
svc_check_queue_access()

◆ checkServiceAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkServiceAccess ( list< auto >  ids)
static

checks if the current user has access to the given list of serviceids; throws an exception if the user is not authorized

Parameters
idsa list of serviceids to check
Exceptions
SERVICE-ACCESS-ERRORno authentication information supplied or user does not have access to one or more of the given services
See also
svc_check_service_access()

◆ checkServiceAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkServiceAccess ( softint  id)
static

checks if the current user has access to the given single serviceid; throws an exception if the user is not authorized

Parameters
idthe serviceid to check
Exceptions
SERVICE-ACCESS-ERRORno authentication information supplied or user does not have access to the given service
See also
svc_check_service_access()

◆ checkVmapAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkVmapAccess ( list< auto >  ids)
static

checks if the current user has access to the given list of value map IDs; throws an exception if the user is not authorized

Parameters
idsa list of value map ids to check
Exceptions
VMAP-ACCESS-ERRORthe user does not have access to one or more of the given value maps
See also
svc_check_vmap_access()

◆ checkVmapAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkVmapAccess ( softint  id)
static

checks if the current user has access to the given single value map ID; throws an exception if the user is not authorized

Parameters
idthe value map id to check
Exceptions
VMAP-ACCESS-ERRORthe user does not have access to the given value map
See also
svc_check_vmap_access()

◆ checkWorkflowAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkWorkflowAccess ( list< auto >  ids)
static

checks if the current user has access to the given list of workflow IDs; throws an exception if the user is not authorized

Parameters
idsa list of workflowids to check
Exceptions
WORKFLOW-ACCESS-ERRORthe user does not have access to one or more of the given workflows
See also
svc_check_workflow_access()

◆ checkWorkflowAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkWorkflowAccess ( softint  id)
static

checks if the current user has access to the given single workflow ID; throws an exception if the user is not authorized

Parameters
idthe workflowid to check
Exceptions
WORKFLOW-ACCESS-ERRORthe user does not have access to the given workflow
See also
svc_check_workflow_access()

◆ checkWorkflowInstanceAccess()

static OMQ::UserApi::Service::ServiceApi::checkWorkflowInstanceAccess ( softstring  wfiid)
static

checks if the current user has access to the given workflow_instanceid; throws an exception if the user is not authorized

Parameters
wfiidthe workflow_instanceid to check
Exceptions
WORKFLOW-ACCESS-ERRORno authentication information supplied or user does not have access to the given workflow
See also
svc_check_workflow_instance_access()

◆ getActiveJobsAsCurrentUser()

static hash<auto> OMQ::UserApi::Service::ServiceApi::getActiveJobsAsCurrentUser ( )
static

Returns information on all active jobs visible to the given user.

If any active jobs are not accessible to the calling user, then they are filtered from the hash returned.

Returns
a hash is keyed by job name; the hash values are job information hashes with the following keys:
  • jobid: the metadata jobid of the job type
  • name: the job name
  • version: the job version
  • description: the job description
  • trigger: a string describing the timer/trigger for the job
  • [job_instanceid]: the id of the job instance (will only have a value if the job is currently executing)
  • [last_executed]: the last executed date/time of the job (NOTHING if not yet executed)
  • [last_executed_job_instanceid]: the last executed instance id of the job
  • [expiry_date]: the expiry date of the job, if any; if this date is present, then the job will not run automatically after this date
  • single_instance: True if the job can only be run in a single Qorus instance, False if no such restriction is enabled
  • [next]: the next trigger date/time; this key is only included if the job is active
  • active: this value is always True because this API only returns information about active jobs
See also
svc_get_active_jobs_as_current_user()

◆ getCallContext()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getCallContext ( )
static

returns contextual information about the current call

Returns
NOTHING if no context information is available, otherwise a hash with the following possible keys; keys actually present depend on the context of the caller to the service method:
  • wf: this key is present if the call to the service method originated from workflow code while processing an order; the value is a hash with the following keys:
    • name: the name of the workflow
    • version: the version of the workflow
    • workflowid: the workflowid of the workflow
    • workflow_instanceid: the workflow_instanceid of the order being executed
    • stepid: the stepid of the step being executed
    • ind: the array step index of the step being executed
    • priority: the priority of the workflow order
    • started: the date/time the order started processing
    • options: the current workflow execution instance option hash
  • job: this key is present if the call to the service method originated from job code; the value is a hash with the following keys:
    • jobid: the metadata jobid of the job type
    • job_instanceid: the id of the job instance
    • name: the job name
    • version: the job version
    • description: the job description
    • trigger: a string describing the timer/trigger for the job
    • last_executed: the last executed date/time of the job (NOTHING if never executed before the current iteration)
    • last_executed_job_instanceid: the last executed instance id of the job
    • single_instance: True if the job can only be run in a single Qorus instance, False if no such restriction is enabled
    • next: the next trigger date/time
  • cx: this key is present if the call to the service method originated externally through the network API; the value is a hash with the following keys:
    • client-cert: an SSLCertificate object for the client certificate if client certificate capture has been enabled in the listener (see the get_remote_certs key in HttpListenerOptionInfo)
    • id: the unique HTTP connection ID
    • peer-info: a hash of socket information for the remote socket (as returned by Socket::getPeerInfo())
    • socket: the bind address used to bind the listener ("socket-info" provides more detailed information)
    • socket-info: a hash of socket information for the listening socket (as returned by Socket::getSocketInfo())
    • ssl: True if the request was encrypted with HTTPS, False if no
    • url: a hash of broken-down URL information (as returned from parseURL())
    • user: the current RBAC username (if any)
See also

◆ getCallContextString()

static string OMQ::UserApi::Service::ServiceApi::getCallContextString ( *hash< auto >  cx)
static

returns a string describing the current call context

Example:
string str = ServiceApi::getCallContextString();
Parameters
cxoptional thread context hash from HTTP handler if available
Returns
a string describing the current call context
See also
svc_get_call_context_string()

◆ getConfigItemHash()

static hash<auto> OMQ::UserApi::Service::ServiceApi::getConfigItemHash ( *hash< auto >  local_context)
static

returns a hash of all configuration items for the current service

Example:
hash<auto> config = ServiceApi::getConfigItemHash();
Parameters
local_contextthe caller can supply its "local" context for template variables (plus user context info is added - see UserApi::getUserContextInfo() method)
Returns
a hash of all configuration items for the current service; keys are config item names; values are config item values. If there are no config items for the current service, then an empty hash is returned.
Note
if there are local configuration item values and values on global level, the local values will take precedence over the global values
Exceptions
CONFIG-ITEM-ERRORthrown if the configuration item is not valid
Note
values are always substituted with UserApi::expandTemplatedValue(); make sure and escape any "$" characters with a backslash ("\") to avoid template substitution
See also
Class-Based Service Configuration Items

◆ getConfigItemValue()

static auto OMQ::UserApi::Service::ServiceApi::getConfigItemValue ( string  item,
*hash< auto >  local_context 
)
static

returns the value of the given service configuration item

Example:
auto val = ServiceApi::getConfigItemValue(item);
Parameters
itemthe name of the service configuration item; service configuration item values take precedence over values on global level if both are set otherwise if both are not set the default value is returned
local_contextthe caller can supply its "local" context for template variables (plus user context info is added - see UserApi::getUserContextInfo() method)
Returns
the value of the given configuration item
Exceptions
CONFIG-ITEM-ERRORthrown if the configuration item is not valid
Note
the value is always substituted with UserApi::expandTemplatedValue(); make sure and escape any "$" characters with a backslash ("\") to avoid template substitution
See also
Class-Based Service Configuration Items

◆ getHttpCallContext()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getHttpCallContext ( )
static

returns a hash with HTTP call context information

Note
This API method is relevant for any external HTTP call, including SOAP and REST calls
See also
svc_get_http_call_context()

◆ getJobAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getJobAccessHash ( )
static

returns a hash of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all jobs

Returns
a hash of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
See also
svc_get_job_access_list()

◆ getJobAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getJobAccessList ( )
static

returns a list of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all jobs

Returns
a list of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
See also
svc_get_job_access_list()

◆ getLastEvents()

static hash<auto> OMQ::UserApi::Service::ServiceApi::getLastEvents ( softint  count)
static

returns the last system events

Parameters
countthe maximum number of system events to return
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the method returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned
See also
svc_get_last_events()

◆ getLastEventsAnd()

static hash<auto> OMQ::UserApi::Service::ServiceApi::getLastEventsAnd ( softint  count,
auto  filter,
auto  or_not 
)
static

gets the last system events that meet all of the filter criteria or none of the "or_not" criteria, if present

Parameters
countthe maximum number of events to return; if this argument is 0, then the size of the returned list is only limited by the number of events in the system that match the filter(s) passed.
filterthis argument is the criteria list for "logical and" comparisons to be applied to the events. If an event matches all of the criteria hashes in the first argument, then it is included in the resulting list. To match a criteria hash in the second argument with this API call, any of the criteria keys in a single hash can match, therefore, to get pure "logical and" behavior, the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
or_notthis argument is an optional criteria list that can augment the list returned with negative matches. If this argument is present and any element in the system’s event list does not match any of the criteria hashes in the third argument, then it is also included in the returned event list. Note that the third argument, if present, is processed with inverted logic compared to the second argument; for a single criteria hash to match, all of the criteria given as hash keys in the criteria hash must match, therefore, to get pure inverted "logical or" logic, the caller must specify only one hash key per hash in the list making up the third argument; see Event Filter Criteria for a description of each criteria hash
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the method returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
GET-LAST-EVENTS-AND-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned
See also
svc_get_last_events_and()

◆ getLastEventsOr()

static hash<auto> OMQ::UserApi::Service::ServiceApi::getLastEventsOr ( softint  count,
auto  filter,
auto  and_not 
)
static

gets the last system events that meet any of the filter criteria and none of the "and_not" criteria, if present

Returns a hash giving the list of the most recent system events matching a filter and the last event ID generated by the system. Events in the event list returned must match the criteria passed as the second argument; if any of the criteria match an event, then it is included in the return list, unless a third criteria list argument is also passed, which allows for removing elements from the list returned.

Parameters
countthe maximum number of events to return; if this argument is 0, then the size of the returned list is only limited by the number of events in the system that match the filter(s) passed.
filterthis argument gives the criteria list for "logical or" comparisons to be applied to the events. If an event matches any of the criteria hashes in the first argument, then it is included in the resulting list, subject to processing by the optional third argument. To match a criteria hash in the second argument with this API call, all of the criteria keys in each hash must match, therefore, to get pure "logical or" behavior the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
and_notthis argument is an optional criteria list allowing the resulting event list to be filtered; if any event selected by the second argument matches all criteria hashes in the criteria hashes passed as the third argument, then it is filtered out of the resulting list. Note that the third argument, if present, is processed with inverted logic compared to the second argument; for a criteria hash to match, any of the criteria given as hash keys in a criteria hash can match, however, all criteria hashes must match for the filter to operate. Therefore, to get pure "logical and" filtering the caller must specify only one hash key per hash in the list making up the third argument; see Event Filter Criteria for a description of each criteria hash
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the method returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
GET-LAST-EVENTS-OR-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned
See also
svc_get_last_events_or()

◆ getMapperAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getMapperAccessHash ( )
static

returns a hash of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all mappers

Returns
a hash of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Note
a return value of an empty hash means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps
See also
svc_get_mapper_access_hash()

◆ getMapperAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getMapperAccessList ( )
static

returns a list of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all mappers

Returns
a list of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Note
a return value of an empty list means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps
See also
svc_get_mapper_access_list()

◆ getOption()

static auto OMQ::UserApi::Service::ServiceApi::getOption ( )
static

Returns the value of the named service option(s)

If the option is not set on the service level, and it is a valid system option, then the value of the system option will be returned.

Returns
the value requested directly if only one argument is passed, otherwise a hash of option keys and values; note that if no arguments are passed to the method all service-level options are returned as a hash
Note
Invalid options do not cause an errors to be raised; the associated key values in the hash returned will be NOTHING
See also

◆ getOptionArgs()

static auto OMQ::UserApi::Service::ServiceApi::getOptionArgs ( *softlist< string args)
static

Returns the value of the named service option or options.

If the option is not set on the service, and it is a valid system option, then the value of the system option will be returned.

Parameters
argsthe list of options to return
Returns
the value requested directly if only one argument is passed, otherwise a hash of option keys and values; note that if no arguments are passed to the method all service-level options are returned as a hash
Note
Invalid options do not cause an errors to be raised; the associated key values in the hash returned will be NOTHING
See also

◆ getResource()

static hash<auto> OMQ::UserApi::Service::ServiceApi::getResource ( string  name,
hash< auto >  ctx,
int  code = 200,
*hash< auto >  hdr 
)
static

Returns the given text or binary file resource as its native type in the "body" key of a hash along with an HTTP response code and optionally HTTP headers; if a template exists, then the template is rendered and returned, if the given resource does not exist, then an exception is raised.

Example:
hash<auto> h = ServiceApi::getResource("image.jpg", cx);
Parameters
namethe name of the resource
ctxthe argument hash to the template code
codethe HTTP response code for the response, if not present then 200 "OK" is assumed
hdrany optional headers for the response (the "Content-Type" header is set from the templates "Content-Type" value automatically)
Returns
a hash with the following keys:
  • code: the HTTP response code corresponding to the code argument
  • body: the rendered template or file resource
  • hdr: a hash of headers corresponding to the hdr argument plus the "Content-Type" key set from the template's "Content-Type" value)
Exceptions
SERVICE-FILE-RESOURCE-ERRORthe given service file resource does not exist
See also

◆ getResourceData()

static data OMQ::UserApi::Service::ServiceApi::getResourceData ( string  name,
*hash< auto >  ctx 
)
static

Returns the given text or binary file resource as its native type; if a template exists, then the template is rendered and returned, if the given resource does not exist, then an exception is raised.

Example:
binary img = ServiceApi::getResourceData("image.jpg");
Parameters
namethe name of the file resource
ctxan optional argument hash used if rendering a template resource
Returns
the given text or binary file resource as its native type; if a template exists, then the template is rendered and returned
Exceptions
SERVICE-FILE-RESOURCE-ERRORthe given service file resource does not exist
See also

◆ getResourceHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getResourceHash ( )
static

returns a hash of the service's file resources (hash keys are service file resource names) or NOTHING if the service has none

Example:
*hash<auto> h = ServiceApi::getResourceHash();
Returns
a hash of the service's file resources (hash keys are service file resource names) or NOTHING if the service has none
See also

◆ getResourceList()

static list<string> OMQ::UserApi::Service::ServiceApi::getResourceList ( )
static

returns a list of the service's file resources or NOTHING if the service has none

Example:
list<auto> l = ServiceApi::getResourceList();
Returns
a list of the service's file resources or NOTHING if the service has none
See also

◆ getResourceWsdl()

static WSDL::WebService OMQ::UserApi::Service::ServiceApi::getResourceWsdl ( string  name,
*hash< auto >  ctx 
)
static

Returns the given file resource as a WSDL::WebService object; any XSD imports are resolved as service resources; if a template exists, then the template is rendered and returned, if the given resource does not exist, then an exception is raised.

Example:
WebService wsdl = ServiceApi::getResourceWsdl("interface1.wsdl");
Parameters
namethe name of the file resource representing the WSDL source
ctxan optional argument hash used if rendering a template resource
Returns
the given file resource as a WSDL::WebService object; any XSD imports are resolved as service resources; if a template exists, then the template is rendered and returned
Exceptions
SERVICE-FILE-RESOURCE-ERRORthe given service file resource does not exist
See also

◆ getRunningWorkflowListAsCurrentUser()

static list<hash<auto> > OMQ::UserApi::Service::ServiceApi::getRunningWorkflowListAsCurrentUser ( string  name,
*string  ver 
)
static

returns a list of hashes giving information about the currently-running workflow execution instances if the current user can access them

Returns
a list of hashes giving information about the currently-running workflow execution instances; if no workflow execution instances are running, then an empty list is returned; otherwise each list element is a hash with the following keys:
  • executionID: the workflow execution instance id
Exceptions
WORKFLOW-ACCESS-ERRORthe current user does not have the right to access one or more running workflows
See also
svc_get_running_workflow_list_as_current_user()

◆ getServiceAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getServiceAccessHash ( )
static

returns a hash of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned

NOTHING is only returned if the current user has access to all services

Returns
a hash of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned
See also
svc_get_service_access_hash()

◆ getServiceAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getServiceAccessList ( )
static

returns a list of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned

NOTHING is only returned if the current user has access to all services

Returns
a list of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned
See also
svc_get_service_access_list()

◆ getServiceInfo()

static hash<auto> OMQ::UserApi::Service::ServiceApi::getServiceInfo ( *hash< auto >  cx)
static

returns information about the current service

Parameters
cxoptional thread context hash from HTTP handler if available
Returns
a hash with the following keys:
  • type: the service type ("user" or "system")
  • name: the name of the service
  • version: the version of the service
  • desc: the description of the service
  • serviceid: the ID of the service, corresponding to SERVICES.SERVICEID in the database
  • status: either OMQ::SSRunning (if there are running threads) or OMQ::SSLoaded
  • threads: the number of currently running threads
  • autostart: the autostart flag
  • loaded: the date/time the service was loaded/started
  • methods: a list of hashes with name and desc keys for each method
  • method: the name of the current method being called
  • resources: a hash of resources attached to the service (may be NOTHING); each hash key is the unique resource name, and the value of each key is a hash with the following keys:
  • type: a string giving the resource type name (ie "HttpGlobalHandler", "HttpListener", "FtpListener", etc)
  • desc: a hashdecl description of the resource
  • info: a hash with additional, free-form information about the resource
  • groups: a list of zero or more strings giving group names the service is a member of
See also
svc_get_service_info()

◆ getServiceInfoAsCurrentUser() [1/2]

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getServiceInfoAsCurrentUser ( string  type,
string  name,
*hash< auto >  cx 
)
static

returns information about the given service from the service name (if it's currently loaded) and if the calling user can access the service

to get information about services whether they are loaded or not, call REST API:

system/metadata/lookupserviceinfo/<type>/<name>
Parameters
typethe type of service (either "system" or "user"; case is ignored)
namethe name of the system service to query
cxoptional thread context hash from HTTP handler if available
Returns
a hash of service information or NOTHING if the service is not loaded; the hash will have the following structure:
  • type: either "system" or "user" corresponding to the argument
  • name: the name of the service
  • version: version of the service
  • desc: description of the service
  • serviceid: service ID
  • status: OMQ::SSRunning or OMQ::SSLoaded
  • threads: number of running threads in the service
  • autostart: True or False if the autostart flag is set
  • loaded: date/time the service was loaded
  • methods: list of hashes for each method with name and desc keys
Exceptions
SERVICE-ACCESS-ERRORthe current user does not have the right to access the given service
See also
svc_get_service_info_as_current_user()

◆ getServiceInfoAsCurrentUser() [2/2]

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getServiceInfoAsCurrentUser ( softint  id,
*hash< auto >  cx 
)
static

returns information about the given service from the serviceid (if it's currently loaded) and if the calling user can access the service

to get information about services whether they are loaded or not, call REST API:

system/metadata/lookupserviceinfo/<type>/<name>
Parameters
idthe serviceid of the service
cxoptional thread context hash from HTTP handler if available
Returns
a hash of service information or NOTHING if the service is not loaded; the hash will have the following structure:
  • type: either "system" or "user" corresponding to the argument
  • name: the name of the service
  • version: version of the service
  • desc: description of the service
  • serviceid: service ID
  • status: OMQ::SSRunning or OMQ::SSLoaded
  • threads: number of running threads in the service
  • autostart: True or False if the autostart flag is set
  • loaded: date/time the service was loaded
  • methods: list of hashes for each method with name and desc keys
Exceptions
SERVICE-ACCESS-ERRORthe current user does not have the right to access the given service
See also
svc_get_service_info_as_current_user()

◆ getStateData()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getStateData ( )
static

returns any service state state data stored with saveStateData()

Returns
any service state state data stored with saveStateData()
Note
service state state data is automatically cleared when a service instance gets a OMQ::StatComplete status
See also

◆ getTemplateHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getTemplateHash ( )
static

returns a hash of the service's template file resources (hash keys are service template resource names) or NOTHING if the service has none

Example:
*hash<auto> h = ServiceApi::getTemplateHash();
Returns
a hash of the service's template file resources (hash keys are service template resource names) or NOTHING if the service has none
See also

◆ getTemplateList()

static list<string> OMQ::UserApi::Service::ServiceApi::getTemplateList ( )
static

returns a list of the service's template file resources or NOTHING if the service has none

Example:
list<auto> l = ServiceApi::getTemplateList();
Returns
a list of the service's template file resources or NOTHING if the service has none
See also

◆ getVmapAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getVmapAccessHash ( )
static

returns a hash of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all value maps

Returns
a hash of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Note
a return value of an empty hash means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps
See also
svc_get_vmap_access_hash()

◆ getVmapAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getVmapAccessList ( )
static

returns a list of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all value maps

Returns
a list of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Note
a return value of an empty list means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps
See also
svc_test_vmap_access()

◆ getWorkflowAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getWorkflowAccessHash ( )
static

returns a hash of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all workflows

Returns
a hash of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
See also
svc_get_workflow_access_hash()

◆ getWorkflowAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getWorkflowAccessList ( )
static

returns a list of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all workflows

Returns
a list of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
See also
svc_get_workflow_access_list()

◆ hasResource()

static bool OMQ::UserApi::Service::ServiceApi::hasResource ( string  name)
static

returns True if the given service file resource exists, False if not

Example:
bool b = ServiceApi::hasResource(name);
Returns
True if the given service file resource exists, False if not
See also

◆ hasTemplate()

static bool OMQ::UserApi::Service::ServiceApi::hasTemplate ( string  name)
static

returns True if the given service template file resource exists, False if not

Example:
bool b = ServiceApi::hasTemplate(name);
Returns
True if the given service template file resource exists, False if not
See also

◆ persistenceRegister()

static OMQ::UserApi::Service::ServiceApi::persistenceRegister ( code  factory)
static

registers the service as providing persistent/dedicated HTTP connection support

Example:
ServiceApi::persistenceRegister(code);
Parameters
factorya closure or call reference that returns a persistence tracking object derived from OMQ::AbstractPersistentDataHelper, takes the following args: hash<auto> cx, *hash<auto> ah
Exceptions
SERVICE-PERSISTENCE-ERRORa persistence handler has already been registered

◆ persistenceThreadTerminate()

static OMQ::UserApi::Service::ServiceApi::persistenceThreadTerminate ( )
static

terminates a persistent connection in the current thread

Example:
ServiceApi::persistenceThreadTerminate();
Exceptions
SERVICE-PERSISTENCE-ERRORthe current thread is not in a persistent connection

◆ registerSoapHandler()

static OMQ::UserApi::Service::ServiceApi::registerSoapHandler ( hash< auto >  h)
static

registers the current service as a SOAP service and exports its methods that map to SOAP operations in the given WSDL to be called from the Qorus HttpServer with the SOAP protocol

Creates a mapping in the system SoapHandler from the given WSDL to the current service. SOAP operations defined in the WSDL will be mapped directly to Qorus service methods with the same names as the SOAP operations.

Parameters
ha hash with the following keys (only wsdl or wsdl_file is required):
  • wsdl, wsdl_file, or wsdl_resource: a URL to the WSDL, the WSDL string (XSD), a WebService object, or a file resource name giving the WSDL file
  • service: a string giving the name of the SOAP service to map to this service; this key is only necessary to set if the WSDL defines multiple SOAP services
  • uri_path: an optional string giving an optional URI path to use when binding the SOAP service
Exceptions
REGISTER-SOAP-HANDLER-ERRORmissing wsdl or wsdl_file key in argument hash; cannot find service; multiple services defined by WSDL but no service key given in argument hash
See also
svc_register_soap_handler()

◆ registerSoapListener()

static list<string> OMQ::UserApi::Service::ServiceApi::registerSoapListener ( hash< auto >  sh,
softstring  bind,
int  family = AF_UNSPEC,
*HttpServer::AbstractAuthenticator  auth,
hash< HttpBindOptionInfo opts = HttpBindOptionInfo >{} 
)
static

starts a dedicated SOAP listener with the given WSDL and registers the current service as a SOAP service and exports its methods that map to SOAP operations in the given WSDL to be called from the Qorus HttpServer with the SOAP protocol

Example:
hash opts.wsdl = ServiceApi::getResourceData("MySoapService.wsdl");
list ret = ServiceApi::registerSoapListener(opts, port);
logInfo("soap listeners: %y", ret);

Creates a mapping in the system SoapHandler from the given WSDL to the current service. SOAP operations defined in the WSDL will be mapped directly to Qorus service methods with the same names as the SOAP operations.

Parameters
sha hash with the following keys (only wsdl, wsdl_file, or wsdl_resource is required)):
  • wsdl, wsdl_file, or wsdl_resource: a URL to the WSDL, the WSDL string (XSD), a WebService object, or a file resource name giving the WSDL file
  • service: a string giving the name of the SOAP service to map to this service; this key is only necessary to set if the WSDL defines multiple SOAP services
  • cert_path: (optional) a path to an X509 certificate for HTTPS listeners
  • key_path: (optional) a path to a private key file for an X509 certificate for HTTPS listeners
  • key_password: (optional) an optional string giving the password for the private key (PEM format only)
  • cert: (optional) a Qore::SSLCertificate object for HTTPS listeners
  • key: (optional) a Qore::SSLPrivateKey object for HTTPS listeners
bindthe bind address of the new listener; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given
familyone of the following network family constants:
  • AF_INET: for binding an IPv4 socket
  • AF_INET6: for binding an IPv6 socket
  • AF_UNSPEC: for binding a socket with any available address family
authif NOTHING then the system authenticator is used, otherwise an authenticator object for the listener; to authenticate all requests, use an object of class PermissiveAuthenticator
optsadditional options for the HTTP handler binding process
Returns
a list of resource names for the HTTP listener resources added to the service
Exceptions
REGISTER-SOAP-LISTENER-ERRORmissing wsdl or wsdl_file key in argument hash; cannot find service; multiple services defined by WSDL but no service key given in argument hash
See also

◆ registerSoapListeners()

static list<string> OMQ::UserApi::Service::ServiceApi::registerSoapListeners ( list< auto >  sl,
softstring  bind,
*hash< auto >  lh,
int  family = AF_UNSPEC,
*HttpServer::AbstractAuthenticator  auth,
hash< HttpBindOptionInfo opts = HttpBindOptionInfo >{} 
)
static

starts a dedicated SOAP listener with one or more WSDLs and registers the current service as a SOAP service and exports all methods that map to SOAP operations in the given WSDLs to be called from the Qorus HttpServer with the SOAP protocol

Example:
list<hash<auto>> sl = (
{"wsdl": ServiceApi::getResourceData("MySoapService1.wsdl"},
{"wsdl": ServiceApi::getResourceData("MySoapService2.wsdl"},
);
list<auto> ret = ServiceApi::registerSoapListeners(sl, port);
logInfo("soap listeners: %y", ret);

Creates a mapping in the system SoapHandler from the given WSDLs to the current service. SOAP operations defined in the WSDLs will be mapped directly to Qorus service methods with the same names as the SOAP operations.

Parameters
sla list of hashes with the following keys (only wsdl, wsdl_file, or wsdl_resource is required):
  • wsdl, wsdl_file, or wsdl_resource: a URL to the WSDL, the WSDL string (XSD), a WebService object, or a file resource name giving the WSDL file
  • service: a string giving the name of the SOAP service to map to this service; this key is only necessary to set if the WSDL defines multiple SOAP services
bindthe bind address of the new listener; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given
lhan optional hash of listener info for HTTPS listeners
  • cert_path: (optional) a path to an X509 certificate for HTTPS listeners
  • key_path: (optional) a path to a private key file for an X509 certificate for HTTPS listeners
  • key_password: (optional) an optional string giving the password for the private key (PEM format only)
  • cert: (optional) a Qore::SSLCertificate object for HTTPS listeners
  • key: (optional) a Qore::SSLPrivateKey object for HTTPS listeners
familyone of the following network family constants:
  • AF_INET: for binding an IPv4 socket
  • AF_INET6: for binding an IPv6 socket
  • AF_UNSPEC: for binding a socket with any available address family
authif NOTHING then the system authenticator is used, otherwise an authenticator object for the listener; to authenticate all requests, use an object of class PermissiveAuthenticator
optsadditional options for the HTTP handler binding process
Returns
a list of resource names for the HTTP listener resources added to the service
Exceptions
REGISTER-SOAP-LISTENER-ERRORmissing wsdl or wsdl_file key in argument hash; cannot find service; multiple services defined by WSDL but no service key given in argument hash
See also

◆ renderTemplate()

static hash<auto> OMQ::UserApi::Service::ServiceApi::renderTemplate ( string  name,
hash< auto >  ctx 
)
static

explicitly renders a template file resource given the template argument hash

Example:
hash<auto> h = ServiceApi::renderTemplate("html/index.qhtml", ctx);
Parameters
namethe template file resource name
ctxthe argument hash to the template code
Returns
a hash with the following keys:
  • code: the HTTP response code corresponding to the code argument
  • body: the rendered template
  • hdr: a hash of headers corresponding to the hdr argument plus the "Content-Type" key set from the template's "Content-Type" value)
Exceptions
TEMPLATE-ERRORthe named template does not exist
See also

◆ saveStateData()

static OMQ::UserApi::Service::ServiceApi::saveStateData ( *hash< auto >  data)
static

serializes the given hash and stores against the service's state data in SERVICE_STATE_DATA

Parameters
datathe state data to serialize and store against the service's state data in SERVICE_STATE_DATA
See also

◆ setOption() [1/2]

static OMQ::UserApi::Service::ServiceApi::setOption ( hash< auto >  opts)
static

Changes option values on a service.

If at least one invalid option is passed to the method, an exception will be raised; however all other valid options in the hash will be set before the exception is raised

Parameters
optsa hash of option-value pairs
Exceptions
SERVICE-OPTION-ERRORinvalid option name
See also

◆ setOption() [2/2]

static OMQ::UserApi::Service::ServiceApi::setOption ( string  option,
auto  value 
)
static

Changes a single option value on a service.

If an invalid option is passed to the method, an exception will be raised.

Parameters
optionthe option to set
valuethe value to set for the option
Exceptions
SERVICE-OPTION-ERRORinvalid option name
See also

◆ sleep()

static int OMQ::UserApi::Service::ServiceApi::sleep ( softint  arg)
static

puts the current thread to sleep for a certain number of seconds

If the service is stopping, this method returns immediately with a return value of -1; otherwise the current thread is put to sleep for the full time period requested. If this method (or usleep()) is called again after -1 is returned, then a "STOP-ERROR" exception is thrown.

Parameters
argthe number of seconds to sleep
Returns
0 if current thread was put to sleep for the full time period; -1 if the sleep was interrupted because the current object is being stopped
Exceptions
STOP-ERRORthe current object is stopping and this method already returned -1 as a warning
See also

◆ startListeners()

static list<hash<auto> > OMQ::UserApi::Service::ServiceApi::startListeners ( softstring  bind,
*string  cert_path,
*string  key_path,
*string  key_password,
*string  name,
int  family = AF_UNSPEC 
)
static

starts one or more new global HTTP listeners; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given

Parameters
bindthe bind address of the new listener; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given
cert_paththe file name of the X.509 certificate in PEM format (only for HTTPS listeners)
key_paththe file name of the private key for the X.509 certificate in PEM format (only for HTTPS listeners)
key_passwordthe optional password for the private key
namean optional name prefix for the listener; the final listener name will have the listener id appended to it and will be returned in the "name" key in each hash element in the return value for each listener started
familyone of the following network family constants:
  • AF_INET: for binding an IPv4 socket
  • AF_INET6: for binding an IPv6 socket
  • AF_UNSPEC: for binding a socket with any available address family
Returns
a list of hashes for each listener started, each hash having the following keys (note that for UNIX domain socket listeners the hostname, hostname_desc, and port keys will not be present):
  • hostname: the hostname of the interface
  • hostname_desc: a descriptive string for the hostname including the address family (ex: "ipv6[localhost]")
  • address: the address of the listener (i.e. "192.168.30.4", etc)
  • address_desc: a descriptive string for the hostname including the address family (ex: "ipv6[::1]")
  • port: the port number
  • family: an integer giving the address family (AF_INET, AF_INET6, AF_UNIX, etc)
  • familystr: a string describing the address family (ex: "ipv6")
  • proto: either "http" or "https"
  • id: the Qorus ID of the listener
  • bind: a string giving the bind address used (ex: "127.0.0.1:8001")
Note
listeners started with this API will be served by global Qorus HTTP handlers; they will not be added as service-specific listeners
See also

◆ startThread()

static int OMQ::UserApi::Service::ServiceApi::startThread ( auto  code)
static

starts a service thread; passes the remaining arguments to the function to the new thread

Parameters
codethe function or service method to call; may be a string giving a function name (string), a call reference, or a closure
Returns
the TID of the new thread
Exceptions
START-SERVICE-THREAD-ERRORthe service has no "stop()" method or too many threads are already active in this service (see qorus.max-service-threads)
See also
svc_start_thread()

◆ startThreadArgs()

static int OMQ::UserApi::Service::ServiceApi::startThreadArgs ( auto  code,
auto  args 
)
static

starts a service thread; uses the second argument as the argument list to pass to the new thread

Parameters
codethe function or service method to call; may be a string giving a function name (string), a call reference, or a closure
argsthe arguments for the function to start in the separate thread
Returns
the TID of the new thread
Exceptions
START-SERVICE-THREAD-ERRORthe service has no "stop()" method or too many threads are already active in this service (see qorus.max-service-threads)
See also
svc_start_thread_args()

◆ stopListener()

static OMQ::UserApi::Service::ServiceApi::stopListener ( softstring  name)
static

stops a single listener based on its name or bind address; does not return until all connections on the listener have closed

See also

◆ stopListenerId()

static OMQ::UserApi::Service::ServiceApi::stopListenerId ( softint  id)
static

stops a single listener based on its listener ID; does not return until all connections on the listener have closed

See also

◆ streamRegister()

static OMQ::UserApi::Service::ServiceApi::streamRegister ( string  name,
string  method,
code  factory,
string  desc 
)
static

registers an HTTP chunked data handler as a service resource

Example:
ServiceApi::streamRegister("stream", "GET", factory, "returns a data stream with log information");
Parameters
namethe name of the stream handler
methodthe HTTP method acceptable for this stream; when acquired with other methods, a 405 Method Not Allowed response is returned
factorya closure or call reference that returns an AbstractRestStreamRequestHandler object, takes the following args: hash cx, *hash ah
desca description for the stream
See also
svc_stream_register()

◆ testAuthorization()

static bool OMQ::UserApi::Service::ServiceApi::testAuthorization ( )
static

tests user authorization for all of permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized)

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors, the method returns False

Returns
if current user does not have all of the given permissions, returns False, otherwise True.
See also

◆ testAuthorizationArgs()

static bool OMQ::UserApi::Service::ServiceApi::testAuthorizationArgs ( softlist< string args)
static

tests user authorization for all of permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized)

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors, the method returns False

Returns
if current user does not have all of the given permissions, returns False, otherwise True.
See also

◆ testAuthorizationOr()

static bool OMQ::UserApi::Service::ServiceApi::testAuthorizationOr ( )
static

tests user authorization for at least one of the permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized)

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors, the method returns False

Returns
if current user does not have at least one of the given permissions, returns False, otherwise True.
See also

◆ testAuthorizationOrArgs()

static bool OMQ::UserApi::Service::ServiceApi::testAuthorizationOrArgs ( softlist< string args)
static

tests user authorization for at least one of the permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized)

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors, the method returns False

Returns
if current user does not have at least one of the given permissions, returns False, otherwise True.
See also

◆ testJobAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testJobAccess ( list< auto >  ids)
static

tests if the current user has access to the given list of job IDs and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idsa list of jobids to check
See also
svc_test_job_access()

◆ testJobAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testJobAccess ( softint  id)
static

tests if the current user has access to the given single job ID and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idthe jobid to check
See also
svc_test_job_access()

◆ testMapperAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testMapperAccess ( list< auto >  ids)
static

tests if the current user has access to the given list of mapper IDs and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idsa list of mapperids to check
See also
svc_test_mapper_access()

◆ testMapperAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testMapperAccess ( softint  id)
static

tests if the current user has access to the given single mapper ID and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idthe mapperid to check
See also
svc_test_mapper_access()

◆ testServiceAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testServiceAccess ( list< auto >  ids)
static

tests if the current user has access to the given list of serviceids and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idsa list of serviceids to check
Exceptions
SERVICE-ACCESS-ERRORno authentication information supplied or user does not have access to the given services
See also
svc_test_service_access()

◆ testServiceAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testServiceAccess ( softint  id)
static

tests if the current user has access to the given single serviceid and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idthe serviceid to check
See also
svc_test_service_access()

◆ testVmapAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testVmapAccess ( list< auto >  ids)
static

tests if the current user has access to the given list of value map IDs and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idsa list of value map ids to check
See also
svc_test_vmap_access()

◆ testVmapAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testVmapAccess ( softint  id)
static

tests if the current user has access to the given single value map ID and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idthe value map id to check
See also
svc_test_vmap_access()

◆ testWorkflowAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testWorkflowAccess ( list< auto >  ids)
static

tests if the current user has access to the given list of workflow IDs and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idsa list of workflowids to check
See also
svc_test_workflow_access()

◆ testWorkflowAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testWorkflowAccess ( softint  id)
static

tests if the current user has access to the given single workflow ID and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idthe workflowid to check
See also
svc_test_workflow_access()

◆ tryGetResource()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::tryGetResource ( string  name,
hash< auto >  ctx,
int  code = 200,
*hash< auto >  hdr 
)
static

Returns the given text or binary file resource as its native type in the "body" key of a hash along with an HTTP response code and optionally HTTP headers; if a template exists, then the template is rendered and returned, if the given resource does not exist, then NOTHING is returned.

Example:
*hash<auto> h = ServiceApi::tryGetResource("image.jpg", cx);
Parameters
namethe name of the resource
ctxthe argument hash to the template code
codethe HTTP response code for the response, if not present then 200 "OK" is assumed
hdrany optional headers for the response (the "Content-Type" header is set from the templates "Content-Type" value automatically)
Returns
NOTHING if the resource does not exist or a hash with the following keys:
  • code: the HTTP response code corresponding to the code argument
  • body: the rendered template or file resource
  • hdr: a hash of headers corresponding to the hdr argument plus the "Content-Type" key set from the template's "Content-Type" value)
See also

◆ tryGetResourceData()

static *data OMQ::UserApi::Service::ServiceApi::tryGetResourceData ( string  name,
*hash< auto >  ctx 
)
static

Returns the given text or binary file resource as its native type; if a template exists, then the template is rendered and returned, if the given resource does not exist, then NOTHING is returned.

Example:
*binary img = UserApi::tryGetResourceData("image.jpg", cx);
Parameters
namethe name of the resource
ctxan optional argument hash to the template code
Returns
NOTHING if the file resource does not exist or the given text or binary file resource as its native type; if a template exists, then the template is rendered and returned
See also

◆ tryGetWfDynamicData()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::tryGetWfDynamicData ( )
static

return the dynamic data hash for the current workflow order if the service call was made from a workflow order, otherwise return NOTHING

See also
svc_try_get_wf_dynamic_data

◆ tryGetWfStaticData()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::tryGetWfStaticData ( )
static

return the static data hash for the current workflow order if the service call was made from a workflow order, otherwise return NOTHING

See also
svc_try_get_wf_static_data()

◆ tryGetWfTempData()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::tryGetWfTempData ( )
static

return the temp data hash for the current workflow order if the service call was made from a workflow order, otherwise return NOTHING

See also
svc_try_get_wf_temp_data()

◆ tryRenderTemplate()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::tryRenderTemplate ( string  name,
hash< auto >  ctx 
)
static

render a template file resource and returns the rendered template if the template exists, otherwise returns NOTHING

Example:
*hash<auto> h = ServiceApi::tryRenderTemplate(name, ctx);
Parameters
namethe template file resource name
ctxthe argument hash to the template code
Returns
NOTHING if the template does not exist or a hash with the following keys:
  • code: the HTTP response code corresponding to the code argument
  • body: the rendered template
  • hdr: a hash of headers corresponding to the hdr argument plus the "Content-Type" key set from the template's "Content-Type" value)
See also

◆ uiExtensionRegister() [1/2]

static OMQ::UserApi::Service::ServiceApi::uiExtensionRegister ( OMQ::QorusExtensionHandler  handler)
static

registers the service as an extension of the system UI

Example:
ServiceApi::uiExtensionRegister(new MyExtensionHandler());
Parameters
handlerthe request handler for the requests to the extension, must be derived from OMQ::QorusExtensionHandler

The registered extension will be available from:

  • default Qorus UI, "Extensions" section
  • directly in URL http(s)://<hostname>:<port>/UIExtension/<service type>-<service name>-<system resource id>

The system resource id value is assigned by Qorus itself, it is not predictable. Also it can vary accross various instalations. You can use uiExtensionRegister(handler, url_name) variant of this method to ensure usage of deterministic URL.

See also
svc_ui_extension_register()

◆ uiExtensionRegister() [2/2]

static OMQ::UserApi::Service::ServiceApi::uiExtensionRegister ( OMQ::QorusExtensionHandler  handler,
string  url_name 
)
static

registers the service as an extension of the system UI with deterministic URL path

Example:
ServiceApi::uiExtensionRegister(new MyExtensionHandler(), "my_extension");
Parameters
handlerthe request handler for the requests to the extension, must be derived from OMQ::QorusExtensionHandler
url_namecustom name used in public URL

The registered extension will be available from:

  • default Qorus UI, "Extensions" section
  • directly in URL http(s)://<hostname>:<port>/UIExtension/<url_name>
See also
svc_ui_extension_register()

◆ usleep() [1/2]

static int OMQ::UserApi::Service::ServiceApi::usleep ( softint  arg)
static

puts the current thread to sleep for a certain number of microseconds

If the service is stopping, this method returns immediately with a return value of -1; otherwise the current thread is put to sleep for the full time period requested. If this method (or sleep()) is called again after -1 is returned, then a "STOP-ERROR" exception is thrown.

Parameters
argthe number of microseconds to sleep (1 microsecond = 1/1000000 of a second)
Returns
0 if current thread was put to sleep for the full time period; -1 if the sleep was interrupted because the current object is being stopped
Exceptions
STOP-ERRORthe current object is stopping and this method already returned -1 as a warning
See also

◆ usleep() [2/2]

static int OMQ::UserApi::Service::ServiceApi::usleep ( date  arg)
static

puts the current thread to sleep for a certain number of microseconds

If the service is stopping, this method returns immediately with a return value of -1; otherwise the current thread is put to sleep for the full time period requested. If this method (or sleep()) is called again after -1 is returned, then a "STOP-ERROR" exception is thrown.

Parameters
argthe amount of time in microseconds to sleep (1 microsecond = 1/1000000 of a second)
Returns
0 if current thread was put to sleep for the full time period; -1 if the sleep was interrupted because the current object is being stopped
Exceptions
STOP-ERRORthe current object is stopping and this method already returned -1 as a warning
See also

◆ waitForEvents()

static hash<auto> OMQ::UserApi::Service::ServiceApi::waitForEvents ( softint  min_id = 1,
timeout  timeout_ms = 0 
)
static

return available system events

by default without any arguments will immediately return all available events in the cache

Parameters
min_idthe minimum event ID to return; no event wil be returned that has an event ID less than this; the first event ID is always 1 (if min_id <= 1 then all events are returned that meet the given criteria)
timeout_msoptional timeout waiting for events; if not present; the method returns immediately
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the method returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned
Note
It is not recommended to use this API in remote services, as high-volume message processing can have a negative impact on a Qorus cluster as a whole
See also
svc_wait_for_events()

◆ waitForEventsAnd()

static hash<auto> OMQ::UserApi::Service::ServiceApi::waitForEventsAnd ( softint  min_id = 1,
auto  filter,
timeout  timeout_ms = 0,
auto  or_not 
)
static

return system events that meet all of the given criteria or none of the optional "or not" criteria

Parameters
min_idthe minimum event ID to return; no event wil be returned that has an event ID less than this; the first event ID is always 1 (if min_id <= 1 then all events are returned that meet the given criteria)
filterthis argument is the criteria list for "logical and" comparisons to be applied to the events. If an event matches all of the criteria hashes in the first argument, then it is included in the resulting list. To match a criteria hash in the second argument with this API call, any of the criteria keys in a single hash can match, therefore, to get pure "logical and" behavior, the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
timeout_msoptional timeout waiting for events; if not present or 0; the method returns immediately
or_notthis argument is an optional criteria list that can augment the list returned with negative matches. If this argument is present and any element in the system’s event list does not match any of the criteria hashes in the third argument, then it is also included in the returned event list. Note that the fourth argument, if present, is processed with inverted logic compared to the second argument; for a single criteria hash to match, all of the criteria given as hash keys in the criteria hash must match, therefore, to get pure inverted "logical or" logic, the caller must specify only one hash key per hash in the list making up the fourth argument; see Event Filter Criteria for a description of each criteria hash
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the method returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
GET-EVENTS-AND-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned
Note
It is not recommended to use this API in remote services, as high-volume message processing can have a negative impact on a Qorus cluster as a whole
See also
svc_wait_for_events_and()

◆ waitForEventsOr()

static hash<auto> OMQ::UserApi::Service::ServiceApi::waitForEventsOr ( softint  min_id = 1,
auto  filter,
timeout  timeout_ms = 0,
auto  and_not 
)
static

return system events that meet any of the given criteria and none of the optional "and not" criteria

Parameters
min_idthe minimum event ID to return; no event wil be returned that has an event ID less than this; the first event ID is always 1 (if min_id <= 1 then all events are returned that meet the given criteria)
filterthis argument is the criteria list for "logical or" comparisons to be applied to the events. If a system event matches any of the criteria hashes in the first argument, then it is included in the resulting list, subject to processing by the optional fourth argument. To match a criteria hash in the second argument with this API call, all of the criteria keys in each hash must match, therefore, to get pure "logical or" behavior the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
timeout_msoptional timeout waiting for events; if not present or 0; the method returns immediately
and_notthis argument is an optional criteria list allowing the resulting event list to be filtered; if any event selected by the second argument matches all criteria hashes in the criteria hashes passed as the third argument, then it is filtered out of the resulting list. Note that the fourth argument, if present, is processed with inverted logic compared to the second argument; for a criteria hash to match, any of the criteria given as hash keys in a criteria hash can match, however, all criteria hashes must match for the filter to operate. Therefore, to get pure "logical and" filtering the caller must specify only one hash key per hash in the list making up the fourth argument; see Event Filter Criteria for a description of each criteria hash
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the method returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
GET-EVENTS-OR-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned
Note
It is not recommended to use this API in remote services, as high-volume message processing can have a negative impact on a Qorus cluster as a whole
See also
svc_wait_for_events_or()

Member Data Documentation

◆ ServiceCallContextKeys

const OMQ::UserApi::Service::ServiceApi::ServiceCallContextKeys = ("socket", "socket-info", "peer-info", "url", "id", "ssl", "user", "client-cert")

keys returned from the cx hash in getCallContext() if present

Since
Qorus 4.0.3

The documentation for this class was generated from the following file: