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

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< stringsvc_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< stringsvc_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< stringsvc_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< stringsvc_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)

◆ bind_handler() [1/2]

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

◆ bind_handler() [2/2]

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

◆ bind_http()

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

◆ call_api_as_current_user()

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

◆ check_authorization()

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

◆ check_authorization_or()

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

◆ check_job_access() [1/2]

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

◆ check_job_access() [2/2]

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

◆ check_job_instance_access()

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

◆ check_queue_access()

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

◆ check_service_access() [1/2]

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

◆ check_service_access() [2/2]

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

◆ check_workflow_access() [1/2]

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

◆ check_workflow_access() [2/2]

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

◆ check_workflow_instance_access()

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

◆ get_active_jobs_as_current_user()

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

◆ get_call_context()

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

◆ get_job_access_hash()

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

◆ get_job_access_list()

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

◆ get_last_events()

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

◆ get_last_events_and()

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

◆ get_last_events_or()

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

◆ get_omq_option()

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

◆ get_resource()

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

◆ get_resource_data()

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

◆ get_resource_hash()

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

◆ get_resource_list()

list OMQ::UserApi::Service::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 
)

◆ get_service_access_hash()

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

◆ get_service_access_list()

deprecated *list OMQ::UserApi::Service::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 
)

◆ get_service_info_as_current_user() [2/2]

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

◆ get_template_hash()

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

◆ get_template_list()

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

◆ get_workflow_access_hash()

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

◆ get_workflow_access_list()

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

◆ getServiceInfo()

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

◆ getSoapCallContext()

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

◆ has_resource()

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

◆ has_template()

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

◆ registerSoapHandler()

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

◆ 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 
)

◆ slog()

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

◆ startServiceThread()

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

◆ startServiceThreadArgs()

