Qorus service API namespace. More...

Classes
class	QorusService
	The base class for Qorus services. More...

class	ServiceApi
	primary service API class More...

Functions
	svc_check_authorization ()
	checks user authorization for all permissions passed to the function; throws an exception if the user is not authorized More...

	svc_check_authorization_or ()
	checks user authorization for at least one of list of permissions passed to the function; throws an exception if the user is not authorized More...

bool	svc_test_authorization ()
	tests user authorization for all of permissions passed to the function and returns True (if authorization is granted) or False (if the user is not authorized) More...

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

	svc_check_workflow_access (list< auto > ids)
	checks if the current user has access to the given list of workflow IDs; throws an exception if the user is not authorized More...

	svc_check_workflow_access (softint id)
	checks if the current user has access to the given single workflow ID; throws an exception if the user is not authorized More...

bool	svc_test_workflow_access (list< auto > ids)
	tests if the current user has access to the given list of workflow IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...

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

*list< auto >	svc_get_workflow_access_list ()
	returns a list of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...

*hash< auto >	svc_get_workflow_access_hash ()
	returns a hash of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...

	svc_check_workflow_instance_access (softstring wfiid)
	checks if the current user has access to the given workflow_instanceid; throws an exception if the user is not authorized More...

	svc_check_service_access (list< auto > ids)
	checks if the current user has access to the given list of serviceids; throws an exception if the user is not authorized More...

	svc_check_service_access (softint id)
	checks if the current user has access to the given single serviceid; throws an exception if the user is not authorized More...

	svc_check_queue_access (softint queueid, string key)
	checks if the current user has access to the given queue entry (as determined through the workflow access list); throws an exception if the user is not authorized More...

bool	svc_test_service_access (list< auto > ids)
	tests if the current user has access to the given list of serviceids and returns True (if authorization is granted) or False (if the user is not authorized) More...

bool	svc_test_service_access (softint id)
	tests if the current user has access to the given single serviceid and returns True (if authorization is granted) or False (if the user is not authorized) More...

*list< auto >	svc_get_service_access_list ()
	returns a list of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned More...

*hash< auto >	svc_get_service_access_hash ()
	returns a hash of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned More...

	svc_check_job_access (list< auto > ids)
	checks if the current user has access to the given list of job IDs; throws an exception if the user is not authorized More...

	svc_check_job_access (softint id)
	checks if the current user has access to the given single job ID; throws an exception if the user is not authorized More...

bool	svc_test_job_access (list< auto > ids)
	tests if the current user has access to the given list of job IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...

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

*list< auto >	svc_get_job_access_list ()
	returns a list of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...

*hash< auto >	svc_get_job_access_hash ()
	returns a hash of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...

	svc_check_job_instance_access (softstring jiid)
	checks if the current user has access to the given job_instanceid; throws an exception if the user is not authorized More...

	svc_check_mapper_access (list< auto > ids)
	checks if the current user has access to the given list of mapper IDs; throws an exception if the user is not authorized More...

	svc_check_mapper_access (softint id)
	checks if the current user has access to the given single mapper ID; throws an exception if the user is not authorized More...

bool	svc_test_mapper_access (list< auto > ids)
	tests if the current user has access to the given list of mapper IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...

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

*list< auto >	svc_get_mapper_access_list ()
	returns a list of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...

*hash< auto >	svc_get_mapper_access_hash ()
	returns a hash of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...

	svc_check_vmap_access (list< auto > ids)
	checks if the current user has access to the given list of value map IDs; throws an exception if the user is not authorized More...

	svc_check_vmap_access (softint id)
	checks if the current user has access to the given single value map ID; throws an exception if the user is not authorized More...

bool	svc_test_vmap_access (list< auto > ids)
	tests if the current user has access to the given list of value map IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...

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

*list< auto >	svc_get_vmap_access_list ()
	returns a list of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...

*hash< auto >	svc_get_vmap_access_hash ()
	returns a hash of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...

deprecated	registerSoapService (auto wsdl, *string service)
	DEPRECATED: 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 using the old SOAP method calling convention. More...

