Reconfiguring a Service

[Previous] [Next]

The CreateService function adds the new service's entry to the SCM's database. It's unusual to do so, but occasionally you might want to change the information in the database. For instance, the user account associated with the entry might need its password changed, or you might want to change the service from manual start to automatic start. Well, Windows offers you four functions that help you reconfigure a service. The first function, QueryServiceConfig, retrieves the service's entry from the SCM's database:

 BOOL QueryServiceConfig(    SC_HANDLE             hService,    QUERY_SERVICE_CONFIG* pqsc,    DWORD                 dwBufSize,    PDWORD                pdwBytesNeeded); 

When you call this function, the hService parameter identifies the service you wish to query. The handle must be opened with SERVICE_QUERY_CONFIG access. You must also allocate a memory buffer large enough to hold a QUERY_SERVICE_CONFIG structure and all the service's string data. A QUERY_SERVICE_CONFIG structure looks like this:

 typedef struct _QUERY_SERVICE_CONFIG {    DWORD  dwServiceType;    DWORD  dwStartType;    DWORD  dwErrorControl;    PTSTR  lpBinaryPathName;    PTSTR  lpLoadOrderGroup;    DWORD  dwTagId;    PTSTR  lpDependencies;    PTSTR  lpServiceStartName;    PTSTR  lpDisplayName; } QUERY_SERVICE_CONFIG, *LPQUERY_SERVICE_CONFIG;  

The dwBufSize parameter of QueryServiceConfig tells the function how big your buffer is, and the DWORD pointed to by the pdwBytesNeeded parameter is filled in by the function, telling you how big the buffer needs to be. The buffer that you pass to QueryServiceConfig will always have to be bigger than the size of a QUERY_SERVICE_CONFIG structure because the function copies all the service's string data into the buffer immediately after copying the fixed-size data structure. The PTSTR members will point to memory addresses inside this buffer.

Once you have the service's current configuration, you can change it by calling the following:

 BOOL ChangeServiceConfig(    SC_HANDLE hService,     DWORD     dwServiceType,    DWORD     dwStartType,     DWORD     dwErrorControl,     PCTSTR    pszPathName,    PCTSTR    pszLoadOrderGroup,    PDWORD    pdwTagId,    PCTSTR    pszDependencies,    PCTSTR    pszUserName,    PCTSTR    pszUserPswd,    PCTSTR    pszDisplayName); 

As you can see, these parameters are practically identical to those passed to CreateService. The differences are that you cannot change the service's internal name and that the display name is the last parameter. When you use ChangeServiceConfig, the changes do not take effect until the service stops.

In addition to providing QueryServiceConfig and ChangeServiceConfig, Windows offers the QueryServiceConfig2 and ChangeServiceConfig2 functions, which allow you to get and set a service's description and failure actions. Customers have long desired both of these features, and it's nice to see Microsoft add them to Windows 2000.

A service's description is simply a string (limited to 1024 characters) that describes the service. This string appears in the Services snap-in and really helps administrators understand the purpose of each service installed and running on the system. You are strongly encouraged to add descriptions when you add a service to the SCM's database.

Using failure actions, an administrator can tell the system what action to take when a service fails. (A service fails if its process dies without the service setting its state to SERVICE_STOPPED.) An administrator can have the SCM automatically restart the service, run an application, or reboot the computer. For more information about QueryServiceConfig2 and ChangeServiceConfig2, please see the Platform SDK documentation.