This REBOL library offers the support for the Windows Services (also known as NT Services). It allows both accessing/controling services definition and providing a way to run REBOL encapped applications as Windows Services. This library wraps all the win32 services API inside a new scheme : SCM (Service Control Manager).
Main features :
- Run your REBOL application as a Windows Service
- No external dependencies to third-party products (like svrany.exe)
- Clean integration with REBOL using a scheme (scm://)
- Full control other any Windows Services : start, stop, install, uninstall, configure...
- Open-source : BSD license
- 3 levels of API :
- High-level API : high level wrapper functions, easy and direct usage
- Mid-level API : handy port meta-functions
- Low-level API : full access to the port API
Just add the following line to your application :
do %scm-scheme.rSee the provided %sample.r file for an example of running a REBOL application as a service.
The provided %service.dll library is only required when you need to run your application as a service (nt-services/run function). Full C source code is available in the archive.
High-level APIAll high-level functions are part of the globally defined NT-services object!.
Install a new service defined in specs block as word: value couples. List of allowed properties :
Property Type Mandatory? Description name: string! yes Keyword used to uniquely identify the new service command: string! yes Service's executable name with path and optional arguments title: string! yes Display name used in Service Control Manager comment: string! no Service description (displayed in Service Control Manager) type: word! no Type of service. Can be any of :
start-type: word! no Service's start mode. Can be any of :
interactive: logic! no yes : allow the service to interact with the user's desktop (e.g.: display a window). This mode doesn't survive to session logoff.
no : no interaction with user's desktop
error-control: word! no Level of error reporting to the system event manager. Can be any of :
user: string! no Login account to be used by the service at runtime. Default to "LocalSystem". User accounts are usually defined as "domain\login", but you can also use the ".\login" syntax. pass: string! no Password for the login account. Default to none
Suppress the service identified by name from the Service Control Manager list.
Starts the service identified by name and returns immediately. If the service is already running, or if something goes wrong, an error! is raised.
Stops the service identified by name and returns immediately. If the service is already running, or if something goes wrong, an error! is raised.
Returns true if the service exists in the Service Control Manager database, else returns false.
Returns true if the service is running, or about to run, else returns false.
nt-services/attach "name" /notify port-id [on-quit]
When your REBOL application is started as a Windows Service, this function is required to attach your REBOL application to the Service Control Manager. It have be called at the beginning of your application. An optional /notify refinement is provided to install a custom callback called when your application is stopped by the Service Control Manager, in order to give it a chance to do some cleanup before quitting. (Your application have to run in an event loop in order to receive the notification)
"name" have to match the name of the service's definition in the Service Control Manager database.
port-id indicates the UDP port number used to receive notification messages.
Mid-level APIThe following function provide a finer-grained access to services information (getting or setting) without having to dive in the port layer API.
Returns a block! of all defined services in the Service Control Manager database.read scm://name
Returns a block! of the service's properties (name: values couple).write scm:// [specs]
Create a new service defined by specs block. See the nt-services/install function documentation above.write scm://name [action]
Send the action command to the service port. Allowed commands are :get-modes scm://name 'property | [properties]
Returns for service name the value of 'property, or a block! of values for [properties]. Properties have to be in the list provided in nt-services/install function documentation (see above).set-modes scm://name [properties]
Sets for service name the list of name: value couples provided in properties. Properties have to be in the list provided in nt-services/install function documentation (see above).
Example:set-modes scm://test [comment: "This service is only for testing purpose"]
Low-level APIThe low-level API is divided in two kind of ports :
- SCM ports: global access to the Service Control Manager database
- Service ports: access to service-level properties
port: open scm://
Opens and returns a new port! value connected to the Service Control Manager.insert port [specs]
Create a new service defined by specs block. See the nt-services/install function documentation above.query | copy port
Returns a block! of all defined services in the Service Control Manager database.find port
Returns true if the service exists in the Service Control Manager database, else returns false.close port
Close an opened scm port.Service port API
port: open scm://name
Opens and returns a new port! value for the service name.insert port [action]
Send the action command to the service port. Allowed commands are :copy port
Returns a block! of all service's properties with values. It's a shorcut to :query port
get-modes port get-modes port 'all
Returns a block! of service's runtime information such as :remove port
- state : can be any of the following words :
- type : service's type as defined in the nt-services/install function documenation.
- accepted : block of accepted commands (see list in the 'insert function documentation)
- exit-code : integer! value giving the exit code value (if any) when the service exited.
- interactive : true if interaction with user's desktop allowed, otherwise false.
Suppresses the service in the Service Control Manager database.get-modes port 'property | [properties]
Returns for service port the value of 'property, or a block! of values for [properties]. Properties have to be in the list provided in nt-services/install function documentation (see above). The 'all value can be used as property value to obtain a list of all available properties.set-modes port [properties]
Sets for service port the list of name: value couples provided in properties. Properties have to be in the list provided in nt-services/install function documentation (see above).close port
Close an opened service port.
- v.1.0.3 - 5-Aug-2009
- Install function now checks for presence of 'title property. (Thanks to Titus Barik)
- v.1.0.2 - 9-Mar-2009
- Fixed a typo in 'running? function preventing it from returning the correct result.(Thanks to David for finding and reporting it).
v.1.0.1 - 23-Feb-2008
- In nt-service API, 'run function renamed to 'attach
- Function 'write can now be used on scm:// ports (replaces open/insert/close sequence)
- v.1.0.0 - 20-Jan-2008
- First public release.