deprecated	registerSoapService (auto wsdl, list service)
	DEPRECATED: 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 using the old SOAP method calling convention. More...

	svc_register_soap_handler (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...

*hash< auto >	svc_get_http_call_context ()
	returns a hash with HTTP call context information More...

hash< auto >	svc_get_last_events (softint count)
	returns the last system events More...

hash< auto >	svc_get_last_events_or (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...

hash< auto >	svc_get_last_events_and (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...

hash< auto >	svc_wait_for_events (softint min_id=1, timeout timeout_ms=0)
	return available system events More...

hash< auto >	svc_wait_for_events_or (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...

hash< auto >	svc_wait_for_events_and (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...

int	svc_start_thread (auto func)
	starts a service thread; passes the remaining arguments to the function to the new thread More...

int	svc_start_thread_args (auto func, auto args)
	starts a service thread; uses the second argument as the argument list to pass to the new thread More...

hash< auto >	svc_get_service_info (*hash< auto > cx)
	returns information about the current service More...

	svc_bind_ftp (OMQ::AbstractFtpHandler handler)
	binds an FTP handler to the service; listeners are started according to the listener information in the OMQ::AbstractFtpHandler argument More...

list< string >	svc_bind_http (OMQ::AbstractServiceHttpHandler handler, hash< HttpBindOptionInfo > opts=< HttpBindOptionInfo >{})
	binds an HTTP handler to the service More...

	svc_bind_handler (string name, OMQ::AbstractServiceHttpHandler handler)
	binds a new handler to a dedicated HTTP service listener by name More...

	svc_bind_handler (string name, HttpServer::AbstractHttpRequestHandler handler, string url, softlist content_type, softlist special_headers, bool isregex=True)
	binds a new handler to a dedicated HTTP service listener by name More...

*hash< auto >	svc_get_call_context ()
	returns contextual information about the current call More...

string	svc_get_call_context_string (*hash< auto > cx)
	returns a string describing the current call context More...

auto	svc_call_api_as_current_user (string call, softlist< auto > args)
	calls a system API with the argument list to the API method as a top-level argument to this function as the current user More...

*hash< auto >	svc_get_service_info_as_current_user (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...

*hash< auto >	svc_get_service_info_as_current_user (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...

list< auto >	svc_get_running_workflow_list_as_current_user (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...

hash< auto >	svc_get_active_jobs_as_current_user ()
	Returns information on all active jobs visible to the given user. More...

hash< auto >	svc_get_resource (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...

*hash< auto >	svc_try_get_resource (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...

*hash< auto >	svc_get_resource_hash ()
	returns a hash of the service's file resources (hash keys are service file resource names) or NOTHING if the service has none More...

list< auto >	svc_get_resource_list ()
	returns a list of the service's file resources or NOTHING if the service has none More...

data	svc_get_resource_data (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...

WSDL::WebService	svc_get_resource_wsdl (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...

*data	svc_try_get_resource_data (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...

bool	svc_has_resource (string name)
	returns True if the given service file resource exists, False if not More...

hash< auto >	svc_render_template (string name, hash< auto > ctx)
	explicitly renders a template file resource given the template argument hash More...

*hash< auto >	svc_try_render_template (string name, hash< auto > ctx)
	render a template file resource and returns the rendered template if the template exists, otherwise returns NOTHING More...

*hash< auto >	svc_get_template_hash ()
	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...

list< string >	svc_get_template_list ()
	returns a list of the service's template file resources or NOTHING if the service has none More...

bool	svc_has_template (string name)
	returns True if the given service template file resource exists, False if not More...

	svc_ui_extension_register (OMQ::QorusExtensionHandler handler)
	registers the service as an extension of the system UI More...

	svc_ui_extension_register (OMQ::QorusExtensionHandler handler, string url_name)
	registers the service as an extension of the system UI with deterministic URL path More...

	svc_stream_register (string name, string method, code factory, string desc)
	registers an HTTP chunked data handler as a service resource More...

	svc_persistence_register (code factory)
	registers the service as providing persistent/dedicated HTTP connection support More...

	svc_persistence_thread_terminate ()
	terminates a persistent connection in the current thread More...

list< auto >	svc_start_listeners (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...

	svc_stop_listener (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...

	svc_stop_listener_id (softint id)
	stops a single listener based on its listener ID; does not return until all connections on the listener have closed More...

list< string >	svc_register_soap_listener (hash 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...

list< string >	svc_register_soap_listeners (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...

deprecated	slog ()

*hash< auto >	svc_try_get_wf_static_data ()
	return the static data hash for the current workflow order if the service call was made from a workflow order, otherwise return NOTHING More...

*hash< auto >	svc_try_get_wf_dynamic_data ()
	return the dynamic data hash for the current workflow order if the service call was made from a workflow order, otherwise return NOTHING More...

*hash< auto >	svc_try_get_wf_temp_data ()
	return the temp data hash for the current workflow order if the service call was made from a workflow order, otherwise return NOTHING More...

	svc_save_state_data (*hash< auto > data)
	serializes the given hash and stores against the service's state data in `SERVICE_STATE_DATA` More...

*hash< auto >	svc_get_state_data ()
	returns any service state state data stored with service_save_state_data() More...

deprecated any	get_omq_option ()

deprecated	check_authorization ()

deprecated	check_authorization_or ()

deprecated bool	test_authorization ()

deprecated bool	test_authorization_or ()

deprecated	check_workflow_access (list ids)

deprecated	check_workflow_access (softint id)

deprecated bool	test_workflow_access (list ids)

deprecated bool	test_workflow_access (softint id)

deprecated *list	get_workflow_access_list ()

deprecated *hash	get_workflow_access_hash ()

deprecated	check_workflow_instance_access (softstring wfiid)

deprecated	check_service_access (list ids)

deprecated	check_service_access (softint id)

deprecated	check_queue_access (softint queueid, string key)

deprecated bool	test_service_access (list ids)

deprecated bool	test_service_access (softint id)

deprecated *list	get_service_access_list ()

deprecated *hash	get_service_access_hash ()

deprecated	check_job_access (list ids)

deprecated	check_job_access (softint id)

deprecated bool	test_job_access (list ids)

deprecated bool	test_job_access (softint id)

deprecated *list	get_job_access_list ()

deprecated *hash	get_job_access_hash ()

deprecated	check_job_instance_access (softstring jiid)

deprecated	registerSoapHandler (hash h)

deprecated hash	get_last_events (softint count)

deprecated hash	get_last_events_or (softint count, any filter, any and_not)

deprecated hash	get_last_events_and (softint count, any filter, any or_not)

deprecated hash	wait_for_events (softint min_id=1, timeout timeout_ms=0)

deprecated hash	wait_for_events_or (softint min_id=1, any filter, timeout timeout_ms=0, any and_not)

deprecated hash	wait_for_events_and (softint min_id=1, any filter, timeout timeout_ms=0, any or_not)

deprecated *hash	getSoapCallContext ()

deprecated int	startServiceThread (any func)

deprecated int	startServiceThreadArgs (any func, any args)

deprecated hash	getServiceInfo ()

deprecated	bind_ftp (AbstractFtpHandler handler)

deprecated list	bind_http (AbstractServiceHttpHandler handler)

deprecated	bind_handler (string name, AbstractServiceHttpHandler handler)

deprecated	bind_handler (string name, AbstractHttpRequestHandler handler, string url, softlist content_type, softlist special_headers)

deprecated *hash	get_call_context ()

deprecated any	call_api_as_current_user (string call, softlist args)

deprecated *hash	get_service_info_as_current_user (string type, string name)

deprecated *hash	get_service_info_as_current_user (softint id)

deprecated list	get_running_workflow_list_as_current_user (string name, *string ver)

deprecated hash	get_active_jobs_as_current_user ()

hash	get_resource (string name, hash ctx, int code=200, *hash hdr)

*hash	try_get_resource (string name, hash ctx, int code=200, *hash hdr)

*hash	get_resource_hash ()

list	get_resource_list ()

data	get_resource_data (string name, *hash ctx)

*data	try_get_resource_data (string name, *hash ctx)

bool	has_resource (string name)

hash	render_template (string name, hash ctx)

*hash	try_render_template (string name, hash ctx)

*hash	get_template_hash ()

list	get_template_list ()

bool	has_template (string name)

	ui_extension_register (OMQ::QorusExtensionHandler handler)

Detailed Description

Qorus service API namespace.

Function Documentation

◆ bind_ftp()

deprecated OMQ::UserApi::Service::bind_ftp ( AbstractFtpHandler handler )

Deprecated:: by svc_bind_ftp()

◆ bind_handler() [1/2]

deprecated OMQ::UserApi::Service::bind_handler	(	string	name,
		AbstractServiceHttpHandler	handler
	)

Deprecated:: by svc_bind_handler()

◆ bind_handler() [2/2]

deprecated OMQ::UserApi::Service::bind_handler	(	string	name,
		AbstractHttpRequestHandler	handler,
		string	url,
		*softlist	content_type,
		*softlist	special_headers
	)

Deprecated:: by svc_bind_handler()

◆ bind_http()

deprecated list OMQ::UserApi::Service::bind_http ( AbstractServiceHttpHandler handler )

Deprecated:: by svc_bind_http()

◆ call_api_as_current_user()

deprecated any OMQ::UserApi::Service::call_api_as_current_user	(	string	call,
		softlist	args
	)

Deprecated:: by svc_call_api_as_current_user()

◆ check_authorization()

deprecated OMQ::UserApi::Service::check_authorization ( )

Deprecated:: by svc_check_authorization()

◆ check_authorization_or()

deprecated OMQ::UserApi::Service::check_authorization_or ( )

Deprecated:: by svc_check_authorization_or()

◆ check_job_access() [1/2]

deprecated OMQ::UserApi::Service::check_job_access ( list ids )

Deprecated:: by svc_check_job_access()

◆ check_job_access() [2/2]

deprecated OMQ::UserApi::Service::check_job_access ( softint id )

Deprecated:: by svc_check_job_access()

◆ check_job_instance_access()

deprecated OMQ::UserApi::Service::check_job_instance_access ( softstring jiid )

Deprecated:: by svc_check_job_instance_access()

◆ check_queue_access()

deprecated OMQ::UserApi::Service::check_queue_access	(	softint	queueid,
		string	key
	)

Deprecated:: by svc_check_queue_access()

◆ check_service_access() [1/2]

deprecated OMQ::UserApi::Service::check_service_access ( list ids )

Deprecated:: by svc_check_service_access()

◆ check_service_access() [2/2]

deprecated OMQ::UserApi::Service::check_service_access ( softint id )

Deprecated:: by svc_check_service_access()

◆ check_workflow_access() [1/2]

deprecated OMQ::UserApi::Service::check_workflow_access ( list ids )

Deprecated:: by svc_check_workflow_access()

◆ check_workflow_access() [2/2]

deprecated OMQ::UserApi::Service::check_workflow_access ( softint id )

Deprecated:: by svc_check_workflow_access()

◆ check_workflow_instance_access()

deprecated OMQ::UserApi::Service::check_workflow_instance_access ( softstring wfiid )

Deprecated:: by svc_check_workflow_instance_access()

◆ get_active_jobs_as_current_user()

deprecated hash OMQ::UserApi::Service::get_active_jobs_as_current_user ( )

Deprecated:: by svc_get_active_jobs_as_current_user()

◆ get_call_context()

deprecated *hash OMQ::UserApi::Service::get_call_context ( )

Deprecated:: by svc_get_call_context()

◆ get_job_access_hash()

deprecated *hash OMQ::UserApi::Service::get_job_access_hash ( )

Deprecated:: by svc_get_job_access_hash()

◆ get_job_access_list()

deprecated *list OMQ::UserApi::Service::get_job_access_list ( )

Deprecated:: by svc_get_job_access_list()

◆ get_last_events()

deprecated hash OMQ::UserApi::Service::get_last_events ( softint count )

Deprecated:: by svc_get_last_events()

◆ get_last_events_and()

deprecated hash OMQ::UserApi::Service::get_last_events_and	(	softint	count,
		any	filter,
		any	or_not
	)

Deprecated:: by svc_get_last_events_and()

◆ get_last_events_or()

deprecated hash OMQ::UserApi::Service::get_last_events_or	(	softint	count,
		any	filter,
		any	and_not
	)

Deprecated:: by svc_get_last_events_or()

◆ get_omq_option()

deprecated any OMQ::UserApi::Service::get_omq_option ( )

Deprecated:: by get_option()

◆ get_resource()

hash OMQ::UserApi::Service::get_resource	(	string	name,
		hash	ctx,
		int	code = `200`,
		*hash	hdr
	)

Deprecated:: by get_resource()

◆ get_resource_data()

data OMQ::UserApi::Service::get_resource_data	(	string	name,
		*hash	ctx
	)

Deprecated:: by svc_get_resource_data()

◆ get_resource_hash()

*hash OMQ::UserApi::Service::get_resource_hash ( )

Deprecated:: by svc_get_resource_hash()

◆ get_resource_list()

list OMQ::UserApi::Service::get_resource_list ( )

Deprecated:: by svc_get_resource_list()

◆ get_running_workflow_list_as_current_user()

deprecated list OMQ::UserApi::Service::get_running_workflow_list_as_current_user	(	string	name,
		*string	ver
	)

Deprecated:: by svc_get_running_workflow_list_as_current_user()

◆ get_service_access_hash()

deprecated *hash OMQ::UserApi::Service::get_service_access_hash ( )

Deprecated:: by svc_get_service_access_hash()

◆ get_service_access_list()

deprecated *list OMQ::UserApi::Service::get_service_access_list ( )

Deprecated:: by svc_get_service_access_list()

◆ get_service_info_as_current_user() [1/2]

deprecated *hash OMQ::UserApi::Service::get_service_info_as_current_user	(	string	type,
		string	name
	)

Deprecated:: by svc_get_service_info_as_current_user()

◆ get_service_info_as_current_user() [2/2]

deprecated *hash OMQ::UserApi::Service::get_service_info_as_current_user ( softint id )

Deprecated:: by svc_get_service_info_as_current_user()

◆ get_template_hash()

*hash OMQ::UserApi::Service::get_template_hash ( )

Deprecated:: by svc_get_template_hash()

◆ get_template_list()

list OMQ::UserApi::Service::get_template_list ( )

Deprecated:: by svc_get_template_list()

◆ get_workflow_access_hash()

deprecated *hash OMQ::UserApi::Service::get_workflow_access_hash ( )

Deprecated:: by svc_get_workflow_access_hash()

◆ get_workflow_access_list()

deprecated *list OMQ::UserApi::Service::get_workflow_access_list ( )

Deprecated:: by svc_get_workflow_access_list()

◆ getServiceInfo()

deprecated hash OMQ::UserApi::Service::getServiceInfo ( )

Deprecated:: by svc_get_service_info()

◆ getSoapCallContext()

deprecated *hash OMQ::UserApi::Service::getSoapCallContext ( )

Deprecated:: by svc_get_http_call_context()

◆ has_resource()

bool OMQ::UserApi::Service::has_resource ( string name )

Deprecated:: by svc_has_resource()

◆ has_template()

bool OMQ::UserApi::Service::has_template ( string name )

Deprecated:: by svc_has_template()

◆ registerSoapHandler()

deprecated OMQ::UserApi::Service::registerSoapHandler ( hash h )

Deprecated:: by svc_register_soap_handler()

◆ registerSoapService() [1/2]

deprecated OMQ::UserApi::Service::registerSoapService	(	auto	wsdl,
		*string	service
	)

DEPRECATED: 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 using the old SOAP method calling convention.

Deprecated:: use registerSoapHandler() instead

◆ registerSoapService() [2/2]

deprecated OMQ::UserApi::Service::registerSoapService	(	auto	wsdl,
		list	service
	)

DEPRECATED: 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 using the old SOAP method calling convention.

Deprecated:: use registerSoapHandler() instead

◆ render_template()

hash OMQ::UserApi::Service::render_template	(	string	name,
		hash	ctx
	)

Deprecated:: by svc_render_template()

◆ slog()

deprecated OMQ::UserApi::Service::slog ( )

Deprecated:: by log()

◆ startServiceThread()

deprecated int OMQ::UserApi::Service::startServiceThread ( any func )

Deprecated:: by svc_start_thread()

◆ startServiceThreadArgs()

deprecated int OMQ::UserApi::Service::startServiceThreadArgs	(	any	func,
		any	args
	)

Deprecated:: by svc_start_thread_args()

◆ svc_bind_ftp()

OMQ::UserApi::Service::svc_bind_ftp ( OMQ::AbstractFtpHandler handler )

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

Since: Qorus 2.6.0

Note: prior to Qorus 3.0.2 this function was known as bind_ftp(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::bindFtp()

◆ svc_bind_handler() [1/2]

OMQ::UserApi::Service::svc_bind_handler	(	string	name,
		OMQ::AbstractServiceHttpHandler	handler
	)

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

Since: Qorus 2.8.1.p7

Note: prior to Qorus 3.0.2 this function was known as bind_handler(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::bindHandler()

◆ svc_bind_handler() [2/2]

OMQ::UserApi::Service::svc_bind_handler	(	string	name,
		HttpServer::AbstractHttpRequestHandler	handler,
		string	url,
		*softlist	content_type,
		*softlist	special_headers,
		bool	isregex = `True`
	)

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

Since: Qorus 2.8.1.p7

Note: prior to Qorus 3.0.2 this function was known as bind_handler(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::bindHandler()

◆ svc_bind_http()

list<string> OMQ::UserApi::Service::svc_bind_http	(	OMQ::AbstractServiceHttpHandler	handler,
		hash< HttpBindOptionInfo >	opts = `< HttpBindOptionInfo >{}`
	)

binds an HTTP handler to the service

if any listener information is present, then 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-NOT-ALLOWED-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`

Since: Qorus 2.6.2

Note: prior to Qorus 3.0.2 this function was known as bind_http(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::bindHttp()

◆ svc_call_api_as_current_user()

auto OMQ::UserApi::Service::svc_call_api_as_current_user	(	string	call,
		softlist< auto >	args
	)

calls a system API with the argument list to the API method as a top-level argument to this function 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())

Note: prior to Qorus 3.0.2 this function was known as call_api_as_current_user(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_check_authorization()

OMQ::UserApi::Service::svc_check_authorization ( )

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

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

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

Exceptions

AUTHORIZATION-ERROR no authentication information supplied or user does not have all required permissions

Note: prior to Qorus 3.0.2 this function was known as check_authorization(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_check_authorization_or()

OMQ::UserApi::Service::svc_check_authorization_or ( )

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

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

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

Exceptions

AUTHORIZATION-ERROR no authentication information supplied or user does not have any of the permissions given

Note: prior to Qorus 3.0.2 this function was known as check_authorization_or(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_check_job_access() [1/2]

OMQ::UserApi::Service::svc_check_job_access ( list< auto > ids )

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

Parameters

ids	a list of jobids to check

Since: Qorus 2.6.0

Exceptions

JOB-ACCESS-ERROR the user does not have access to one or more of the given jobs

Note: prior to Qorus 3.0.2 this function was known as check_job_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::checkJobAccess()

◆ svc_check_job_access() [2/2]

OMQ::UserApi::Service::svc_check_job_access ( softint id )

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

Parameters

id	the jobid to check

Since: Qorus 2.6.1

Exceptions

JOB-ACCESS-ERROR the user does not have access to the given job

Note: prior to Qorus 3.0.2 this function was known as check_job_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::checkJobAccess()

◆ svc_check_job_instance_access()

OMQ::UserApi::Service::svc_check_job_instance_access ( softstring jiid )

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

Parameters

jiid	the job_instanceid to check

Exceptions

JOB-ACCESS-ERROR the user does not have access to the given job

Since: Qorus 2.6.1

Note: prior to Qorus 3.0.2 this function was known as check_job_instance_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::checkJobInstanceAccess()

◆ svc_check_mapper_access() [1/2]

OMQ::UserApi::Service::svc_check_mapper_access ( list< auto > ids )

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

Parameters

ids	a list of mapperids to check

Since: Qorus 3.1

Exceptions

MAPPER-ACCESS-ERROR the user does not have access to one or more of the given mappers

See also: ServiceApi::checkMapperAccess()

◆ svc_check_mapper_access() [2/2]

OMQ::UserApi::Service::svc_check_mapper_access ( softint id )

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

Parameters

id	the mapperid to check

Since: Qorus 3.1

Exceptions

MAPPER-ACCESS-ERROR the user does not have access to the given mapper

See also: ServiceApi::checkMapperAccess()

◆ svc_check_queue_access()

OMQ::UserApi::Service::svc_check_queue_access	(	softint	queueid,
		string	key
	)

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

Parameters

queueid	the queue ID to check
key	the key value in queue given by the first argument to check

Since: Qorus 2.6.0

Exceptions

WORKFLOW-ACCESS-ERROR no authentication information supplied or user does not have access to the given workflow

Note: prior to Qorus 3.0.2 this function was known as check_queue_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::checkQueueAccess()

◆ svc_check_service_access() [1/2]

OMQ::UserApi::Service::svc_check_service_access ( list< auto > ids )

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

Parameters

ids	a list of serviceids to check

Since: Qorus 2.6.0

Exceptions

SERVICE-ACCESS-ERROR no authentication information supplied or user does not have access to one or more of the given services

Note: prior to Qorus 3.0.2 this function was known as check_service_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::checkServiceAccess()

◆ svc_check_service_access() [2/2]

OMQ::UserApi::Service::svc_check_service_access ( softint id )

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

Parameters

id	the serviceid to check

Since: Qorus 2.6.0

Exceptions

SERVICE-ACCESS-ERROR no authentication information supplied or user does not have access to the given service

Note: prior to Qorus 3.0.2 this function was known as check_service_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::checkServiceAccess()

◆ svc_check_vmap_access() [1/2]

OMQ::UserApi::Service::svc_check_vmap_access ( list< auto > ids )

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

Parameters

ids	a list of value map ids to check

Since: Qorus 3.1

Exceptions

VMAP-ACCESS-ERROR the user does not have access to one or more of the given value maps

See also: ServiceApi::checkVmapAccess()

◆ svc_check_vmap_access() [2/2]

OMQ::UserApi::Service::svc_check_vmap_access ( softint id )

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

Parameters

id	the value map id to check

Since: Qorus 3.1

Exceptions

VMAP-ACCESS-ERROR the user does not have access to the given value map

See also: ServiceApi::checkVmapAccess()

◆ svc_check_workflow_access() [1/2]

OMQ::UserApi::Service::svc_check_workflow_access ( list< auto > ids )

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

Parameters

ids	a list of workflowids to check

Since: Qorus 2.6.0

Exceptions

WORKFLOW-ACCESS-ERROR the user does not have access to one or more of the given workflows

Note: prior to Qorus 3.0.2 this function was known as check_workflow_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::checkWorkflowAccess()

◆ svc_check_workflow_access() [2/2]

OMQ::UserApi::Service::svc_check_workflow_access ( softint id )

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

Parameters

id	the workflowid to check

Since: Qorus 2.6.0

Exceptions

WORKFLOW-ACCESS-ERROR the user does not have access to the given workflow

Note: prior to Qorus 3.0.2 this function was known as check_workflow_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::checkWorkflowAccess()

◆ svc_check_workflow_instance_access()

OMQ::UserApi::Service::svc_check_workflow_instance_access ( softstring wfiid )

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

Parameters

wfiid the workflow_instanceid to check

Since: Qorus 2.6.0

Exceptions

WORKFLOW-ACCESS-ERROR no authentication information supplied or user does not have access to the given workflow

Note: prior to Qorus 3.0.2 this function was known as check_workflow_instance_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::checkWorkflowInstanceAccess()

◆ svc_get_active_jobs_as_current_user()

hash<auto> OMQ::UserApi::Service::svc_get_active_jobs_as_current_user ( )

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

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

Returns

a hash is keyed by job name; the hash values are job information hashes with the following keys:

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

Since: Qorus 2.8.1.p4

Note: prior to Qorus 3.0.2 this function was known as get_active_jobs_as_current_user(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::getActiveJobsAsCurrentUser()

◆ svc_get_call_context()

*hash<auto> OMQ::UserApi::Service::svc_get_call_context ( )

returns contextual information about the current call

Returns

NOTHING if no context information is available, otherwise a hash with the following possible keys; keys actually present depend on the context of the caller to the service method:

wf: this key is present if the call to the service method originated from workflow code while processing an order; the value is a hash with the following keys:
- name: the name of the workflow
- version: the version of the workflow
- workflowid: the workflowid of the workflow
- workflow_instanceid: the workflow_instanceid of the order being executed
- stepid: the stepid of the step being executed
- ind: the array step index of the step being executed
- priority: the priority of the workflow order
- started: the date/time the order started processing
- options: the current workflow execution instance option hash
job: this key is present if the call to the service method originated from job code; the value is a hash with the following keys:
- jobid: the metadata jobid of the job type
- job_instanceid: the id of the job instance
- name: the job name
- version: the job version
- description: the job description
- trigger: a string describing the timer/trigger for the job
- last_executed: the last executed date/time of the job (NOTHING if never executed before the current iteration)
- last_executed_job_instanceid: the last executed instance id of the job
- single_instance: True if the job can only be run in a single Qorus instance, False if no such restriction is enabled
- next: the next trigger date/time
cx: this key is present if the call to the service method originated externally through the network API; the value is a hash with the following keys:
- 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())
- peer-info: a hash of socket information for the remote socket (as returned by Socket::getPeerInfo())
- url: a hash of broken-down URL information (as returned from parseURL())
- id: the unique HTTP connection ID
- ssl: True if the request was encrypted with HTTPS, False if no
- user: the current RBAC username (if any)

Since: Qorus 2.6.3.p40

Note: prior to Qorus 3.0.2 this function was known as get_call_context(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

ServiceApi::getCallContext()
get_user_context_info() for a similar function available in all user contexts

◆ svc_get_call_context_string()

string OMQ::UserApi::Service::svc_get_call_context_string ( *hash< auto > cx )

returns a string describing the current call context

Example:: string str = svc_get_call_context_string();

Parameters

cx	optional thread context hash from HTTP handler if available

Returns: a string describing the current call context

Since: Qorus 3.1.0

See also: ServiceApi::getCallContextString()

◆ svc_get_http_call_context()

*hash<auto> OMQ::UserApi::Service::svc_get_http_call_context ( )

returns a hash with HTTP call context information

Note

prior to Qorus 3.0.2 this function was known as getSoapCallContext(), and is still imported with this old camel-case name for backwards compatibility
this call is relevant for any external HTTP call and not only for SOAP calls

See also: ServiceApi::getHttpCallContext()

◆ svc_get_job_access_hash()

*hash<auto> OMQ::UserApi::Service::svc_get_job_access_hash ( )

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

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

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

Since: Qorus 2.8.0.p1

Note: prior to Qorus 3.0.2 this function was known as get_job_access_hash(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::getJobAccessHash()

◆ svc_get_job_access_list()

*list<auto> OMQ::UserApi::Service::svc_get_job_access_list ( )

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

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

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

Since: Qorus 2.6.1

Note: prior to Qorus 3.0.2 this function was known as get_job_access_list(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::getJobAccessList()

◆ svc_get_last_events()

hash<auto> OMQ::UserApi::Service::svc_get_last_events ( softint count )

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 function 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

Since: Qorus 2.0.2

Note: prior to Qorus 3.0.2 this function was known as get_last_events(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::getLastEvents()

◆ svc_get_last_events_and()

hash<auto> OMQ::UserApi::Service::svc_get_last_events_and	(	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

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 function 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

Since: Qorus 2.0.2

Note: prior to Qorus 3.0.2 this function was known as get_last_events_and(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::getLastEventsAnd()

◆ svc_get_last_events_or()

hash<auto> OMQ::UserApi::Service::svc_get_last_events_or	(	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

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 function 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

Since: Qorus 2.0.2

Note: prior to Qorus 3.0.2 this function was known as get_last_events_or(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::getLastEventsOr()

◆ svc_get_mapper_access_hash()

*hash<auto> OMQ::UserApi::Service::svc_get_mapper_access_hash ( )

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

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

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

Note: a return value of an empty hash means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps

Since: Qorus 3.1

See also: ServiceApi::getMapperAccessHash()

◆ svc_get_mapper_access_list()

*list<auto> OMQ::UserApi::Service::svc_get_mapper_access_list ( )

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

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

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

Note: a return value of an empty list means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps

Since: Qorus 3.1

See also: ServiceApi::getMapperAccessList()

◆ svc_get_resource()

hash<auto> OMQ::UserApi::Service::svc_get_resource	(	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.

Example:: hash h = svc_get_resource("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

Since: Qorus 3.0.0

Note: prior to Qorus 3.0.2 this function was known as get_resource(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_get_resource_data()

data OMQ::UserApi::Service::svc_get_resource_data	(	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.

Example:: binary img = svc_get_resource_data("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

Since: Qorus 3.0.0

Note: prior to Qorus 3.0.2 this function was known as get_resource_data(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_get_resource_hash()

*hash<auto> OMQ::UserApi::Service::svc_get_resource_hash ( )

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 h = svc_get_resource_hash();

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

Since: Qorus 3.0.0

Note: prior to Qorus 3.0.2 this function was known as get_resource_hash(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_get_resource_list()

list<auto> OMQ::UserApi::Service::svc_get_resource_list ( )

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

Example:: list l = svc_get_resource_list();

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

Since: Qorus 3.0.0

Note: prior to Qorus 3.0.2 this function was known as get_resource_list(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_get_resource_wsdl()

WSDL::WebService OMQ::UserApi::Service::svc_get_resource_wsdl	(	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.

Example:: WebService wsdl = svc_get_resource_wsdl("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

Since: Qorus 3.1.0

See also

◆ svc_get_running_workflow_list_as_current_user()

list<auto> OMQ::UserApi::Service::svc_get_running_workflow_list_as_current_user	(	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

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
- logfile: log file name

Exceptions

WORKFLOW-ACCESS-ERROR the current user does not have the right to access one or more running workflows

Note: prior to Qorus 3.0.2 this function was known as get_running_workflow_list_as_current_user(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::getRunningWorkflowListAsCurrentUser()

◆ svc_get_service_access_hash()

*hash<auto> OMQ::UserApi::Service::svc_get_service_access_hash ( )

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

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

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

Since: Qorus 2.8.0.p1

Note: prior to Qorus 3.0.2 this function was known as get_service_access_hash(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::getServiceAccessHash()

◆ svc_get_service_access_list()

*list<auto> OMQ::UserApi::Service::svc_get_service_access_list ( )

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

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

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

Since: Qorus 2.6.0

Note: prior to Qorus 3.0.2 this function was known as get_service_access_list(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::getServiceAccessList()

◆ svc_get_service_info()

hash<auto> OMQ::UserApi::Service::svc_get_service_info ( *hash< auto > cx )

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

Note: prior to Qorus 3.0.2 this function was known as getServiceInfo(), and is still imported with this old camel-case name for backwards compatibility

See also: ServiceApi::getServiceInfo()

◆ svc_get_service_info_as_current_user() [1/2]

*hash<auto> OMQ::UserApi::Service::svc_get_service_info_as_current_user	(	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

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

Exceptions

SERVICE-ACCESS-ERROR the current user does not have the right to access the given service

Note: prior to Qorus 3.0.2 this function was known as get_service_info_as_current_user(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::getServiceInfoAsCurrentUser()

◆ svc_get_service_info_as_current_user() [2/2]

*hash<auto> OMQ::UserApi::Service::svc_get_service_info_as_current_user	(	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

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

Note: prior to Qorus 3.0.2 this function was known as get_service_info_as_current_user(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::getServiceInfoAsCurrentUser()

◆ svc_get_state_data()

*hash<auto> OMQ::UserApi::Service::svc_get_state_data ( )

returns any service state state data stored with service_save_state_data()

Returns: any service state state data stored with service_save_state_data()

Note: service state state data is automatically cleared when a service instance gets a OMQ::StatComplete status

Since: Qorus 3.1.0

See also

◆ svc_get_template_hash()

*hash<auto> OMQ::UserApi::Service::svc_get_template_hash ( )

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 h = svc_get_template_hash();

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

Since: Qorus 3.0.0

Note: prior to Qorus 3.0.2 this function was known as get_template_hash(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_get_template_list()

list<string> OMQ::UserApi::Service::svc_get_template_list ( )

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

Example:: list<string> l = svc_get_template_list();

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

Since: Qorus 3.0.0

Note: prior to Qorus 3.0.2 this function was known as get_template_list(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_get_vmap_access_hash()

*hash<auto> OMQ::UserApi::Service::svc_get_vmap_access_hash ( )

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

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

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

Note: a return value of an empty hash means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps

Since: Qorus 3.1

See also: ServiceApi::getVmapAccessHash()

◆ svc_get_vmap_access_list()

*list<auto> OMQ::UserApi::Service::svc_get_vmap_access_list ( )

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

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

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

Note: a return value of an empty list means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps

Since: Qorus 3.1

See also: ServiceApi::getVmapAccessList()

◆ svc_get_workflow_access_hash()

*hash<auto> OMQ::UserApi::Service::svc_get_workflow_access_hash ( )

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

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

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

Since: Qorus 2.8.0.p1

Note: prior to Qorus 3.0.2 this function was known as get_workflow_access_hash(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::getWorkflowAccessHash()

◆ svc_get_workflow_access_list()

*list<auto> OMQ::UserApi::Service::svc_get_workflow_access_list ( )

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

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

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

Since: Qorus 2.6.0

Note: prior to Qorus 3.0.2 this function was known as get_workflow_access_list(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::getWorkflowAccessList()

◆ svc_has_resource()

bool OMQ::UserApi::Service::svc_has_resource ( string name )

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

Example:: bool b = svc_has_resource(name);

Returns: True if the given service file resource exists, False if not

Since: Qorus 3.0.0

Note: prior to Qorus 3.0.2 this function was known as has_resource(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_has_template()

bool OMQ::UserApi::Service::svc_has_template ( string name )

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

Example:: bool b = svc_has_template(name);

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

Since: Qorus 3.0.0

Note: prior to Qorus 3.0.2 this function was known as has_template(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_persistence_register()

OMQ::UserApi::Service::svc_persistence_register ( code factory )

registers the service as providing persistent/dedicated HTTP connection support

Example:: svc_persistence_register(code);

Parameters

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

Exceptions

SERVICE-PERSISTENCE-ERROR a persistence handler has already been registered

Since: Qorus 3.0.2

See also: ServiceApi::persistenceRegister()

◆ svc_persistence_thread_terminate()

OMQ::UserApi::Service::svc_persistence_thread_terminate ( )

terminates a persistent connection in the current thread

Example:: svc_persistence_thread_terminate();

Exceptions

SERVICE-PERSISTENCE-ERROR the current thread is not in a persistent connection

Since: Qorus 3.0.2

See also: ServiceApi::persistenceThreadTerminate()

◆ svc_register_soap_handler()

OMQ::UserApi::Service::svc_register_soap_handler ( 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

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

Note: prior to Qorus 3.0.2 this function was known as registerSoapHandler(), and is still imported with this old camel-case name for backwards compatibility

See also: ServiceApi::registerSoapHandler()

◆ svc_register_soap_listener()

list<string> OMQ::UserApi::Service::svc_register_soap_listener	(	hash	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

Example:: hash opts.wsdl = svc_get_resource_data("MySoapService.wsdl");
list ret = svc_register_soap_listener(opts, port);
log(LL_INFO, "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

Since: Qorus 3.0.4.p2

See also

◆ svc_register_soap_listeners()

list<string> OMQ::UserApi::Service::svc_register_soap_listeners	(	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

Example:: list sl = (
("wsdl": svc_get_resource_data("MySoapService1.wsdl"),
("wsdl": svc_get_resource_data("MySoapService2.wsdl"),
);
list ret = svc_register_soap_listeners(sl, port);
log(LL_INFO, "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

Since: Qorus 3.1.0

See also

◆ svc_render_template()

hash<auto> OMQ::UserApi::Service::svc_render_template	(	string	name,
		hash< auto >	ctx
	)

explicitly renders a template file resource given the template argument hash

Example:: hash<auto> h = svc_render_template("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

Since: Qorus 3.0.0

Note: prior to Qorus 3.0.2 this function was known as render_template(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_save_state_data()

OMQ::UserApi::Service::svc_save_state_data ( *hash< auto > data )

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`

Since: Qorus 3.1.0

See also

◆ svc_start_listeners()

list<auto> OMQ::UserApi::Service::svc_start_listeners	(	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

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

Since: Qorus 3.0.4.p2

See also

◆ svc_start_thread()

int OMQ::UserApi::Service::svc_start_thread ( auto func )

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

Parameters

func	the function 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)

Note: prior to Qorus 3.0.2 this function was known as startServiceThread(), and is still imported with this old camel-case name for backwards compatibility

See also: ServiceApi::startThreadArgs()

◆ svc_start_thread_args()

int OMQ::UserApi::Service::svc_start_thread_args	(	auto	func,
		auto	args
	)

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

Parameters

func	the function 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)

Note: prior to Qorus 3.0.2 this function was known as startServiceThreadArgs(), and is still imported with this old camel-case name for backwards compatibility

See also: ServiceApi::startThreadArgs()

◆ svc_stop_listener()

OMQ::UserApi::Service::svc_stop_listener ( softstring name )

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

See also

Since: Qorus 3.0.4.p2

See also: ServiceApi::stopListener()

◆ svc_stop_listener_id()

OMQ::UserApi::Service::svc_stop_listener_id ( softint id )

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

Since: Qorus 3.0.4.p2

See also

◆ svc_stream_register()

OMQ::UserApi::Service::svc_stream_register	(	string	name,
		string	method,
		code	factory,
		string	desc
	)

registers an HTTP chunked data handler as a service resource

Example:: svc_stream_register("stream", "GET", factory, "returns a data stream with log information");

Parameters

name	the name of the stream handler
method	the HTTP method 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<auto> cx, *hash<auto> ah
desc	a description for the stream

Since: Qorus 3.0.2

See also: ServiceApi::streamRegister()

◆ svc_test_authorization()

bool OMQ::UserApi::Service::svc_test_authorization ( )

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

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

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

Note: prior to Qorus 3.0.2 this function was known as test_authorization(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_test_authorization_or()

bool OMQ::UserApi::Service::svc_test_authorization_or ( )

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

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

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

Note: prior to Qorus 3.0.2 this function was known as test_authorization_or(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_test_job_access() [1/2]

bool OMQ::UserApi::Service::svc_test_job_access ( list< auto > ids )

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

Parameters

ids	a list of jobids to check

Since: Qorus 2.6.1

Note: prior to Qorus 3.0.2 this function was known as test_job_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::testJobAccess()

◆ svc_test_job_access() [2/2]

bool OMQ::UserApi::Service::svc_test_job_access ( softint id )

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

Parameters

id	the jobid to check

Since: Qorus 2.6.1

Note: prior to Qorus 3.0.2 this function was known as test_job_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::testJobAccess()

◆ svc_test_mapper_access() [1/2]

bool OMQ::UserApi::Service::svc_test_mapper_access ( list< auto > ids )

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

Parameters

ids	a list of mapperids to check

Since: Qorus 3.1

See also: ServiceApi::testMapperAccess()

◆ svc_test_mapper_access() [2/2]

bool OMQ::UserApi::Service::svc_test_mapper_access ( softint id )

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

Parameters

id	the mapperid to check

Since: Qorus 3.1

See also: ServiceApi::testMapperAccess()

◆ svc_test_service_access() [1/2]

bool OMQ::UserApi::Service::svc_test_service_access ( list< auto > ids )

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

Parameters

ids	a list of serviceids to check

Since: Qorus 2.6.0

Exceptions

SERVICE-ACCESS-ERROR no authentication information supplied or user does not have access to the given services

Note: prior to Qorus 3.0.2 this function was known as test_service_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::testServiceAccess()

◆ svc_test_service_access() [2/2]

bool OMQ::UserApi::Service::svc_test_service_access ( softint id )

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

Parameters

id	the serviceid to check

Since: Qorus 2.6.0

Note: prior to Qorus 3.0.2 this function was known as test_service_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::testServiceAccess()

◆ svc_test_vmap_access() [1/2]

bool OMQ::UserApi::Service::svc_test_vmap_access ( list< auto > ids )

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

Parameters

ids	a list of value map ids to check

Since: Qorus 3.1

See also: ServiceApi::testVmapAccess()

◆ svc_test_vmap_access() [2/2]

bool OMQ::UserApi::Service::svc_test_vmap_access ( softint id )

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

Parameters

id	the value map id to check

Since: Qorus 3.1

See also: ServiceApi::testVmapAccess()

◆ svc_test_workflow_access() [1/2]

bool OMQ::UserApi::Service::svc_test_workflow_access ( list< auto > ids )

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

Parameters

ids	a list of workflowids to check

Since: Qorus 2.6.0

Note: prior to Qorus 3.0.2 this function was known as test_workflow_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::checkWorkflowAccess()

◆ svc_test_workflow_access() [2/2]

bool OMQ::UserApi::Service::svc_test_workflow_access ( softint id )

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

Parameters

id	the workflowid to check

Since: Qorus 2.6.0

Note: prior to Qorus 3.0.2 this function was known as test_workflow_access(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::checkWorkflowAccess()

◆ svc_try_get_resource()

*hash<auto> OMQ::UserApi::Service::svc_try_get_resource	(	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.

Example:: *hash h = svc_try_get_resource("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)

Since: Qorus 3.0.0

Note: prior to Qorus 3.0.2 this function was known as try_get_resource(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_try_get_resource_data()

*data OMQ::UserApi::Service::svc_try_get_resource_data	(	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.

Example:: binary img = svc_try_get_resource_data("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

Since: Qorus 3.0.0

Note: prior to Qorus 3.0.2 this function was known as try_get_resource_data(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_try_get_wf_dynamic_data()

*hash<auto> OMQ::UserApi::Service::svc_try_get_wf_dynamic_data ( )

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

Since: Qorus 3.1.0

See also: ServiceApi::tryGetWfDynamicData()

◆ svc_try_get_wf_static_data()

*hash<auto> OMQ::UserApi::Service::svc_try_get_wf_static_data ( )

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

Since: Qorus 3.1.0

See also: ServiceApi::tryGetWfStaticData()

◆ svc_try_get_wf_temp_data()

*hash<auto> OMQ::UserApi::Service::svc_try_get_wf_temp_data ( )

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

Since: Qorus 3.1.0

See also: ServiceApi::tryGetWfTempData()

◆ svc_try_render_template()

*hash<auto> OMQ::UserApi::Service::svc_try_render_template	(	string	name,
		hash< auto >	ctx
	)

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

Example:: *hash<auto> h = svc_try_render_template(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)

Since: Qorus 3.0.0

Note: prior to Qorus 3.0.2 this function was known as try_render_template(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also

◆ svc_ui_extension_register() [1/2]

OMQ::UserApi::Service::svc_ui_extension_register ( OMQ::QorusExtensionHandler handler )

registers the service as an extension of the system UI

Example:: svc_ui_extension_register(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 svc_ui_extension_register(handler, url_name) variant of this function to ensure usage of deterministic URL.

Since: Qorus 3.0.0

Note: prior to Qorus 3.0.2 this function was known as ui_extension_register(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::uiExtensionRegister()

◆ svc_ui_extension_register() [2/2]

OMQ::UserApi::Service::svc_ui_extension_register	(	OMQ::QorusExtensionHandler	handler,
		string	url_name
	)

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

Example:: svc_ui_extension_register(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>

Since: Qorus 3.1.1.p3

See also: ServiceApi::uiExtensionRegister()

◆ svc_wait_for_events()

hash<auto> OMQ::UserApi::Service::svc_wait_for_events	(	softint	min_id = `1`,
		timeout	timeout_ms = `0`
	)

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 function returns immediately

Returns

a hash with the following keys:

lastid: the last event ID at the time the function 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

Since: Qorus 2.0.2

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
prior to Qorus 3.0.2 this function was known as wait_for_events(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::waitForEvents()

◆ svc_wait_for_events_and()

hash<auto> OMQ::UserApi::Service::svc_wait_for_events_and	(	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

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 function 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 function 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

Since: Qorus 2.0.2

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
prior to Qorus 3.0.2 this function was known as wait_for_events_and(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::waitForEventsAnd()

◆ svc_wait_for_events_or()

hash<auto> OMQ::UserApi::Service::svc_wait_for_events_or	(	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

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 function 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 function 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

Since: Qorus 2.0.2

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
prior to Qorus 3.0.2 this function was known as wait_for_events_or(), and is still imported with this old name without the "svc_" prefix for backwards compatibility

See also: ServiceApi::waitForEventsOr()

◆ test_authorization()

deprecated bool OMQ::UserApi::Service::test_authorization ( )

Deprecated:: by svc_test_authorization()

◆ test_authorization_or()

deprecated bool OMQ::UserApi::Service::test_authorization_or ( )

Deprecated:: by svc_test_authorization_or()

◆ test_job_access() [1/2]

deprecated bool OMQ::UserApi::Service::test_job_access ( list ids )

Deprecated:: by svc_test_job_access()

◆ test_job_access() [2/2]

deprecated bool OMQ::UserApi::Service::test_job_access ( softint id )

Deprecated:: by svc_test_job_access()

◆ test_service_access() [1/2]

deprecated bool OMQ::UserApi::Service::test_service_access ( list ids )

Deprecated:: by svc_test_service_access()

◆ test_service_access() [2/2]

deprecated bool OMQ::UserApi::Service::test_service_access ( softint id )

Deprecated:: by svc_test_service_access()

◆ test_workflow_access() [1/2]

deprecated bool OMQ::UserApi::Service::test_workflow_access ( list ids )

Deprecated:: by svc_test_workflow_access()

◆ test_workflow_access() [2/2]

deprecated bool OMQ::UserApi::Service::test_workflow_access ( softint id )

Deprecated:: by svc_test_workflow_access()

◆ try_get_resource()

*hash OMQ::UserApi::Service::try_get_resource	(	string	name,
		hash	ctx,
		int	code = `200`,
		*hash	hdr
	)

Deprecated:: by svc_try_get_resource()

◆ try_get_resource_data()

*data OMQ::UserApi::Service::try_get_resource_data	(	string	name,
		*hash	ctx
	)

Deprecated:: by svc_try_get_resource_data()

◆ try_render_template()

*hash OMQ::UserApi::Service::try_render_template	(	string	name,
		hash	ctx
	)

Deprecated:: by svc_try_render_template()

◆ ui_extension_register()

OMQ::UserApi::Service::ui_extension_register ( OMQ::QorusExtensionHandler handler )

Deprecated:: by svc_ui_extension_register()

◆ wait_for_events()

deprecated hash OMQ::UserApi::Service::wait_for_events	(	softint	min_id = `1`,
		timeout	timeout_ms = `0`
	)

Deprecated:: by svc_wait_for_events()

◆ wait_for_events_and()

deprecated hash OMQ::UserApi::Service::wait_for_events_and	(	softint	min_id = `1`,
		any	filter,
		timeout	timeout_ms = `0`,
		any	or_not
	)

Deprecated:: by svc_wait_for_events_and()

◆ wait_for_events_or()

deprecated hash OMQ::UserApi::Service::wait_for_events_or	(	softint	min_id = `1`,
		any	filter,
		timeout	timeout_ms = `0`,
		any	and_not
	)

Deprecated:: by svc_wait_for_events_or()

Classes

Functions

Detailed Description

Function Documentation

◆ bind_ftp()

◆ bind_handler() [1/2]

◆ bind_handler() [2/2]

◆ bind_http()

◆ call_api_as_current_user()

◆ check_authorization()

◆ check_authorization_or()

◆ check_job_access() [1/2]

◆ check_job_access() [2/2]

◆ check_job_instance_access()

◆ check_queue_access()

◆ check_service_access() [1/2]

◆ check_service_access() [2/2]

◆ check_workflow_access() [1/2]

◆ check_workflow_access() [2/2]

◆ check_workflow_instance_access()

◆ get_active_jobs_as_current_user()

◆ get_call_context()

◆ get_job_access_hash()

◆ get_job_access_list()

◆ get_last_events()

◆ get_last_events_and()

◆ get_last_events_or()

◆ get_omq_option()

◆ get_resource()

◆ get_resource_data()

◆ get_resource_hash()

◆ get_resource_list()

◆ get_running_workflow_list_as_current_user()

◆ get_service_access_hash()

◆ get_service_access_list()

◆ get_service_info_as_current_user() [1/2]

◆ get_service_info_as_current_user() [2/2]

◆ get_template_hash()

◆ get_template_list()

◆ get_workflow_access_hash()

◆ get_workflow_access_list()

◆ getServiceInfo()

◆ getSoapCallContext()

◆ has_resource()

◆ has_template()

◆ registerSoapHandler()

◆ registerSoapService() [1/2]

◆ registerSoapService() [2/2]

◆ render_template()

◆ slog()

◆ startServiceThread()

◆ startServiceThreadArgs()

◆ svc_bind_ftp()

◆ svc_bind_handler() [1/2]

◆ svc_bind_handler() [2/2]

◆ svc_bind_http()

◆ svc_call_api_as_current_user()

◆ svc_check_authorization()

◆ svc_check_authorization_or()

◆ svc_check_job_access() [1/2]

◆ svc_check_job_access() [2/2]

◆ svc_check_job_instance_access()

◆ svc_check_mapper_access() [1/2]

◆ svc_check_mapper_access() [2/2]

◆ svc_check_queue_access()

◆ svc_check_service_access() [1/2]

◆ svc_check_service_access() [2/2]

◆ svc_check_vmap_access() [1/2]

◆ svc_check_vmap_access() [2/2]

◆ svc_check_workflow_access() [1/2]

◆ svc_check_workflow_access() [2/2]

◆ svc_check_workflow_instance_access()

◆ svc_get_active_jobs_as_current_user()

◆ svc_get_call_context()

◆ svc_get_call_context_string()

◆ svc_get_http_call_context()

◆ svc_get_job_access_hash()

◆ svc_get_job_access_list()

◆ svc_get_last_events()

◆ svc_get_last_events_and()