Qorus Integration Engine  3.0.4.p7
Functions
OMQ::UserApi::Service Namespace Reference

Qorus service API namespace. More...

Functions

 svc_check_authorization ()
 checks user authorization for all of roles 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 roles passed to the function; throws an exception if the user is not authorized More...
 
bool svc_test_authorization ()
 tests user authorization for all of roles 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 roles 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 $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 $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 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 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 $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 $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 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 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 $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 $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 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 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...
 
deprecated registerSoapService (any $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 (any $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 $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 svc_get_http_call_context ()
 returns a hash with HTTP call context information More...
 
hash svc_get_last_events (softint $count)
 returns the last system events More...
 
hash svc_get_last_events_or (softint $count, any $filter, any $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 svc_get_last_events_and (softint $count, any $filter, any $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 svc_wait_for_events (softint $min_id=1, timeout $timeout_ms=0)
 return available system events More...
 
hash svc_wait_for_events_or (softint $min_id=1, any $filter, timeout $timeout_ms=0, any $and_not)
 return system events that meet any of the given criteria and none of the optional "and not" criteria More...
 
hash svc_wait_for_events_and (softint $min_id=1, any $filter, timeout $timeout_ms=0, any $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 (any $func)
 starts a service thread; passes the remaining arguments to the function to the new thread More...
 
int svc_start_thread_args (any $func, any $args)
 starts a service thread; uses the second argument as the argument list to pass to the new thread More...
 
hash svc_get_service_info ()
 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 svc_bind_http (OMQ::AbstractServiceHttpHandler $handler)
 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 svc_get_call_context ()
 returns contextual information about the current call More...
 
any svc_call_api_as_current_user (string $call, softlist $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 svc_get_service_info_as_current_user (string $type, string $name)
 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 svc_get_service_info_as_current_user (softint $id)
 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 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 svc_get_active_jobs_as_current_user ()
 Returns information on all active jobs visible to the given user. More...
 
hash svc_get_resource (string $name, hash $ctx, int $code=200, *hash $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 svc_try_get_resource (string $name, hash $ctx, int $code=200, *hash $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 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 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 $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...
 
*data svc_try_get_resource_data (string $name, *hash $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 svc_render_template (string $name, hash $ctx)
 explicitly renders a template file resource given the template argument hash More...
 
*hash svc_try_render_template (string $name, hash $ctx)
 render a template file resource and returns the rendered template if the template exists, otherwise returns NOTHING More...
 
*hash 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 svc_get_template_list ()
 returns a list of the service's template file resources or NOTHING if the service has none More...
 
bool svc_has_template (string $name)
 returns True if the given service template file resource exists, False if not More...
 
 svc_ui_extension_register (OMQ::QorusExtensionHandler $handler)
 registers the service as an extension of the system UI More...
 
 svc_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 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 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 svc_register_soap_listener (hash $sh, softstring $bind, int $family=AF_UNSPEC, *HttpServer::AbstractAuthenticator $auth)
 starts a dedicated SOAP listener with the given and xxx 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...
 
deprecated slog ()
 
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

deprecated OMQ::UserApi::Service::bind_ftp ( AbstractFtpHandler  $handler)
Deprecated:
by svc_bind_ftp()
deprecated OMQ::UserApi::Service::bind_handler ( string  $name,
AbstractServiceHttpHandler  $handler 
)
Deprecated:
by svc_bind_handler()
deprecated OMQ::UserApi::Service::bind_handler ( string  $name,
AbstractHttpRequestHandler  $handler,
string  $url,
*softlist  $content_type,
*softlist  $special_headers 
)
Deprecated:
by svc_bind_handler()
deprecated list OMQ::UserApi::Service::bind_http ( AbstractServiceHttpHandler  $handler)
Deprecated:
by svc_bind_http()
deprecated any OMQ::UserApi::Service::call_api_as_current_user ( string  $call,
softlist  $args 
)
Deprecated:
by svc_call_api_as_current_user()
deprecated OMQ::UserApi::Service::check_authorization ( )
Deprecated:
by svc_check_authorization()
deprecated OMQ::UserApi::Service::check_authorization_or ( )
Deprecated:
by svc_check_authorization_or()
deprecated OMQ::UserApi::Service::check_job_access ( list  $ids)
Deprecated:
by svc_check_job_access()
deprecated OMQ::UserApi::Service::check_job_access ( softint  $id)
Deprecated:
by svc_check_job_access()
deprecated OMQ::UserApi::Service::check_job_instance_access ( softstring  $jiid)
Deprecated:
by svc_check_job_instance_access()
deprecated OMQ::UserApi::Service::check_queue_access ( softint  $queueid,
string  $key 
)
Deprecated:
by svc_check_queue_access()
deprecated OMQ::UserApi::Service::check_service_access ( list  $ids)
Deprecated:
by svc_check_service_access()
deprecated OMQ::UserApi::Service::check_service_access ( softint  $id)
Deprecated:
by svc_check_service_access()
deprecated OMQ::UserApi::Service::check_workflow_access ( list  $ids)
Deprecated:
by svc_check_workflow_access()
deprecated OMQ::UserApi::Service::check_workflow_access ( softint  $id)
Deprecated:
by svc_check_workflow_access()
deprecated OMQ::UserApi::Service::check_workflow_instance_access ( softstring  $wfiid)
Deprecated:
by svc_check_workflow_instance_access()
deprecated hash OMQ::UserApi::Service::get_active_jobs_as_current_user ( )
Deprecated:
by svc_get_active_jobs_as_current_user()
deprecated *hash OMQ::UserApi::Service::get_call_context ( )
Deprecated:
by svc_get_call_context()
deprecated *hash OMQ::UserApi::Service::get_job_access_hash ( )
Deprecated:
by svc_get_job_access_hash()
deprecated *list OMQ::UserApi::Service::get_job_access_list ( )
Deprecated:
by svc_get_job_access_list()
deprecated hash OMQ::UserApi::Service::get_last_events ( softint  $count)
Deprecated:
by svc_get_last_events()
deprecated hash OMQ::UserApi::Service::get_last_events_and ( softint  $count,
any  $filter,
any  $or_not 
)
Deprecated:
by svc_get_last_events_and()
deprecated hash OMQ::UserApi::Service::get_last_events_or ( softint  $count,
any  $filter,
any  $and_not 
)
Deprecated:
by svc_get_last_events_or()
deprecated any OMQ::UserApi::Service::get_omq_option ( )
Deprecated:
by get_option()
hash OMQ::UserApi::Service::get_resource ( string  $name,
hash  $ctx,
int  $code = 200,
*hash  $hdr 
)
Deprecated:
by get_resource()
data OMQ::UserApi::Service::get_resource_data ( string  $name,
*hash  $ctx 
)
Deprecated:
by svc_get_resource_data()
*hash OMQ::UserApi::Service::get_resource_hash ( )
Deprecated:
by svc_get_resource_hash()
list OMQ::UserApi::Service::get_resource_list ( )
Deprecated:
by svc_get_resource_list()
deprecated list OMQ::UserApi::Service::get_running_workflow_list_as_current_user ( string  $name,
*string  $ver 
)
Deprecated:
by svc_get_running_workflow_list_as_current_user()
deprecated *hash OMQ::UserApi::Service::get_service_access_hash ( )
Deprecated:
by svc_get_service_access_hash()
deprecated *list OMQ::UserApi::Service::get_service_access_list ( )
Deprecated:
by svc_get_service_access_list()
deprecated *hash OMQ::UserApi::Service::get_service_info_as_current_user ( string  $type,
string  $name 
)
Deprecated:
by svc_get_service_info_as_current_user()
deprecated *hash OMQ::UserApi::Service::get_service_info_as_current_user ( softint  $id)
Deprecated:
by svc_get_service_info_as_current_user()
*hash OMQ::UserApi::Service::get_template_hash ( )
Deprecated:
by svc_get_template_hash()
list OMQ::UserApi::Service::get_template_list ( )
Deprecated:
by svc_get_template_list()
deprecated *hash OMQ::UserApi::Service::get_workflow_access_hash ( )
Deprecated:
by svc_get_workflow_access_hash()
deprecated *list OMQ::UserApi::Service::get_workflow_access_list ( )
Deprecated:
by svc_get_workflow_access_list()
deprecated hash OMQ::UserApi::Service::getServiceInfo ( )
Deprecated:
by svc_get_service_info()
deprecated *hash OMQ::UserApi::Service::getSoapCallContext ( )
Deprecated:
by svc_get_http_call_context()
bool OMQ::UserApi::Service::has_resource ( string  $name)
Deprecated:
by svc_has_resource()
bool OMQ::UserApi::Service::has_template ( string  $name)
Deprecated:
by svc_has_template()
deprecated OMQ::UserApi::Service::registerSoapHandler ( hash  $h)
Deprecated:
by svc_register_soap_handler()
deprecated OMQ::UserApi::Service::registerSoapService ( any  $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
deprecated OMQ::UserApi::Service::registerSoapService ( any  $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
hash OMQ::UserApi::Service::render_template ( string  $name,
hash  $ctx 
)
Deprecated:
by svc_render_template()
deprecated OMQ::UserApi::Service::slog ( )
Deprecated:
by log()
deprecated int OMQ::UserApi::Service::startServiceThread ( any  $func)
Deprecated:
by svc_start_thread()
deprecated int OMQ::UserApi::Service::startServiceThreadArgs ( any  $func,
any  $args 
)
Deprecated:
by svc_start_thread_args()
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
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
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
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
list OMQ::UserApi::Service::svc_bind_http ( OMQ::AbstractServiceHttpHandler  $handler)

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
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
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
any OMQ::UserApi::Service::svc_call_api_as_current_user ( string  $call,
softlist  $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
See also
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
OMQ::UserApi::Service::svc_check_authorization ( )

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

If current user does not have all of the given roles, 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.

See also
svc_test_authorization()
Exceptions
AUTHORIZATION-ERRORno authentication information supplied or user does not have all required roles
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
OMQ::UserApi::Service::svc_check_authorization_or ( )

checks user authorization for at least one of list of roles 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 roles, 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.

See also
svc_test_authorization_or()
Exceptions
AUTHORIZATION-ERRORno authentication information supplied or user does not have any of the roles 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
OMQ::UserApi::Service::svc_check_job_access ( list  $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
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
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
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
OMQ::UserApi::Service::svc_check_service_access ( list  $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
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
OMQ::UserApi::Service::svc_check_workflow_access ( list  $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
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
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
hash 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)
  • [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
*hash 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)
    • 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
    • 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
*hash 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
*hash 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
*list 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
hash OMQ::UserApi::Service::svc_get_last_events ( softint  $count)

returns the last system events

Parameters
$countthe maximum number of 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
hash OMQ::UserApi::Service::svc_get_last_events_and ( softint  $count,
any  $filter,
any  $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
hash OMQ::UserApi::Service::svc_get_last_events_or ( softint  $count,
any  $filter,
any  $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
hash OMQ::UserApi::Service::svc_get_resource ( string  $name,
hash  $ctx,
int  $code = 200,
*hash  $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:
my 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
See also
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
data OMQ::UserApi::Service::svc_get_resource_data ( string  $name,
*hash  $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:
my 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
See also
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
*hash 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:
my *hash $h = svc_get_resource_hash();
Returns
a hash of the service's file resources (hash keys are service file resource names) or NOTHING if the service has none
See also
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
list OMQ::UserApi::Service::svc_get_resource_list ( )

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

Example:
my list $l = svc_get_resource_list();
Returns
a list of the service's file resources or NOTHING if the service has none
See also
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
list 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
*hash 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
*list 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
hash OMQ::UserApi::Service::svc_get_service_info ( )

returns information about the current service

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 struct 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
*hash OMQ::UserApi::Service::svc_get_service_info_as_current_user ( string  $type,
string  $name 
)

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:

$omqservice.system.omqmap.lookupserviceinfo(<type>, <name>)
Parameters
$typethe type of service (either "system" or "user"; case is ignored)
$namethe name of the system service to query
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 of 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
*hash OMQ::UserApi::Service::svc_get_service_info_as_current_user ( softint  $id)

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:

$omqservice.system.omqmap.lookupserviceinfo(<type>, <name>)
Parameters
$idthe serviceid of the service
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 of 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
*hash 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:
my *hash $h = svc_get_template_hash();
Returns
a hash of the service's template file resources (hash keys are service template resource names) or NOTHING if the service has none
See also
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
list 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:
my list $l = svc_get_template_list();
Returns
a list of the service's template file resources or NOTHING if the service has none
See also
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
*hash 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
*list 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
bool OMQ::UserApi::Service::svc_has_resource ( string  $name)

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

Example:
my bool $b = svc_has_resource($name);
Returns
True if the given service file resource exists, False if not
See also
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
bool OMQ::UserApi::Service::svc_has_template ( string  $name)

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

Example:
my bool $b = svc_has_template($name);
Returns
True if the given service template file resource exists, False if not
See also
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
OMQ::UserApi::Service::svc_persistence_register ( code  $factory)

registers the service as providing persistent/dedicated HTTP connection support

Example:
svc_persistence_register($code);
Parameters
factorya closure or call reference that returns a persistence tracking object derived from OMQ::AbstractPersistentDataHelper, takes the following args: hash cx, *hash ah
Exceptions
SERVICE-PERSISTENCE-ERRORa persistence handler has already been registered
Since
Qorus 3.0.2
OMQ::UserApi::Service::svc_persistence_thread_terminate ( )

terminates a persistent connection in the current thread

Example:
svc_persistence_thread_terminate();
Exceptions
SERVICE-PERSISTENCE-ERRORthe current thread is not in a persistent connection
Since
Qorus 3.0.2
OMQ::UserApi::Service::svc_register_soap_handler ( hash  $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
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
list OMQ::UserApi::Service::svc_register_soap_listener ( hash  $sh,
softstring  $bind,
int  $family = AF_UNSPEC,
*HttpServer::AbstractAuthenticator  $auth 
)

starts a dedicated SOAP listener with the given and xxx 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
$sha 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
  • 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
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")
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
hash OMQ::UserApi::Service::svc_render_template ( string  $name,
hash  $ctx 
)

explicitly renders a template file resource given the template argument hash

Example:
my string $html = 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
See also
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
list 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 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")
See also
Since
Qorus 3.0.4.p2
int OMQ::UserApi::Service::svc_start_thread ( any  $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 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
int OMQ::UserApi::Service::svc_start_thread_args ( any  $func,
any  $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 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
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
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

See also
Since
Qorus 3.0.4.p2
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
methodsthe HTTP method acceptable for this stream; when acquired with other methods, a 405 Method Not Allowed response is returned
factorya closure or call reference that returns an AbstractRestStreamRequestHandler object, takes the following args: hash cx, *hash ah
desca description for the stream
Since
Qorus 3.0.2
bool OMQ::UserApi::Service::svc_test_authorization ( )

tests user authorization for all of roles 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 roles, returns False, otherwise True.
See also
svc_check_authorization()
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
bool OMQ::UserApi::Service::svc_test_authorization_or ( )

tests user authorization for at least one of the roles 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 roles, returns False, otherwise True.
See also
svc_check_authorization_or()
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
bool OMQ::UserApi::Service::svc_test_job_access ( list  $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
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
bool OMQ::UserApi::Service::svc_test_service_access ( list  $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
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
bool OMQ::UserApi::Service::svc_test_workflow_access ( list  $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
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
*hash OMQ::UserApi::Service::svc_try_get_resource ( string  $name,
hash  $ctx,
int  $code = 200,
*hash  $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:
my *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)
See also
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
*data OMQ::UserApi::Service::svc_try_get_resource_data ( string  $name,
*hash  $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:
my *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
See also
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
*hash OMQ::UserApi::Service::svc_try_render_template ( string  $name,
hash  $ctx 
)

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

Example:
my *hash $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)
See also
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
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
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
hash 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
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
hash OMQ::UserApi::Service::svc_wait_for_events_and ( softint  $min_id = 1,
any  $filter,
timeout  $timeout_ms = 0,
any  $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
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
hash OMQ::UserApi::Service::svc_wait_for_events_or ( softint  $min_id = 1,
any  $filter,
timeout  $timeout_ms = 0,
any  $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
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
deprecated bool OMQ::UserApi::Service::test_authorization ( )
Deprecated:
by svc_test_authorization()
deprecated bool OMQ::UserApi::Service::test_authorization_or ( )
Deprecated:
by svc_test_authorization_or()
deprecated bool OMQ::UserApi::Service::test_job_access ( list  $ids)
Deprecated:
by svc_test_job_access()
deprecated bool OMQ::UserApi::Service::test_job_access ( softint  $id)
Deprecated:
by svc_test_job_access()
deprecated bool OMQ::UserApi::Service::test_service_access ( list  $ids)
Deprecated:
by svc_test_service_access()
deprecated bool OMQ::UserApi::Service::test_service_access ( softint  $id)
Deprecated:
by svc_test_service_access()
deprecated bool OMQ::UserApi::Service::test_workflow_access ( list  $ids)
Deprecated:
by svc_test_workflow_access()
deprecated bool OMQ::UserApi::Service::test_workflow_access ( softint  $id)
Deprecated:
by svc_test_workflow_access()
*hash OMQ::UserApi::Service::try_get_resource ( string  $name,
hash  $ctx,
int  $code = 200,
*hash  $hdr 
)
Deprecated:
by svc_try_get_resource()
*data OMQ::UserApi::Service::try_get_resource_data ( string  $name,
*hash  $ctx 
)
Deprecated:
by svc_try_get_resource_data()
*hash OMQ::UserApi::Service::try_render_template ( string  $name,
hash  $ctx 
)
Deprecated:
by svc_try_render_template()
OMQ::UserApi::Service::ui_extension_register ( OMQ::QorusExtensionHandler  $handler)
Deprecated:
by ui_extension_register()
deprecated hash OMQ::UserApi::Service::wait_for_events ( softint  $min_id = 1,
timeout  $timeout_ms = 0 
)
Deprecated:
by svc_wait_for_events()
deprecated hash OMQ::UserApi::Service::wait_for_events_and ( softint  $min_id = 1,
any  $filter,
timeout  $timeout_ms = 0,
any  $or_not 
)
Deprecated:
by svc_wait_for_events_and()
deprecated hash OMQ::UserApi::Service::wait_for_events_or ( softint  $min_id = 1,
any  $filter,
timeout  $timeout_ms = 0,
any  $and_not 
)
Deprecated:
by svc_wait_for_events_or()