OMQ::UserApi::Service::ServiceApi Class Reference

primary service API class More...

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

Collaboration diagram for OMQ::UserApi::Service::ServiceApi:

Static Public Member Methods
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< string >	bindHttp (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< string >	getResourceList ()
	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< string >	getTemplateList ()
	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, softlist< string > methods, 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< string >	registerSoapListener (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< string >	registerSoapListeners (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
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
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
static	saveStateData (*hash< auto > data)
	serializes the given hash and stores against the service's state data in SERVICE_STATE_DATA More...
static	saveStateDataPath (string path, auto value)
	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, bool expand_complex_values=True)
	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	setConfigItemChangeCallback (*code callback)
	Set a callback for config item value changes in the 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< auto >	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< auto > params, string status=StatReady)
	creates a workflow order data instance in the database More...
static softint	createRemoteOrder (string remote, string name, *string version, hash< auto > 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< auto > sdata, *hash< auto > opts, *hash< auto > ddata, softint priority=DefaultOrderPriority, *hash< auto > 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 OMQ::QE_CLASS_USER More...
static hash	runtimeProperties ()
	returns Qorus runtime properties as a hash More...
static auto	callNetworkApiArgs (string call, *softlist< auto > 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 hash< auto >	getSystemInfo ()
	returns a hash of system info More...
static int	getSessionId ()
	returns the current Qorus application session ID More...
static	startCapturingObjectsFromJava ()
	Starts capturing Qore objects created from Java APIs in the current interface's object cache. More...
static	stopCapturingObjectsFromJava ()
	Stops capturing Qore objects created from Java APIs in the current interface's object cache. More...
static	startCapturingObjectsFromPython ()
	Starts capturing Qore objects created from Python APIs in the current interface's object cache. More...
static	stopCapturingObjectsFromPython ()
	Stops capturing Qore objects created from Python APIs in the current interface's object cache. More...
static	saveObjectInObjectCache (object obj)
	Saves the object in the object cache. More...
static bool	clearObjectFromObjectCache (object obj)
	Removes the object from the object cache. More...
static *date	checkObjectCache (object obj)
	Returns the date/time the object was cached or NOTHING if the object is not in the cache. More...
static int	getObjectCacheSize ()
	Returns the number of objects in the cache. More...
static int	clearObjectCache ()
	Clears the entire the object cache. More...
static int	clearObjectCache (date cutoff)
	Clears the entire the object cache for all objects cached before the given date/time. More...
static list< hash< CallStackInfo > >	getThreadCallStack ()
	Allows the current thread's call stack to be retrieved in Qorus. 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	logWithLevel (int level, string msg)
	Writes to the current interface log file with the given log level. More...
static	logWithLevelArgs (int level, string msg, *softlist< auto > args)
	Writes to the current interface log file with the given log level. 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 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 (date arg)
	puts the current thread to sleep for a certain number of microseconds More...
static int	usleep (int arg)
	puts the current thread to sleep for a certain number of microseconds More...
static hash< 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< auto > 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 hash< auto >	getUserConnectionTags (string name)
	Returns any tags set on the given 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	updateDynamicOrderData (softint wfiid, hash< auto > new_data)
	updates the given workflow order instance's dynamic data hash atomically More...
static	updateDynamicOrderDataPath (softint wfiid, string path, auto value)
	updates the given workflow order instance's dynamic data hash atomically More...
static *hash< auto >	getUserContextInfo ()
	returns a hash for the current user context More...
static auto	getConfigItemValue (string cfg_item, *hash< auto > local_context, bool expand_complex_values=True)
	returns config item value in the current user context More...
static auto	getInterfaceConfigItemValue (string cfg_item, *hash< auto > local_context, bool expand_complex_values=True)
	returns config item value in the current interface context More...
static hash< auto >	getConfigItemHash (*hash< auto > local_context)
	returns a hash of all configuration items for the current interface More...
static hash< auto >	getInterfaceConfigItemHash (*hash< auto > local_context)
	Returns a hash of all configuration items for the current context as a combination of local and global configuration items. More...
static auto	getGlobalConfigItemValue (string item, *hash< auto > local_context, bool expand_complex_values=True)
	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, bool expand_complex_values=True)
	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 AbstractDataProvider	getDataProvider (string path)
	returns the data provider given by a path string More...
static AbstractDataProvider	getDataProvider (string type, string name, *string path, *hash< auto > opts, *hash< auto > ctxt)
	returns the data provider given by a path string More...
static AbstractDataProviderType	getQorusType (string type_path)
	Returns a data provider type from a direct type path. More...
static AbstractDataProviderType	getTypeFromPath (string path)
	returns a data provider type identified by a path string 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 More...
static auto	getHashDotValue (*hash< auto > var_data, string var_name, *reference< bool > missing_input)
	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, auto template_arg, *hash< auto > local_context, *bool brackets, bool expand_complex_values=True, *reference< bool > missing_input)
	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, bool expand_complex_values=True, *reference< bool > missing_input, *string template_context)
	expands all variables in a templated string More...
