SOFTINNOV
Home
NT-Services Support Library
Download Now!
Size :  16Kb
Level :  beta
Version :  1.0.3
Date :  5-Aug-2009

Description

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

Usage

Just add the following line to your application :

do %scm-scheme.r
See 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 API

All high-level functions are part of the globally defined NT-services object!.

nt-services/install [specs]

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 :

kernel-driver
file-system-driver
win32-own-process (default)
win32-share-process
start-type: word! no Service's start mode. Can be any of :

auto(default)
manual
disabled
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 :

ignore (default)
normal
severe
critical
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

nt-services/uninstall "name"

Suppress the service identified by name from the Service Control Manager list.

nt-services/start "name"

Starts the service identified by name and returns immediately. If the service is already running, or if something goes wrong, an error! is raised.

nt-services/stop "name"

Stops the service identified by name and returns immediately. If the service is already running, or if something goes wrong, an error! is raised.

nt-services/exists? "name"

Returns true if the service exists in the Service Control Manager database, else returns false.

nt-services/running? "name"

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 API

The following function provide a finer-grained access to services information (getting or setting) without having to dive in the port layer API.

read scm://
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 :
  • start
  • stop
  • pause
  • continue

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 API

The 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
SCM port API


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 :
  • start
  • stop
  • pause
  • continue

copy port
Returns a block! of all service's properties with values. It's a shorcut to :

get-modes port get-modes port 'all

query port
Returns a block! of service's runtime information such as :
  • state : can be any of the following words :
    • stopped
    • start-pending
    • stop-pending
    • running
    • continue-pending
    • pause-pending
    • paused
  • 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.

remove port
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.

History

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