deprecated int OMQ::UserApi::Service::startServiceThreadArgs ( any  func,
any  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
handlerdefines parameters and callback routines for the system FTP server
Exceptions
SERVICE-FTP-ERRORno 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
namethe name of the service resource for the dedicated service listener
handlerdefines parameters and callback routines for the system HTTP server
Exceptions
BIND-HANDLER-ERRORcannot bind a handler with listeners to an existing HTTP service handler
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
namethe name of the service resource for the dedicated service listener
handlerdefines parameters and callback routines for the system HTTP server
urla regex for the URL to service
content_typean optional list of Content-Types to match
special_headersan optional list of special headers to match
isregexdefines if url is a regular expression or not
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
handlerdefines parameters and callback routines for the system HTTP server
optsadditional options for the HTTP handler binding process
Returns
a list of service resource names bound to the service; multiple resource names are returned only if there are multiple listeners defined in the handler argument
Exceptions
SERVICE-HTTP-ERRORerror starting listener, error binding URL
LISTENER-SHARING-NOT-ALLOWED-ERRORthere is already a listener with same bind value and either the service that started it does not allow sharing of it, or the allow_listener_sharing option is set to False
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
callthe full api method name (ex: "omq.system.exec-synchronous-exiting"); see Network System API for a full list
argsany arguments to the method; if multiple argument should be passed to the method, use a list of arguments here
Returns
the return value of the method
Exceptions
UNKNOWN-API-CALLinvalid API method
INVALID-INTERNAL-API-CALLAPI may not be called internally (ex: omq.system.shutdown-wait())
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-ERRORno 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-ERRORno 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
idsa list of jobids to check
Since
Qorus 2.6.0
Exceptions
JOB-ACCESS-ERRORthe 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
idthe jobid to check
Since
Qorus 2.6.1
Exceptions
JOB-ACCESS-ERRORthe 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
jiidthe job_instanceid to check
Exceptions
JOB-ACCESS-ERRORthe 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
idsa list of mapperids to check
Since
Qorus 3.1
Exceptions
MAPPER-ACCESS-ERRORthe 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
idthe mapperid to check
Since
Qorus 3.1
Exceptions
MAPPER-ACCESS-ERRORthe 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
queueidthe queue ID to check
keythe key value in queue given by the first argument to check
Since
Qorus 2.6.0
Exceptions
WORKFLOW-ACCESS-ERRORno 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
idsa list of serviceids to check
Since
Qorus 2.6.0
Exceptions
SERVICE-ACCESS-ERRORno 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
idthe serviceid to check
Since
Qorus 2.6.0
Exceptions
SERVICE-ACCESS-ERRORno 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
idsa list of value map ids to check
Since
Qorus 3.1
Exceptions
VMAP-ACCESS-ERRORthe 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
idthe value map id to check
Since
Qorus 3.1
Exceptions
VMAP-ACCESS-ERRORthe 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
idsa list of workflowids to check
Since
Qorus 2.6.0
Exceptions
WORKFLOW-ACCESS-ERRORthe 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
idthe workflowid to check
Since
Qorus 2.6.0
Exceptions
WORKFLOW-ACCESS-ERRORthe 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
wfiidthe workflow_instanceid to check
Since
Qorus 2.6.0
Exceptions
WORKFLOW-ACCESS-ERRORno 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

◆ 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:
Parameters
cxoptional 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
countthe 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-ERRORthis 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
countthe maximum number of events to return; if this argument is 0, then the size of the returned list is only limited by the number of events in the system that match the filter(s) passed.
filterthis argument is the criteria list for "logical and" comparisons to be applied to the events. If an event matches all of the criteria hashes in the first argument, then it is included in the resulting list. To match a criteria hash in the second argument with this API call, any of the criteria keys in a single hash can match, therefore, to get pure "logical and" behavior, the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
or_notthis argument is an optional criteria list that can augment the list returned with negative matches. If this argument is present and any element in the system’s event list does not match any of the criteria hashes in the third argument, then it is also included in the returned event list. Note that the third argument, if present, is processed with inverted logic compared to the second argument; for a single criteria hash to match, all of the criteria given as hash keys in the criteria hash must match, therefore, to get pure inverted "logical or" logic, the caller must specify only one hash key per hash in the list making up the third argument; see Event Filter Criteria for a description of each criteria hash
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the 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-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned
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
countthe maximum number of events to return; if this argument is 0, then the size of the returned list is only limited by the number of events in the system that match the filter(s) passed.
filterthis argument gives the criteria list for "logical or" comparisons to be applied to the events. If an event matches any of the criteria hashes in the first argument, then it is included in the resulting list, subject to processing by the optional third argument. To match a criteria hash in the second argument with this API call, all of the criteria keys in each hash must match, therefore, to get pure "logical or" behavior the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
and_notthis argument is an optional criteria list allowing the resulting event list to be filtered; if any event selected by the second argument matches all criteria hashes in the criteria hashes passed as the third argument, then it is filtered out of the resulting list. Note that the third argument, if present, is processed with inverted logic compared to the second argument; for a criteria hash to match, any of the criteria given as hash keys in a criteria hash can match, however, all criteria hashes must match for the filter to operate. Therefore, to get pure "logical and" filtering the caller must specify only one hash key per hash in the list making up the third argument; see Event Filter Criteria for a description of each criteria hash
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the 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-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned
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
namethe name of the resource
ctxthe argument hash to the template code
codethe HTTP response code for the response, if not present then 200 "OK" is assumed
hdrany optional headers for the response (the "Content-Type" header is set from the templates "Content-Type" value automatically)
Returns
a hash with the following keys:
  • code: the HTTP response code corresponding to the code argument
  • body: the rendered template or file resource
  • hdr: a hash of headers corresponding to the hdr argument plus the "Content-Type" key set from the template's "Content-Type" value)
Exceptions
SERVICE-FILE-RESOURCE-ERRORthe given service file resource does not exist
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
namethe name of the file resource
ctxan optional argument hash used if rendering a template resource
Returns
the given text or binary file resource as its native type; if a template exists, then the template is rendered and returned
Exceptions
SERVICE-FILE-RESOURCE-ERRORthe given service file resource does not exist
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:
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:
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
namethe name of the file resource representing the WSDL source
ctxan optional argument hash used if rendering a template resource
Returns
the given file resource as a WSDL::WebService object; any XSD imports are resolved as service resources; if a template exists, then the template is rendered and returned
Exceptions
SERVICE-FILE-RESOURCE-ERRORthe given service file resource does not exist
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
Exceptions
WORKFLOW-ACCESS-ERRORthe 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
cxoptional thread context hash from HTTP handler if available
Returns
a hash with the following keys:
  • type: the service type ("user" or "system")
  • name: the name of the service
  • version: the version of the service
  • desc: the description of the service
  • serviceid: the ID of the service, corresponding to SERVICES.SERVICEID in the database
  • status: either OMQ::SSRunning (if there are running threads) or OMQ::SSLoaded
  • threads: the number of currently running threads
  • autostart: the autostart flag
  • loaded: the date/time the service was loaded/started
  • methods: a list of hashes with name and desc keys for each method
  • method: the name of the current method being called
  • resources: a hash of resources attached to the service (may be NOTHING); each hash key is the unique resource name, and the value of each key is a hash with the following keys:
  • type: a string giving the resource type name (ie "HttpGlobalHandler", "HttpListener", "FtpListener", etc)
  • desc: a hashdecl description of the resource
  • info: a hash with additional, free-form information about the resource
  • groups: a list of zero or more strings giving group names the service is a member of
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
typethe type of service (either "system" or "user"; case is ignored)
namethe name of the system service to query
cxoptional thread context hash from HTTP handler if available
Returns
a hash of service information or NOTHING if the service is not loaded; the hash will have the following structure:
  • type: either "system" or "user" corresponding to the argument
  • name: the name of the service
  • version: version of the service
  • desc: description of the service
  • serviceid: service ID
  • status: OMQ::SSRunning or OMQ::SSLoaded
  • threads: number of running threads in the service
  • autostart: True or False if the autostart flag is set
  • loaded: date/time the service was loaded
  • methods: list of hashes for each method with name and desc keys
Exceptions
SERVICE-ACCESS-ERRORthe current user does not have the right to access the given service
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
idthe serviceid of the service
cxoptional thread context hash from HTTP handler if available
Returns
a hash of service information or NOTHING if the service is not loaded; the hash will have the following structure:
  • type: either "system" or "user" corresponding to the argument
  • name: the name of the service
  • version: version of the service
  • desc: description of the service
  • serviceid: service ID
  • status: OMQ::SSRunning or OMQ::SSLoaded
  • threads: number of running threads in the service
  • autostart: True or False if the autostart flag is set
  • loaded: date/time the service was loaded
  • methods: list of hashes for each method with name and desc keys
Exceptions
SERVICE-ACCESS-ERRORthe current user does not have the right to access the given service
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:
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:
Parameters
factorya closure or call reference that returns a persistence tracking object derived from OMQ::AbstractPersistentDataHelper, takes the following args: hash<auto> cx, *hash<auto> ah
Exceptions
SERVICE-PERSISTENCE-ERRORa persistence handler has already been registered
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:
Exceptions
SERVICE-PERSISTENCE-ERRORthe 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
ha hash with the following keys (only wsdl or wsdl_file is required):
  • wsdl, wsdl_file, or wsdl_resource: a URL to the WSDL, the WSDL string (XSD), a WebService object, or a file resource name giving the WSDL file
  • service: a string giving the name of the SOAP service to map to this service; this key is only necessary to set if the WSDL defines multiple SOAP services
  • uri_path: an optional string giving an optional URI path to use when binding the SOAP service
Exceptions
REGISTER-SOAP-HANDLER-ERRORmissing wsdl or wsdl_file key in argument hash; cannot find service; multiple services defined by WSDL but no service key given in argument hash
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
sha hash with the following keys (only wsdl, wsdl_file, or wsdl_resource is required)):
  • wsdl, wsdl_file, or wsdl_resource: a URL to the WSDL, the WSDL string (XSD), a WebService object, or a file resource name giving the WSDL file
  • service: a string giving the name of the SOAP service to map to this service; this key is only necessary to set if the WSDL defines multiple SOAP services
  • cert_path: (optional) a path to an X509 certificate for HTTPS listeners
  • key_path: (optional) a path to a private key file for an X509 certificate for HTTPS listeners
  • key_password: (optional) an optional string giving the password for the private key (PEM format only)
  • cert: (optional) a Qore::SSLCertificate object for HTTPS listeners
  • key: (optional) a Qore::SSLPrivateKey object for HTTPS listeners