static softlist< auto >	expandComplexValue (list< auto > val, *hash< auto > local_context, *string template_context)
	expands all variables in a list with templated values More...
static hash< auto >	expandComplexValue (hash< auto > val, *hash< auto > local_context, *string template_context)
	expands all variables in a hash with templated values 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, NOTHING, False))
	updates all output data More...
static	writeOutputData (*hash< auto > output_data)
	Writes output data using a concise format. 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...
static Qore::StreamReader	getStreamReaderFromLocation (string location)
	Returns a string stream for the file's data at the given location. More...
static Qore::InputStream	getBinaryStreamFromLocation (string location)
	Returns an input stream for file data at the given location. More...
static	writeFileToLocation (string location, data contents)
	Writes data to a file at the given location. More...
static FileLocationHandler::OutputStreamWrapper	getOutputStreamForLocation (string location)
	Returns an output stream for writing data to the given location. More...
static auto	executeFsm (string fsm_name, auto arg)
	Executes the given Finite State Machine and returns the final output. More...
static	registerFsmAsObserver (string fsm_name, DataProvider::Observable observable, string event_id)
	Registers the given Finite State Machine with the given object as an Observer. More...
static public hash< auto >	bindSubworkflow (hash< auto > wf, hash< auto > order)
	This method binds a workflow to a subworkflow step. More...
static public hash< auto >	skipSubworkflow ()
	This method skips binding a workflow to a subworkflow step. More...
static public	submitAsyncKey (string key)
	Binds the given key to the asynchronous step. More...
static public	skipAsyncStep ()
	This method will skip the execution of an asynchronous step. More...
static public	bindEvent (string eventkey)
	binds a workflow synchronization event based on the event key to a workflow synchronization event step (type OMQ::ExecEvent) More...
static public	bindEventUnposted (string eventkey)
	binds a workflow synchronization event based on the event key to a workflow synchronization event step (type OMQ::ExecEvent) only if the event has not yet been posted; if the event has already been posted, then an ALREADY-POSTED exception is raised More...
static public	skipEvent ()
	skips a workflow synchronization event step More...
static	leaveParentFeedback (string key, auto value)
	leaves feedback for a parent workflow More...
static auto	getChildFeedback (string key)
	gets feedback from a child workflow order with the given key More...
static bool	isWorkflowContext ()
	Returns True if the code is executing in an immediate workflow context, False if not. More...
static bool	isServiceContext ()
	Returns True if the code is executing in an immediate service context, False if not. More...
static bool	isJobContext ()
	Returns True if the code is executing in an immediate job context, False if not. 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...

Additional Inherited Members
Static Private Member Methods inherited from OMQ::UserApi::UserApi
static QorusProgram	DynamicLogic (False, CommonParseOptions|PO_NO_INHERIT_USER_CLASSES|PO_NO_INHERIT_USER_FUNC_VARIANTS|PO_NO_INHERIT_GLOBAL_VARS|PO_NO_INHERIT_USER_CONSTANTS|PO_NO_INHERIT_USER_HASHDECLS|PO_NEW_STYLE|PO_STRICT_ARGS|PO_REQUIRE_TYPES, QorusServerDefines)
	Program for dynamic logic.
