Change method of the Win32_BaseService class

The Change WMI class method modifies a service object derived from Win32_BaseService. The Win32_LoadOrderGroup parameter represents a group of system services that define execution dependencies. The services must be initiated in the order specified by the Load Order Group, because the services depend on each other. These dependent services require antecedent services to function correctly.

This topic uses Managed Object Format (MOF) syntax. For more information about using this method, see Calling a Method.

Syntax

uint32 Change(
  [in] string  DisplayName,
  [in] string  PathName,
  [in] uint8   ServiceType,
  [in] uint8   ErrorControl,
  [in] string  StartMode,
  [in] boolean DesktopInteract,
  [in] string  StartName,
  [in] string  StartPassword,
  [in] string  LoadOrderGroup,
  [in] string  LoadOrderGroupDependencies[],
  [in] string  ServiceDependencies[]
);

Parameters

DisplayName [in]

The display name for a service. This string has a maximum length of 256 characters. The name is case preserved in the service control manager. DisplayName comparisons are always case insensitive.

Constraints: Accepts the same value as the Name parameter.

Example: "Atdisk".

PathName [in]

The fully qualified path to the executable file that implements a service.

Example: "\SystemRoot\System32\drivers\afd.sys".

ServiceType [in]

Type of services provided to processes that call them.

Kernel Driver (1)

File System Driver (2)

Adapter (4)

Recognizer Driver (8)

Own Process (16)

Share Process (32)

(256)

Interactive Process

ErrorControl [in]

Severity of an error if this service does not start during startup. The value indicates the action that the startup program takes if failure occurs. The system logs all errors.

Ignore (0)

User is not notified.

Normal (1)

Normal. User is notified.

Severe (2)

System is restarted with the last good configuration.

Critical (3)

System attempts to restart with a good configuration.

StartMode [in]

Start mode of the Windows base service.

Boot Start ("Boot")

Device driver that the operating system loader starts.

System Start ("System")

Device driver started by the operating system initialization process. This value is valid only for driver services.

Auto Start ("Automatic")

Service to start automatically by the service control manager during system startup.

Demand Start ("Manual")

Service to start by the service control manager when a process calls the StartService method.

Disabled ("Disabled")

Service that cannot be started.

DesktopInteract [in]

If True, the service can create or communicate with a window on the desktop.

StartName [in]

Account name that the service runs under, which depends on the service type. The account name may be in the form of DomainName\Username or .\Username. When it runs, the service process is logged by using one of the previous two forms. If the account belongs to the built-in domain, .\Username can be specified. If an empty string is specified, the service is logged on as the LocalSystem account. For kernel or system-level drivers, StartName contains the driver object name, for example, \FileSystem\Rdr or \Driver\Xns, which the input and output (I/O) system uses to load the device driver. If NULL is specified, the driver runs with a default object name that the I/O system creates based on the service name, for example, DWDOM\Admin.

You also can use the User Principal Name (UPN) format to specify the StartName, for example, Username@DomainName.

StartPassword [in]

Password to the account name that the StartName parameter specifies. Specify NULL when you do not change the password. Specify an empty string if the service does not have a password.

Note

When you change a service from local system to network or from network to local system, StartPassword must be an empty string ("") and not NULL.

LoadOrderGroup [in]

Group name that it is associated with. Load order groups are contained in the system registry, and determine the sequence that services are loaded into an operating system. If the pointer is NULL, or points to an empty string, the service does not belong to a group. Dependencies between groups should be listed in the LoadOrderGroupDependencies parameter. Services in the load-ordering group list are started first, followed by services in groups not in the load-ordering group list, followed by services that do not belong to a group. The system registry has a list of load ordering groups located at HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceGroupOrder.

LoadOrderGroupDependencies [in]

List of load-ordering groups that must start before this service starts. The array is doubly null-terminated. If the pointer is NULL, or if it points to an empty string, the service does not have dependencies. Group names must be prefixed by the SC_GROUP_IDENTIFIER (defined in the Winsvc.h file) character to differentiate them from service names, because services and service groups share the same namespace. 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 of the members of the group.

ServiceDependencies [in]

List that contains the names of services that must start before this service starts. The array is doubly null-terminated. If the pointer is NULL, or points to an empty string, the service does not have dependencies. Dependency on a service means that this service can run only if the service it depends on is running.

Return value

Returns one of the values listed in the following list, or a different value to indicate an error.

Success

0

The request is accepted.

Not Supported

1

The request is not supported.

Access Denied

2

The user does not have the necessary access privileges.

Dependent Services Running

3

The service cannot be stopped because other services that are running are dependent on it.

Invalid Service Control

4

The requested control code is not valid, or is unacceptable to the service.

Service Cannot Accept Control

5

The requested control code cannot be sent to the service because the State property in the Win32_BaseService object is equal to 0, 1, or 2.

Service Not Active

6

The service has not been started.

Service Request Timeout

7

The service does not respond to the start request quickly.

Unknown Failure

8

Interactive process.

Path Not Found

9

The directory path to the service executable file is not found.

Service Already Running

10

The service is already running.

Service Database Locked

11

The database to add a new service is locked.

Service Dependency Deleted

12

A dependency for which this service relies on is removed from the system.

Service Dependency Failure

13

The service does not find the service needed from a dependent service.

Service Disabled

14

The service is disabled from the system.

Service Logon Failed

15

The service does not have the correct authentication to run on the system.

Service Marked For Deletion

16

This service is being removed from the system.

Service No Thread

17

There is no execution thread for the service.

Status Circular Dependency

18

There are circular dependencies when starting the service.

Status Duplicate Name

19

There is a service running under the same name.

Status Invalid Name

20

There are invalid characters in the name of the service.

Status Invalid Parameter

21

Invalid parameters have been passed to the service.

Status Invalid Service Account

22

The account for this service to run under is not valid or does not have the permissions to run the service.

Status Service Exists

23

The service exists in the database of services available from the system.

Service Already Paused

24

The service is currently paused in the system.

Other

25 4294967295

Remarks

To change a service from a network to a local system, use the following values for the StartName and StartPassword parameters:

StartName = "LocalSystem"
StartPassword = "" // - empty string, not NULL

To change a service from a local system to a network, use the following values for the StartName and StartPassword parameters:

StartName = "NT AUTHORITY\NetworkService"
StartPassword = "" // - empty string, not NULL

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Namespace	Root\CIMV2
Header	Mbnapi.h
MOF	CIMWin32.mof
DLL	CIMWin32.dll

See also

Operating System Classes

Win32_BaseService