bindthe bind address of the new listener; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given
familyone of the following network family constants:
  • AF_INET: for binding an IPv4 socket
  • AF_INET6: for binding an IPv6 socket
  • AF_UNSPEC: for binding a socket with any available address family
authif NOTHING then the system authenticator is used, otherwise an authenticator object for the listener; to authenticate all requests, use an object of class PermissiveAuthenticator
optsadditional options for the HTTP handler binding process
Returns
a list of resource names for the HTTP listener resources added to the service
Exceptions
REGISTER-SOAP-LISTENER-ERRORmissing wsdl or wsdl_file key in argument hash; cannot find service; multiple services defined by WSDL but no service key given in argument hash
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
sla list of hashes with the following keys (only wsdl, wsdl_file, or wsdl_resource is required):
  • wsdl, wsdl_file, or wsdl_resource: a URL to the WSDL, the WSDL string (XSD), a WebService object, or a file resource name giving the WSDL file
  • service: a string giving the name of the SOAP service to map to this service; this key is only necessary to set if the WSDL defines multiple SOAP services
bindthe bind address of the new listener; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given
lhan optional hash of listener info for HTTPS listeners
  • cert_path: (optional) a path to an X509 certificate for HTTPS listeners
  • key_path: (optional) a path to a private key file for an X509 certificate for HTTPS listeners
  • key_password: (optional) an optional string giving the password for the private key (PEM format only)
  • cert: (optional) a Qore::SSLCertificate object for HTTPS listeners
  • key: (optional) a Qore::SSLPrivateKey object for HTTPS listeners