Private Attributes inherited from OMQ::UserApi::UserApi
const	DataProviderRootValues
	data provider root path values
const	DataTypeRootValues
	data type root path values
const	DataProviderPathTypeValues
	data type path provider type values

Detailed Description

primary service API class

Note

In Python available as svcapi

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

handler

defines parameters and callback routines for the system FTP server

Exceptions

SERVICE-FTP-ERROR

no listeners set in OMQ::AbstractFtpHandler, error starting listener

bindHandler() [1/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

name	the name of the service resource for the dedicated service listener
handler	defines parameters and callback routines for the system HTTP server
url	a regex for the URL to service
content_type	an optional list of Content-Types to match
special_headers	an optional list of special headers to match
isregex	defines if url is a regular expression or not

bindHandler() [2/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

name	the name of the service resource for the dedicated service listener
handler	defines parameters and callback routines for the system HTTP server

Exceptions

BIND-HANDLER-ERROR

cannot bind a handler with listeners to an existing HTTP service 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

handler	defines parameters and callback routines for the system HTTP server
opts	additional 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-ERROR	error starting listener, error binding URL
LISTENER-SHARING-ERROR	there 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

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

call	the full api method name (ex: "omq.system.exec-synchronous-exiting"); see Network System API for a full list
args	any 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-CALL	invalid API method
INVALID-INTERNAL-API-CALL	API may not be called internally (ex: omq.system.shutdown-wait())

See also

• UserApi::callNetworkApiArgs()
• UserApi::callNetworkApi()

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
• [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

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
  • 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 not
  • url: a hash of broken-down URL information (as returned from parseURL())

See also

• UserApi::getUserContextInfo() for a similar method available in all user contexts

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

cx	optional thread context hash from HTTP handler if available

Returns

a string describing the current call context

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_context

the 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-ERROR

thrown 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

Service Configuration Items

getConfigItemValue()

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

static

returns the value of the given service configuration item

Example:

auto val = ServiceApi::getConfigItemValue(item);

Parameters

item	the 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_context	the caller can supply its "local" context for template variables (plus user context info is added - see the UserApi::getUserContextInfo() method)
expand_complex_values	if True then lists and hashes will have their string values expanded recursively

Returns

the value of the given configuration item

Exceptions

CONFIG-ITEM-ERROR

thrown 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

Since

• Qorus 4.1.1 added the expand_complex_values parameter

See also

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

getLastEvents()

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

static

returns the last system events

Parameters

count

the 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-ERROR

this exception is raised if any event API is called a second time after the "shutdown" key is returned

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

count	the 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.
filter	this 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_not	this 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-ERROR	empty or missing filter value
GET-EVENTS-ERROR	non-hash criteria element passed in event filter
INVALID-CRITERIA-CODE	invalid criteria code found in event filter
SHUTDOWN-ERROR	this exception is raised if any event API is called a second time after the "shutdown" key is returned

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

count	the 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.
filter	this 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_not	this 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-ERROR	empty or missing filter value
GET-EVENTS-ERROR	non-hash criteria element passed in event filter
INVALID-CRITERIA-CODE	invalid criteria code found in event filter
SHUTDOWN-ERROR	this exception is raised if any event API is called a second time after the "shutdown" key is returned

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

• get_option()
• getOptionArgs()
• setOption()

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

args	the 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

• getOption()
• setOption()

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

name	the name of the resource
ctx	the argument hash to the template code
code	the HTTP response code for the response, if not present then 200 "OK" is assumed
hdr	any 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-ERROR

the given service file resource does not exist

See also

• getResourceData()
• getResourceWsdl()
• Service File Resources
• bindHttp()
• OMQ::AbstractServiceHttpHandler

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

name	the name of the file resource
ctx	an 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-ERROR

the given service file resource does not exist

See also

• getResourceData()
• getResource()
• getResourceWsdl()
• Service File Resources
• bindHttp()
• OMQ::AbstractServiceHttpHandler

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()
• Service File Resources
• bindHttp()
• OMQ::AbstractServiceHttpHandler

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

• getResourceHash()
• Service File Resources
• bindHttp()
• OMQ::AbstractServiceHttpHandler

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

name	the name of the file resource representing the WSDL source
ctx	an 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-ERROR

the given service file resource does not exist

See also

• getResource()
• getResourceData()
• Service File Resources
• bindHttp()
• OMQ::AbstractServiceHttpHandler

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
  • name: the name of the workflow
  • version: version of the workflow
  • workflowid: the workflowid of the workflow
  • mode: OMQ::WM_Normal, OMQ::WM_Recovery, OMQ::WM_Synchronous
  • status: OMQ::WISInitializing, OMQ::WISRunning, OMQ::WISWaiting, OMQ::WISStopping
  • iterations: number of segment iterations performed so far
  • totalSegments: number of segments executed
  • errors: total number of errors encountered
  • warnings: total number of warnings raised
  • starttime: date/time the execution instance was started
  • options: options set on the workflow execution instance

Exceptions

WORKFLOW-ACCESS-ERROR

the current user does not have the right to access one or more running workflows

getServiceInfo()

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

static

returns information about the current service

Parameters

cx	optional 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

getServiceInfoAsCurrentUser() [1/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

id	the serviceid of the service
cx	optional 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-ERROR

the current user does not have the right to access the given service

getServiceInfoAsCurrentUser() [2/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

type	the type of service (either "system" or "user"; case is ignored)
name	the name of the system service to query
cx	optional 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
• processes: list of process info hashes for remote services

Exceptions

SERVICE-ACCESS-ERROR

the current user does not have the right to access the given service

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

• saveStateData()
• JobApi::getStateData()
• JobApi::saveStateData()
• GET /api/latest/services/{id_or_name}
• PUT /api/latest/services/{id_or_name}?action=setStateData

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

• Service File Resources
• bindHttp()
• OMQ::AbstractServiceHttpHandler

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

• Service File Resources
• bindHttp()
• OMQ::AbstractServiceHttpHandler

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

• Service File Resources
• bindHttp()
• OMQ::AbstractServiceHttpHandler

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

• Service File Resources
• bindHttp()
• OMQ::AbstractServiceHttpHandler

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

factory

a closure or call reference that returns a persistence tracking object derived from OMQ::AbstractPersistentDataHelper, takes the following args: hash&lt:auto> cx, *hash<auto> ah

Exceptions

SERVICE-PERSISTENCE-ERROR

a 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-ERROR

the 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

h

a 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-ERROR

missing wsdl or wsdl_file key in argument hash; cannot find service; multiple services defined by WSDL but no service key given in argument hash

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

sh	a 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
bind	the 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
family	one 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
auth	if NOTHING then the system authenticator is used, otherwise an authenticator object for the listener; to authenticate all requests, use an object of class PermissiveAuthenticator
opts	additional 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-ERROR

missing 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()

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

sl	a 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
bind	the 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
lh	an 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
family	one 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
auth	if NOTHING then the system authenticator is used, otherwise an authenticator object for the listener; to authenticate all requests, use an object of class PermissiveAuthenticator
opts	additional 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-ERROR

missing 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

• registerSoapListener()

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

name	the template file resource name
ctx	the 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-ERROR

the named template does not exist

See also

• Service File Resources
• bindHttp()
• OMQ::AbstractServiceHttpHandler

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

data	the state data to serialize and store against the service's state data in SERVICE_STATE_DATA

See also

• getStateData()
• JobApi::saveStateData()
• JobApi::getStateData()
• GET /api/latest/services/{id_or_name}
• PUT /api/latest/services/{id_or_name}?action=setStateData

saveStateDataPath()

static OMQ::UserApi::Service::ServiceApi::saveStateDataPath ( string  path, auto  value  )

static

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

# will assign {"account": {"id": "123456ABC"}}
ServiceApi::saveStateDataPath("account.id", "123456ABC");

Parameters

path	the path to the data to save
value	the value to merge into existing persistent state data at the given path

See also

• saveStateData()
• getStateData()

Since

Qorus 5.0

setConfigItemChangeCallback()

static OMQ::UserApi::Service::ServiceApi::setConfigItemChangeCallback ( *code  callback )

static

Set a callback for config item value changes in the service.

Example:

class MyService inherits QorusService {
    private:internal myCallback(string config_item_name) {
        # ...
    }
 
    init() {
        setConfigItemChangeCallback(\myCallback());
    }
}

Parameters

callback

the callback in the service; must take a single string argument giving the name of the config item whose value was updated

Note

The callback is executed asynchronously to the update; there can be a lag between the actual update and the delivery of the message from qorus-core to the remote process (if the interface is running remotely), also the callback is always run in a background thread that is unsynchronized with the change of the config item value; keep these facts in mind when writing code that reacts to config item value updates.

Since

Qorus 4.1

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

opts	a hash of option-value pairs

Exceptions

SERVICE-OPTION-ERROR

invalid option name

See also

• set_option()
• getOption()
• getOptionArgs()

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

option	the option to set
value	the value to set for the option

Exceptions

SERVICE-OPTION-ERROR

invalid option name

See also

• set_option()
• getOption()
• getOptionArgs()

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

arg	the 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-ERROR

the current object is stopping and this method already returned -1 as a warning

See also

• omqsleep()
• usleep()

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

bind	the 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_path	the file name of the X.509 certificate in PEM format (only for HTTPS listeners)
key_path	the file name of the private key for the X.509 certificate in PEM format (only for HTTPS listeners)
key_password	the optional password for the private key
name	an 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
family	one 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

• stopListener()
• stopListenerId()

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

code	the 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-ERROR

the service has no "stop()" method or too many threads are already active in this service (see qorus.max-service-threads)

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

code	the function or service method to call; may be a string giving a function name (string), a call reference, or a closure
args	the arguments for the function to start in the separate thread

Returns

the TID of the new thread

Exceptions

START-SERVICE-THREAD-ERROR

the service has no "stop()" method or too many threads are already active in this service (see qorus.max-service-threads)

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

• startListeners()
• stopListenerId()

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

• startListeners()
• stopListener()

streamRegister()

static OMQ::UserApi::Service::ServiceApi::streamRegister ( string  name, softlist< string >  methods, 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

name	the name of the stream handler
methods	one or more HTTP methods acceptable for this stream; when acquired with other methods, a 405 Method Not Allowed response is returned
factory	a closure or call reference that returns an AbstractRestStreamRequestHandler object, takes the following args: hash&lt:auto> cx, *hash<auto> ah
desc	a description for the stream

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

name	the name of the resource
ctx	the argument hash to the template code
code	the HTTP response code for the response, if not present then 200 "OK" is assumed
hdr	any 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()
• Service File Resources
• bindHttp()
• OMQ::AbstractServiceHttpHandler

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

name	the name of the resource
ctx	an 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

• tryGetResource()
• Service File Resources
• bindHttp()
• OMQ::AbstractServiceHttpHandler

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

name	the template file resource name
ctx	the 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

• Service File Resources
• bindHttp()
• OMQ::AbstractServiceHttpHandler

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

handler

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

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

handler	the request handler for the requests to the extension, must be derived from OMQ::QorusExtensionHandler
url_name	custom 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>

usleep() [1/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

arg	the 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-ERROR

the current object is stopping and this method already returned -1 as a warning

See also

• omqusleep()
• sleep()

usleep() [2/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

arg	the 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-ERROR

the current object is stopping and this method already returned -1 as a warning

See also

• omqusleep()
• sleep()

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_id	the 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_ms	optional 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-ERROR

this 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

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_id	the 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)
filter	this 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_ms	optional timeout waiting for events; if not present or 0; the method returns immediately
or_not	this 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-ERROR	empty or missing filter value
GET-EVENTS-ERROR	non-hash criteria element passed in event filter
INVALID-CRITERIA-CODE	invalid criteria code found in event filter
SHUTDOWN-ERROR	this 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

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_id	the 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)
filter	this 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_ms	optional timeout waiting for events; if not present or 0; the method returns immediately
and_not	this 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-ERROR	empty or missing filter value
GET-EVENTS-ERROR	non-hash criteria element passed in event filter
INVALID-CRITERIA-CODE	invalid criteria code found in event filter
SHUTDOWN-ERROR	this 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

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:

• ServiceApi.qc