CreateService API using VB

CreateService API declaration for VB 5/VB 6. Parameter description paraphrased from MSDN.

Private Declare Function CreateService Lib "advapi32.dll" Alias "CreateServiceA" ( _
   ByVal hSCManager As Long, _
   ByVal lpServiceName As String, _
   ByVal lpDisplayName As String, _
   ByVal dwDesiredAccess As Long, _
   ByVal dwServiceType As Long, _
   ByVal dwStartType As Long, _
   ByVal dwErrorControl As Long, _
   ByVal lpBinaryPathName As String, _
   ByVal lpLoadOrderGroup As String, _
   ByVal lpdwTagId As String, _
   ByVal lpDependencies As String, _
   ByVal lpServiceStartName As String, _
   ByVal lpPassword As String _
) As Long

Parameters:

hSCManager
[in] LONG handle to the service control manager database. This handle is returned by the OpenSCManager function and must have SC_MANAGER_CREATE_SERVICE access.

lpServiceName
[in] STRING that contains the name of the service to install. The maximum string length is 256 characters. The service control manager database preserves the case of the characters, but service name comparisons are always case insensitive. Forward-slash (/) and back-slash (\) are invalid service name characters.

lpDisplayName
[in] STRING that contains the display name to be used by user interface programs to identify the service. This string has a maximum length of 256 characters. The name is case-preserved in the service control manager. Display name comparisons are always case-insensitive.

dwDesiredAccess
[in] LONG value specifying the access to the service. Before granting the requested access, the system checks the access token of the calling process.

The STANDARD_RIGHTS_REQUIRED constant enables the following object access types.

ACCESS_SYSTEM_SECURITY
Enables calling of the QueryServiceObjectSecurity or SetServiceObjectSecurity function to access the SACL. The proper way to obtain this access is to enable the SE_SECURITY_NAME privilege in the caller's current access token, open the handle for ACCESS_SYSTEM_SECURITY access, and then disable the privilege.
DELETE
Enables calling of the DeleteService function to delete the service.
READ_CONTROL
Enables calling of the QueryServiceObjectSecurity function to query the security descriptor of the service object.
WRITE_DAC
Enables calling of the SetServiceObjectSecurity function to modify the DACL member of the service object's security descriptor.
WRITE_OWNER
Enables calling of the SetServiceObjectSecurity function to modify the Owner and Group members of the service object's security descriptor.

You can specify any or all of the following service object access types.

SERVICE_ALL_ACCESS
Includes STANDARD_RIGHTS_REQUIRED in addition to all of the access types listed in this table.
SERVICE_CHANGE_CONFIG
Enables calling of the ChangeServiceConfig function to change the service configuration.
SERVICE_ENUMERATE_DEPENDENTS
Enables calling of the EnumDependentServices function to enumerate all the services dependent on the service.
SERVICE_INTERROGATE
Enables calling of the ControlService function to ask the service to report its status immediately.
SERVICE_PAUSE_CONTINUE
Enables calling of the ControlService function to pause or continue the service.
SERVICE_QUERY_CONFIG
Enables calling of the QueryServiceConfig function to query the service configuration.
SERVICE_QUERY_STATUS
Enables calling of the QueryServiceStatus function to ask the service control manager about the status of the service.
SERVICE_START
Enables calling of the StartService function to start the service.
SERVICE_STOP
Enables calling of the ControlService function to stop the service.
SERVICE_USER_DEFINED_CONTROL
Enables calling of the ControlService function to specify a user-defined control code.

You can specify any of the following generic access types.

GENERIC_READ
Combines the following access types: STANDARD_RIGHTS_READ, SERVICE_QUERY_CONFIG, SERVICE_QUERY_STATUS, SERVICE_INTERROGATE, and SERVICE_ENUMERATE_DEPENDENTS.
GENERIC_WRITE
Combines the following access types: STANDARD_RIGHTS_WRITE and SERVICE_CHANGE_CONFIG.
GENERIC_EXECUTE
Combines the following access types: STANDARD_RIGHTS_EXECUTE, SERVICE_START, SERVICE_STOP, SERVICE_PAUSE_CONTINUE, and SERVICE_USER_DEFINED_CONTROL.

dwServiceType
[in] LONG value specifying the type of service. This parameter must be one of the following service types.

SERVICE_FILE_SYSTEM_DRIVER
File system driver service.
SERVICE_KERNEL_DRIVER
Driver service.
SERVICE_WIN32_OWN_PROCESS
Service that runs in its own process.
SERVICE_WIN32_SHARE_PROCESS
Service that shares a process with other services.

If you specify either SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS, and the service is running in the context of the LocalSystem account, you can also specify the following type.

SERVICE_INTERACTIVE_PROCESS
The service can interact with the desktop.

For more information, see Interactive Services.

dwStartType
[in] LONG value specifying when to start the service. This parameter must be one of the following start types.

SERVICE_AUTO_START
A service started automatically by the service control manager during system startup.
SERVICE_BOOT_START
A device driver started by the system loader. This value is valid only for driver services.
SERVICE_DEMAND_START
A service started by the service control manager when a process calls the StartService function.
SERVICE_DISABLED
A service that cannot be started. Attempts to start the service result in the error code ERROR_SERVICE_DISABLED.
SERVICE_SYSTEM_START
A device driver started by the IoInitSystem function. This value is valid only for driver services.

dwErrorControl
[in] LONG value specifying the severity of the error if this service fails to start during startup, and determines the action taken by the startup program if failure occurs. This parameter must be one of the following values.