familyone of the following network family constants:
  • AF_INET: for binding an IPv4 socket
  • AF_INET6: for binding an IPv6 socket
  • AF_UNSPEC: for binding a socket with any available address family
authif NOTHING then the system authenticator is used, otherwise an authenticator object for the listener; to authenticate all requests, use an object of class PermissiveAuthenticator
optsadditional options for the HTTP handler binding process
Returns
a list of resource names for the HTTP listener resources added to the service
Exceptions
REGISTER-SOAP-LISTENER-ERRORmissing wsdl or wsdl_file key in argument hash; cannot find service; multiple services defined by WSDL but no service key given in argument hash
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
namethe template file resource name
ctxthe argument hash to the template code
Returns
a hash with the following keys:
  • code: the HTTP response code corresponding to the code argument
  • body: the rendered template
  • hdr: a hash of headers corresponding to the hdr argument plus the "Content-Type" key set from the template's "Content-Type" value)
Exceptions
TEMPLATE-ERRORthe named template does not exist
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
datathe 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
bindthe bind address of the new listener; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given
cert_paththe file name of the X.509 certificate in PEM format (only for HTTPS listeners)
key_paththe file name of the private key for the X.509 certificate in PEM format (only for HTTPS listeners)
key_passwordthe optional password for the private key
namean optional name prefix for the listener; the final listener name will have the listener id appended to it and will be returned in the "name" key in each hash element in the return value for each listener started
familyone of the following network family constants:
  • AF_INET: for binding an IPv4 socket
  • AF_INET6: for binding an IPv6 socket
  • AF_UNSPEC: for binding a socket with any available address family
Returns
a list of hashes for each listener started, each hash having the following keys (note that for UNIX domain socket listeners the hostname, hostname_desc, and port keys will not be present):
  • hostname: the hostname of the interface
  • hostname_desc: a descriptive string for the hostname including the address family (ex: "ipv6[localhost]")
  • address: the address of the listener (i.e. "192.168.30.4", etc)
  • address_desc: a descriptive string for the hostname including the address family (ex: "ipv6[::1]")
  • port: the port number
  • family: an integer giving the address family (AF_INET, AF_INET6, AF_UNIX, etc)
  • familystr: a string describing the address family (ex: "ipv6")
  • proto: either "http" or "https"
  • id: the Qorus ID of the listener
  • bind: a string giving the bind address used (ex: "127.0.0.1:8001")
Note
listeners started with this API will be served by global Qorus HTTP handlers; they will not be added as service-specific listeners
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
functhe 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-ERRORthe 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
functhe function to call; may be a string giving a function name (string), a call reference, or a closure
argsthe arguments for the function to start in the separate thread
Returns
the TID of the new thread
Exceptions
START-SERVICE-THREAD-ERRORthe service has no "stop()" method or too many threads are already active in this service (see qorus.max-service-threads)
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
namethe name of the stream handler
methodthe HTTP method acceptable for this stream; when acquired with other methods, a 405 Method Not Allowed response is returned
factorya closure or call reference that returns an AbstractRestStreamRequestHandler object, takes the following args: hash<auto> cx, *hash<auto> ah
desca 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
idsa 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
idthe 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
idsa 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
idthe 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
idsa list of serviceids to check
Since
Qorus 2.6.0
Exceptions
SERVICE-ACCESS-ERRORno 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
idthe 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
idsa 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
idthe 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
idsa 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
idthe 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
namethe name of the resource
ctxthe argument hash to the template code
codethe HTTP response code for the response, if not present then 200 "OK" is assumed
hdrany optional headers for the response (the "Content-Type" header is set from the templates "Content-Type" value automatically)
Returns
NOTHING if the resource does not exist or a hash with the following keys:
  • code: the HTTP response code corresponding to the code argument
  • body: the rendered template or file resource
  • hdr: a hash of headers corresponding to the hdr argument plus the "Content-Type" key set from the template's "Content-Type" value)
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
namethe name of the resource
ctxan optional argument hash to the template code
Returns
NOTHING if the file resource does not exist or the given text or binary file resource as its native type; if a template exists, then the template is rendered and returned
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
namethe template file resource name
ctxthe argument hash to the template code
Returns
NOTHING if the template does not exist or a hash with the following keys:
  • code: the HTTP response code corresponding to the code argument
  • body: the rendered template
  • hdr: a hash of headers corresponding to the hdr argument plus the "Content-Type" key set from the template's "Content-Type" value)
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
handlerthe request handler for the requests to the extension, must be derived from OMQ::QorusExtensionHandler

