CreateService info Overview Group

The CreateService function creates a service object and adds it to the specified service control manager database.

SC_HANDLE CreateService(

SC_HANDLE hSCManager,

// handle to service control manager database

LPCTSTR lpServiceName,

// pointer to name of service to start

LPCTSTR lpDisplayName,

// pointer to display name

DWORD dwDesiredAccess,

// type of access to service

DWORD dwServiceType,

// type of service

DWORD dwStartType,

// when to start service

DWORD dwErrorControl,

// severity if service fails to start

LPCTSTR lpBinaryPathName,

// pointer to name of binary file

LPCTSTR lpLoadOrderGroup,

// pointer to name of load ordering group

LPDWORD lpdwTagId,

// pointer to variable to get tag identifier

LPCTSTR lpDependencies,

// pointer to array of dependency names

LPCTSTR lpServiceStartName,

// pointer to account name of service

LPCTSTR lpPassword

// pointer to password for service account

);

Parameters

hSCManager

Identifies the service control manager database. This handle is returned by the OpenSCManager function and must have SC_MANAGER_CREATE_SERVICE access.

lpServiceName

Points to a null-terminated string that names 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

Points to a null-terminated string that is 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

Specifies 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 service object access types:

Standard rights

Description

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|WRITE_OWNER

Enables calling of the SetServiceObjectSecurity function to modify the security descriptor of the service object.

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

Access

Description

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 access

Service access

GENERIC_READ

Combines the following access types: STANDARD_RIGHTS_READ, SERVICE_QUERY_CONFIG, SERVICE_QUERY_STATUS, 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, SERVICE_INTERROGATE, and SERVICE_USER_DEFINED_CONTROL.

dwServiceType

A set of bit flags that specify the type of service. You must specify one of the following service types.

Value	Meaning
SERVICE_WIN32_OWN_PROCESS	Specifies a Win32-based service that runs in its own process.
SERVICE_WIN32_SHARE_PROCESS	Specifies a Win32-based service that shares a process with other services.
SERVICE_KERNEL_DRIVER	Specifies a driver service.
SERVICE_FILE_SYSTEM_DRIVER	Specifies a file system driver service.

If you specify either SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS, you can also specify the following flag.

Value

Meaning

SERVICE_INTERACTIVE_PROCESS

Enables a Win32-based service process to interact with the desktop.

dwStartType

Specifies when to start the service. You must specify one of the following start types.

Value	Meaning
SERVICE_BOOT_START	Specifies a device driver started by the operating system loader. This value is valid only for driver services.
SERVICE_SYSTEM_START	Specifies a device driver started by the IoInitSystem function. This value is valid only for driver services.
SERVICE_AUTO_START	Specifies a service to be started automatically by the service control manager during system startup.
SERVICE_DEMAND_START	Specifies a service to be started by the service control manager when a process calls the StartService function.
SERVICE_DISABLED	Specifies a service that can no longer be started.

dwErrorControl

Specifies 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. You must specify one of the following error control flags.

Value	Meaning
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

Points to a null-terminated string that contains the fully qualified path to the service binary file.

lpLoadOrderGroup

Pointer to a null-terminated string that names the load ordering group of which this service is a member. Specify NULL or an empty string if the service does not belong to a group.

lpdwTagId

Pointer to a DWORD variable that receives a tag value that is unique in the group specified in the lpLoadOrderGroup parameter. Specify NULL 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

Points to a double null-terminated array of null-separated names of services or load ordering groups that the system must start before this service. Specify NULL or an empty string 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

Pointer to a null-terminated string that names the service. If the service type is SERVICE_WIN32_OWN_PROCESS, use an account name 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 the service type is SERVICE_WIN32_SHARE_PROCESS you must specify the LocalSystem account. If you specify NULL, CreateService uses the LocalSystem account.

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 NULL if the driver is to use a default object name created by the I/O system.

lpPassword

Points to a null-terminated string that contains the password to the account name specified by the lpServiceStartName parameter. If the pointer is NULL or if it points to an empty string, the service has no password. Passwords are ignored for driver services. If lpServiceStartName is LocalSystem, the password must be NULL.

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.

Errors

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.

Value

Meaning

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.

SC_HANDLE hSCManager,	// handle to service control manager database
LPCTSTR lpServiceName,	// pointer to name of service to start
LPCTSTR lpDisplayName,	// pointer to display name
DWORD dwDesiredAccess,	// type of access to service
DWORD dwServiceType,	// type of service
DWORD dwStartType,	// when to start service
DWORD dwErrorControl,	// severity if service fails to start
LPCTSTR lpBinaryPathName,	// pointer to name of binary file
LPCTSTR lpLoadOrderGroup,	// pointer to name of load ordering group
LPDWORD lpdwTagId,	// pointer to variable to get tag identifier
LPCTSTR lpDependencies,	// pointer to array of dependency names
LPCTSTR lpServiceStartName,	// pointer to account name of service
LPCTSTR lpPassword	// pointer to password for service account
);

Standard rights	Description
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\|WRITE_OWNER	Enables calling of the SetServiceObjectSecurity function to modify the security descriptor of the service object.

Access	Description
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.

Generic access	Service access
GENERIC_READ	Combines the following access types: STANDARD_RIGHTS_READ, SERVICE_QUERY_CONFIG, SERVICE_QUERY_STATUS, 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, SERVICE_INTERROGATE, and SERVICE_USER_DEFINED_CONTROL.

Value	Meaning
SERVICE_INTERACTIVE_PROCESS	Enables a Win32-based service process to interact with the desktop.

Value	Meaning
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.

CreateService info Overview Group

Parameters

Return Values

Errors

Remarks

See Also