SERVICE_ERROR_IGNORE
The startup program logs the error but continues the startup operation.
SERVICE_ERROR_NORMAL
The startup program logs the error and puts up a message box pop-up but continues the startup operation.
SERVICE_ERROR_SEVERE
The startup program logs the error. If the last-known-good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known-good configuration.
SERVICE_ERROR_CRITICAL
The startup program logs the error, if possible. If the last-known-good configuration is being started, the startup operation fails. Otherwise, the system is restarted with the last-known good configuration.

lpBinaryPathName
[in] STRING value that contains the fully qualified path to the service binary file. If the path contains a space, it must be quoted so that it is correctly interpreted. For example, "d:\my share\myservice.exe" should be specified as """d:\my share\myservice.exe""".

lpLoadOrderGroup
[in] STRING value that names the load ordering group of which this service is a member. Specify vbNullString if the service does not belong to a group.

lpdwTagId
[out] STRING variable that receives a tag value that is unique in the group specified in the lpLoadOrderGroup parameter. Specify vbNullString if you are not changing the existing tag.

You can use a tag for ordering service startup within a load ordering group by specifying a tag order vector in the GroupOrderList value of the following registry key:
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control
Tags are only evaluated for driver services that have SERVICE_BOOT_START or SERVICE_SYSTEM_START start types.

lpDependencies
[in] STRING array of null-separated names of services or load ordering groups that the system must start before this service. Specify vbNullString if the service has no dependencies. Dependency on a group means that this service can run if at least one member of the group is running after an attempt to start all members of the group.

You must prefix group names with SC_GROUP_IDENTIFIER so that they can be distinguished from a service name, because services and service groups share the same name space.

lpServiceStartName
[in] STRING value that specifies the name of the account under which the service should run. If the service type is SERVICE_WIN32_OWN_PROCESS, the account name must be in the form DomainName\UserName. The service process will be logged on as this user. If the account belongs to the built-in domain, you can specify .\UserName.

If this parameter is vbNullString, CreateService uses the LocalSystem account. If the service type specifies SERVICE_INTERACTIVE_PROCESS, the service must run in the LocalSystem account.

Windows XP: If this parameter is NT AUTHORITY\LocalService, CreateService uses the LocalService account. If the parameter is NT AUTHORITY\NetworkService, CreateService uses the NetworkService account.

Windows NT 4.0 and earlier: If the service type is SERVICE_WIN32_SHARE_PROCESS, you must specify the LocalSystem account. On Windows 2000 and later, a shared process can run as any user.

If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, the name is the driver object name that the system uses to load the device driver. Specify vbNullString if the driver is to use a default object name created by the I/O system.

lpPassword
[in] STRING value that contains the password to the account name specified by the lpServiceStartName parameter. Specify vbNullString if the account has no password or if the service runs in the LocalService, NetworkService, or LocalSystem account.

Passwords are ignored for driver services.

Return Values

If the function succeeds, the return value is a handle to the service.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

NOTE: Error 87 ("The parameter is incorrect.") is a common error encountered while calling this function. This is the result of an incorrect data type specified in the API declaration or an incorrect value (e.g. an empty string instead of vbNullString) being passed to the function.

The following error codes can be set by the service control manager. Other error codes can be set by the registry functions that are called by the service control manager.

ERROR_ACCESS_DENIED
The handle to the specified service control manager database does not have SC_MANAGER_CREATE_SERVICE access.
ERROR_CIRCULAR_DEPENDENCY
A circular service dependency was specified.
ERROR_DUP_NAME
The display name already exists in the service control manager database either as a service name or as another display name.
ERROR_INVALID_HANDLE
The handle to the specified service control manager database is invalid.
ERROR_INVALID_NAME
The specified service name is invalid.
ERROR_INVALID_PARAMETER
A parameter that was specified is invalid.
ERROR_INVALID_SERVICE_ACCOUNT
The user account name specified in the lpServiceStartName parameter does not exist.
ERROR_SERVICE_EXISTS
The specified service already exists in this database.

Remarks

The CreateService function creates a service object and installs it in the service control manager database by creating a key with the same name as the service under the following registry key:
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services
Information specified for this function is saved as values under this key. Setup programs and the service itself can create subkeys under this key for any service specific information.

The returned handle is only valid for the process that called CreateService. It can be closed by calling the CloseServiceHandle function.

If you are creating services that share a process, avoid calling functions with process-wide effects, such as ExitProcess. In addition, do not unload your service DLL.

Example Code

Creates a service running under the local Administrator account.

lngResult = CreateService( _
    lngHOpenSCM, _
    "My Service", _
    "My Service", _
    SERVICE_ALL_ACCESS, _
    SERVICE_WIN32_OWN_PROCESS, _
    SERVICE_AUTO_START, _
    SERVICE_ERROR_NORMAL, _
    "C:\MYSERVICE.EXE", _
    vbNullString, _
    vbNullString, _
    vbNullString, _
    ".\Administrator", _
    "Password")

Requirements

Windows NT/2000/XP: Included in Windows NT 3.1 and later.
Library: Use Advapi32.lib.
Unicode: Implemented as Unicode and ANSI versions.

Author: ASAK
Created: Sep 19 2005 (last modified Dec 7 2005)
Categories: VB APIs
TechByte #16

Warning: By visiting this site and/or by using any information contained herein, you agree to the Techbytes.ca terms of use.