The registered extension will be available from:

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

The system resource id value is assigned by Qorus itself, it is not predictable. Also it can vary accross various instalations. You can use 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
handlerthe request handler for the requests to the extension, must be derived from OMQ::QorusExtensionHandler
url_namecustom name used in public URL

The registered extension will be available from:

  • default Qorus UI, "Extensions" section
  • directly in URL http(s)://<hostname>:<port>/UIExtension/<url_name>
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_idthe minimum event ID to return; no event wil be returned that has an event ID less than this; the first event ID is always 1 (if min_id <= 1 then all events are returned that meet the given criteria)
timeout_msoptional timeout waiting for events; if not present; the 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-ERRORthis 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_idthe minimum event ID to return; no event wil be returned that has an event ID less than this; the first event ID is always 1 (if min_id <= 1 then all events are returned that meet the given criteria)
filterthis argument is the criteria list for "logical and" comparisons to be applied to the events. If an event matches all of the criteria hashes in the first argument, then it is included in the resulting list. To match a criteria hash in the second argument with this API call, any of the criteria keys in a single hash can match, therefore, to get pure "logical and" behavior, the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
timeout_msoptional timeout waiting for events; if not present or 0; the function returns immediately
or_notthis argument is an optional criteria list that can augment the list returned with negative matches. If this argument is present and any element in the system’s event list does not match any of the criteria hashes in the third argument, then it is also included in the returned event list. Note that the fourth argument, if present, is processed with inverted logic compared to the second argument; for a single criteria hash to match, all of the criteria given as hash keys in the criteria hash must match, therefore, to get pure inverted "logical or" logic, the caller must specify only one hash key per hash in the list making up the fourth argument; see Event Filter Criteria for a description of each criteria hash
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the 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-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned
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_idthe minimum event ID to return; no event wil be returned that has an event ID less than this; the first event ID is always 1 (if min_id <= 1 then all events are returned that meet the given criteria)
filterthis argument is the criteria list for "logical or" comparisons to be applied to the events. If a system event matches any of the criteria hashes in the first argument, then it is included in the resulting list, subject to processing by the optional fourth argument. To match a criteria hash in the second argument with this API call, all of the criteria keys in each hash must match, therefore, to get pure "logical or" behavior the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
timeout_msoptional timeout waiting for events; if not present or 0; the function returns immediately
and_notthis argument is an optional criteria list allowing the resulting event list to be filtered; if any event selected by the second argument matches all criteria hashes in the criteria hashes passed as the third argument, then it is filtered out of the resulting list. Note that the fourth argument, if present, is processed with inverted logic compared to the second argument; for a criteria hash to match, any of the criteria given as hash keys in a criteria hash can match, however, all criteria hashes must match for the filter to operate. Therefore, to get pure "logical and" filtering the caller must specify only one hash key per hash in the list making up the fourth argument; see Event Filter Criteria for a description of each criteria hash
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the 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-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned
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 ( )

◆ test_authorization_or()

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

◆ test_job_access() [1/2]

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

◆ test_job_access() [2/2]

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

◆ test_service_access() [1/2]

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

◆ test_service_access() [2/2]

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

◆ test_workflow_access() [1/2]

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

◆ test_workflow_access() [2/2]

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

◆ try_get_resource()

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

◆ try_get_resource_data()

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

◆ try_render_template()

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

◆ ui_extension_register()

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

◆ wait_for_events()

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

◆ 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 
)

◆ 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 
)