| Previous | Main | Next | Site Index | Download | Disclaimer | Privacy |


 

 

 

 

 

 

ANOTHER WINDOWS SERVICES: A SUPPLEMENTARY NOTE

 

 

 

 

 

 

 

 

Windows Service: Functions used in program examples of Windows Services 1 and Windows Services 2 wherever applicable. To learn about function you can jump to C & C++ function tutorials.

 

The Page Index

  1. DeleteService()

  2. OpenService()

  3. CloseServiceHandle()

  4. QueryServiceLockStatus()

  5. ChangeServiceConfig2()

  6. ChangeServiceConfig()

  7. LockServiceDatabase()

  8. QueryServiceLockStatus()

  9. QueryServiceConfig()

  10. QueryServiceConfig2()

  11. UnlockServiceDatabase()

  12. StartService()

 

 

DeleteService()

 

Item

Description

Function

DeleteService().

Use

Marks the specified service for deletion from the service control manager database.

Prototype

BOOL DeleteService(SC_HANDLE hService);

Parameters

hService - [in] Handle to the service. This handle is returned by the OpenService() or CreateService() function, and it must have the DELETE access right.

Return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). The following error codes may be set by the service control manager. Others may be set by the registry functions that are called by the service control manager.

  1. ERROR_ACCESS_DENIED - The handle does not have the DELETE access right.

  2. ERROR_INVALID_HANDLE - The specified handle is invalid.

  3. ERROR_SERVICE_MARKED_FOR_DELETE - The specified service has already been marked for deletion.

Include file

<windows.h>

Remark

The DeleteService() function marks a service for deletion from the service control manager database. The database entry is not removed until all open handles to the service have been closed by calls to the CloseServiceHandle() function and the service is not running. A running service is stopped by a call to the ControlService() function with the SERVICE_CONTROL_STOP control code. If the service cannot be stopped, the database entry is removed when the system is restarted. The service control manager deletes the service by deleting the service key and its subkeys from the registry.

 

Table 1.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

OpenService()

 

Item

Description

Function

OpenService().

Use

Opens an existing service.

Prototype

SC_HANDLE OpenService( SC_HANDLE hSCManager, LPCTSTR lpServiceName, DWORD dwDesiredAccess);

Parameters

hSCManager - [in] Handle to the service control manager database. The OpenSCManager() function returns this handle.

lpServiceName - [in] Pointer to a null-terminated string that specifies the name of the service to open. 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 backslash (\) are invalid service name characters.

dwDesiredAccess - [in] Access to the service. Before granting the requested access, the system checks the access token of the calling process against the discretionary access-control list of the security descriptor associated with the service object.

Return value

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(). The following error codes can be set by the service control manager. Others can be set by the registry functions that are called by the service control manager.

  1. ERROR_ACCESS_DENIED - The handle does not have access to the service.

  2. ERROR_INVALID_HANDLE - The specified handle is invalid.

  3. ERROR_INVALID_NAME - The specified service name is invalid.

  4. ERROR_SERVICE_DOES_NOT_EXIST - The specified service does not exist.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions. The returned handle is only valid for the process that called OpenService(). It can be closed by calling the CloseServiceHandle() function.

 

Table 2.

 

CloseServiceHandle()

 

Item

Description

Function

CloseServiceHandle().

Use

Closes a handle to a service control manager or service object.

Prototype

BOOL CloseServiceHandle(SC_HANDLE hSCObject);

Parameters

hSCObject - [in] Handle to the service control manager object or the service object to close. Handles to service control manager objects are returned by the OpenSCManager() function, and handles to service objects are returned by either the OpenService() or CreateService() function.

Return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). The following error code can be set by the service control manager:

  • ERROR_INVALID_HANDLE - The specified handle is invalid.

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

Include file

<windows.h>

Remark

The CloseServiceHandle() function does not destroy the service control manager object referred to by the handle. A service control manager object cannot be destroyed. A service object can be destroyed by calling the DeleteService() function.

 

Table 3.

 

QueryServiceLockStatus()

 

Item

Description

Function

QueryServiceLockStatus().

Use

Retrieves the lock status of the specified service control manager database.

Prototype

BOOL QueryServiceLockStatus( SC_HANDLE hSCManager, LPQUERY_SERVICE_LOCK_STATUS lpLockStatus, DWORD cbBufSize, LPDWORD pcbBytesNeeded);

Parameters

hSCManager - [in] Handle to the service control manager database. The OpenSCManager() function returns this handle, which must have the SC_MANAGER_QUERY_LOCK_STATUS access right. 

lpLockStatus - [out] Pointer to a QUERY_SERVICE_LOCK_STATUS structure that receives the lock status of the specified database is returned, plus the strings to which its members point. 

cbBufSize - [in] Size of the buffer pointed to by the lpLockStatus parameter, in bytes. 

pcbBytesNeeded - [out] Pointer to a variable that receives the number of bytes needed to return all the lock status information, if the function fails.

Return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). 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.

  1. ERROR_ACCESS_DENIED - The handle does not have the SC_MANAGER_QUERY_LOCK_STATUS access right.

  2. ERROR_INSUFFICIENT_BUFFER - There is more lock status information than would fit into the lpLockStatus buffer. The number of bytes required to get all the information is returned in the pcbBytesNeeded parameter. Nothing is written to lpLockStatus.

  3. ERROR_INVALID_HANDLE - The specified handle is invalid.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions. The

QueryServiceLockStatus() function returns a QUERY_SERVICE_LOCK_STATUS structure that indicates whether the specified database is locked. If the database is locked, the structure provides the account name of the user that owns the lock and the length of time that the lock has been held. A process calls the LockServiceDatabase() function to acquire ownership of a service control manager database lock and the UnlockServiceDatabase() function to release the lock.

 

Table 4.

 

ChangeServiceConfig2()

 

Item

Description

Function

ChangeServiceConfig2().

Use

Changes the optional configuration parameters of a service.

Prototype

BOOL ChangeServiceConfig2(SC_HANDLE hService, DWORD dwInfoLevel, LPVOID lpInfo);

Parameters

hService - [in] Handle to the service. This handle is returned by the OpenService() or CreateService() function and must have the SERVICE_CHANGE_CONFIG access right. If one of the specified service controller actions is SC_ACTION_RESTART, hService must have the SERVICE_START access right.

dwInfoLevel - [in] Configuration information to be changed. This parameter can be one of the following values.

  1. SERVICE_CONFIG_DESCRIPTION - The lpInfo parameter is a pointer to a SERVICE_DESCRIPTION structure.

  2. SERVICE_CONFIG_FAILURE_ACTIONS - The lpInfo parameter is a pointer to a SERVICE_FAILURE_ACTIONS structure.

  3. If you specify SC_ACTION_REBOOT, the caller must have the SE_SHUTDOWN_NAME privilege.

 

lpInfo - [in] Pointer to the new value to be set for the configuration information. The format of this data depends on the value of the dwInfoLevel parameter. If this value is NULL, the information remains unchanged.

Return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions. The ChangeServiceConfig2() function changes the optional configuration information for the specified service in the service control manager database. You can obtain the current optional configuration information by using the QueryServiceConfig2() function. You cannot set the SERVICE_CONFIG_FAILURE_ACTIONS value for a service that shares the service control manager's process. This includes all services whose executable image is "services.exe". You can change and query additional configuration information using the ChangeServiceConfig() and QueryServiceConfig() functions, respectively.

 

Table 5.

 

ChangeServiceConfig()

 

Item

Description

Function

ChangeServiceConfig().

Use

Changes the configuration parameters of a service. To change the optional configuration parameters, use the ChangeServiceConfig2() function.

Prototype

BOOL ChangeServiceConfig( SC_HANDLE hService, DWORD dwServiceType, DWORD dwStartType, DWORD dwErrorControl, LPCTSTR lpBinaryPathName, LPCTSTR lpLoadOrderGroup, LPDWORD lpdwTagId, LPCTSTR lpDependencies, LPCTSTR lpServiceStartName, LPCTSTR lpPassword, LPCTSTR lpDisplayName );

Parameters

See below.

Return value

See below.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions. The ChangeServiceConfig() function changes the configuration information for the specified service in the service control manager database. You can obtain the current configuration information by using the QueryServiceConfig() function. If the configuration is changed for a service that is running, with the exception of lpDisplayName, the changes do not take effect until the service is stopped. To update the credentials without having to restart the service, use the LsaCallAuthenticationPackage() function.

 

Security Remarks: Setting the lpServiceStartName parameter changes the logon account of the service. This can cause problems. If you have registered a service principal name (SPN), it would now be registered on the wrong account. Similarly, if you have used an ACE to grant access to a service, it would now grant access to the wrong account.

 

Table 6.

 

Parameters

 

hService - [in] Handle to the service. This handle is returned by the OpenService() or CreateService() function and must have the SERVICE_CHANGE_CONFIG access right.

dwServiceType - [in] Type of service. Specify SERVICE_NO_CHANGE if you are not changing the existing service type; otherwise, specify one of the following service types.

 

Type

Meaning

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.

 

Table 7

 

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.

 

Type

Meaning

SERVICE_INTERACTIVE_PROCESS

The service can interact with the desktop.

 

Table 8

 

dwStartType - [in] Service start options. Specify SERVICE_NO_CHANGE if you are not changing the existing start type; otherwise, specify one of the following values.

 

Type

Meaning

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.

 

Table 9

 

dwErrorControl - [in] Severity of the error, and action taken, if this service fails to start. Specify SERVICE_NO_CHANGE if you are not changing the existing error control; otherwise, specify one of the following values.

 

Values

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.

 

Table 10

 

lpBinaryPathName - [in] Pointer to a null-terminated string that contains the fully qualified path to the service binary file. Specify NULL if you are not changing the existing path. 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\""

 

The path can also include arguments for an auto-start service. For example, "d:\\myshare\\myservice.exe arg1 arg2". These arguments are passed to the service entry point (typically the main function).

lpLoadOrderGroup - [in] Pointer to a null-terminated string that names the load ordering group of which this service is a member. Specify NULL if you are not changing the existing group. Specify an empty string if the service does not belong to a group. The startup program uses load ordering groups to load groups of services in a specified order with respect to the other groups. The list of load ordering groups is contained in the ServiceGroupOrder value of the following registry key:

 

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control

 

lpdwTagId - [out] Pointer to a 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 - [in] Pointer to a double null-terminated array of null-separated names of services or load ordering groups that the system must start before this service can be started. 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. Specify NULL if you are not changing the existing dependencies. Specify an empty string if the service has no dependencies. 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] Pointer to a null-terminated string that specifies the name of the account under which the service should run. Specify NULL if you are not changing the existing account name. 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 (note that the corresponding C/C++ string is ".\\UserName"). For Windows NT:  If the service type is SERVICE_WIN32_SHARE_PROCESS, you must specify the LocalSystem account. On later versions of Windows, 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 NULL if the driver is to use a default object name created by the I/O system.

lpPassword - [in] Pointer to a null-terminated string that contains the password to the account name specified by the lpServiceStartName parameter. Specify NULL if you are not changing the existing password. Specify an empty string if the account has no password or if the service runs in the LocalService, NetworkService, or LocalSystem account. Passwords are ignored for driver services.

lpDisplayName - [in] Pointer to a null-terminated string that contains the display name to be used by applications to identify the service for its users. Specify NULL if you are not changing the existing display name; otherwise, 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.

 

Return Values

 

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

 

Return code

Description

ERROR_ACCESS_DENIED

The handle does not have the SERVICE_CHANGE_CONFIG access right.

ERROR_CIRCULAR_DEPENDENCY

A circular service dependency was specified.

ERROR_DUPLICATE_SERVICE_NAME

The display name already exists in the service controller manager database, either as a service name or as another display name.

ERROR_INVALID_HANDLE

The specified handle is invalid.

ERROR_INVALID_PARAMETER

A parameter that was specified is invalid.

ERROR_INVALID_SERVICE_ACCOUNT

The account name does not exist, or a service is specified to share the same binary file as an already installed service but with an account name that is not the same as the installed service.

ERROR_SERVICE_MARKED_FOR_DELETE

The service has been marked for deletion.

 

Table 11

 

LockServiceDatabase()

 

Item

Description

Function

LockServiceDatabase().

Use

Requests ownership of the service control manager database lock. Only one process can own the lock at any given time.

Prototype

SC_LOCK LockServiceDatabase(SC_HANDLE hSCManager);

Parameters

hSCManager - [in] Handle to the service control manager database. This handle is returned by the OpenSCManager() function, and must have the SC_MANAGER_LOCK access right.

Return value

If the function succeeds, the return value is a lock to the specified service control manager database. If the function fails, the return value is NULL. To get extended error information, call GetLastError(). The following error code can be set by the service control manager. Other error codes can be set by registry functions that are called by the service control manager.

  1. ERROR_ACCESS_DENIED - The handle does not have the SC_MANAGER_LOCK access right.

  2. ERROR_INVALID_HANDLE - The specified handle is invalid.

  3. ERROR_SERVICE_DATABASE_LOCKED - The database is locked.

Include file

<windows.h>

Remark

A lock is a protocol used by setup and configuration programs and the service control manager to serialize access to the service tree in the registry. The only time the service control manager requests ownership of the lock is when it is starting a service. Acquiring the SCM database lock prevents the service control manager from starting a service until the lock is released. For example, a program that must configure several related services before any of them starts should call LockServiceDatabase() before configuring the first service. Similarly, a program that must call both ChangeServiceConfig() and ChangeServiceConfig2() for a particular service before it starts should call LockServiceDatabase() before calling either function. A call to the StartService() function to start a service in a locked database fails. No other service control manager functions are affected by a lock.

The lock is held until the SC_LOCK handle is specified in a subsequent call to the UnlockServiceDatabase() function. If a process that owns a lock terminates, the service control manager automatically cleans up and releases ownership of the lock.

 

Table 12.

 

QueryServiceLockStatus()

 

Item

Description

Function

QueryServiceLockStatus().

Use

Retrieves the lock status of the specified service control manager database.

Prototype

BOOL QueryServiceLockStatus( SC_HANDLE hSCManager, LPQUERY_SERVICE_LOCK_STATUS lpLockStatus, DWORD cbBufSize, LPDWORD pcbBytesNeeded);

Parameters

hSCManager - [in] Handle to the service control manager database. The OpenSCManager() function returns this handle, which must have the SC_MANAGER_QUERY_LOCK_STATUS access right.

lpLockStatus - [out] Pointer to a QUERY_SERVICE_LOCK_STATUS structure that receives the lock status of the specified database is returned, plus the strings to which its members point.

cbBufSize - [in] Size of the buffer pointed to by the lpLockStatus parameter, in bytes.

pcbBytesNeeded - [out] Pointer to a variable that receives the number of bytes needed to return all the lock status information, if the function fails.

Return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). 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.

  1. ERROR_ACCESS_DENIED - The handle does not have the SC_MANAGER_QUERY_LOCK_STATUS access right.

  2. ERROR_INSUFFICIENT_BUFFER - There is more lock status information than would fit into the lpLockStatus buffer. The number of bytes required to get all the information is returned in the pcbBytesNeeded parameter. Nothing is written to lpLockStatus.

  3. ERROR_INVALID_HANDLE - The specified handle is invalid.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions. The QueryServiceLockStatus() function returns a QUERY_SERVICE_LOCK_STATUS structure that indicates whether the specified database is locked. If the database is locked, the structure provides the account name of the user that owns the lock and the length of time that the lock has been held. A process calls the LockServiceDatabase() function to acquire ownership of a service control manager database lock and the UnlockServiceDatabase() function to release the lock.

 

Table 13.

 

QueryServiceConfig()

 

Item

Description

Function

QueryServiceConfig().

Use

Retrieves the configuration parameters of the specified service. Optional configuration parameters are available using the QueryServiceConfig2() function.

Prototype

BOOL QueryServiceConfig( SC_HANDLE hService, LPQUERY_SERVICE_CONFIG lpServiceConfig, DWORD cbBufSize, LPDWORD pcbBytesNeeded);

Parameters

hService - [in] Handle to the service. This handle is returned by the OpenService() or CreateService() function, and it must have the SERVICE_QUERY_CONFIG access right.

lpServiceConfig - [out] Pointer to a buffer that receives the service configuration information. The format of the data is a QUERY_SERVICE_CONFIG structure.

The maximum size of this array is 8K bytes. To determine the required size, specify NULL for this parameter and 0 for the cbBufSize parameter. The function will fail and GetLastError() will return ERROR_INSUFFICIENT_BUFFER. The pcbBytesNeeded parameter will receive the required size.

cbBufSize - [in] Size of the buffer pointed to by the lpServiceConfig parameter, in bytes.

pcbBytesNeeded - [out] Pointer to a variable that receives the number of bytes needed to store all the configuration information, if the function fails with ERROR_INSUFFICIENT_BUFFER.

Return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). The following error codes can be set by the service control manager. Others can be set by the registry functions that are called by the service control manager.

  1. ERROR_ACCESS_DENIED - The handle does not have the SERVICE_QUERY_CONFIG access right.

  2. ERROR_INSUFFICIENT_BUFFER - There is more service configuration information than would fit into the lpServiceConfig buffer. The number of bytes required to get all the information is returned in the pcbBytesNeeded parameter. Nothing is written to lpServiceConfig.

  3. ERROR_INVALID_HANDLE - The specified handle is invalid.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions. The QueryServiceConfig() function returns the service configuration information kept in the registry for a particular service. This configuration information is first set by a service control program using the CreateService() function. This information may have been updated by a service configuration program using the ChangeServiceConfig() function. If the service was running when the configuration information was last changed, the information returned by QueryServiceConfig() will not reflect the current configuration of the service. Instead, it will reflect the configuration of the service when it is next run. The DisplayName() key is an exception to this. When the DisplayName() key is changed, it takes effect immediately, regardless of whether the service is running.

 

Table 14.

 

QueryServiceConfig2()

 

Item

Description

Function

QueryServiceConfig2().

Use

Retrieves the optional configuration parameters of the specified service.

Prototype

BOOL QueryServiceConfig2( SC_HANDLE hService, DWORD dwInfoLevel, LPBYTE lpBuffer, DWORD cbBufSize, LPDWORD pcbBytesNeeded);

Parameters

hService - [in] Handle to the service. This handle is returned by the OpenService() or CreateService() function and must have the SERVICE_QUERY_CONFIG access right.

dwInfoLevel - [in] Configuration information to be queried. This parameter can be one of the following values.

  1. SERVICE_CONFIG_DESCRIPTION - The lpBuffer parameter is a pointer to a SERVICE_DESCRIPTION structure.

  2. SERVICE_CONFIG_FAILURE_ACTIONS - The lpBuffer parameter is a pointer to a SERVICE_FAILURE_ACTIONS structure.

 

lpBuffer - [out] Pointer to the buffer that receives the service configuration information. The format of this data depends on the value of the dwInfoLevel parameter. The maximum size of this array is 8K bytes. To determine the required size, specify NULL for this parameter and 0 for the cbBufSize parameter. The function will fail and GetLastError() will return ERROR_INSUFFICIENT_BUFFER. The pcbBytesNeeded parameter will receive the required size.

cbBufSize - [in] Size of the structure pointed to by the lpBuffer parameter, in bytes. 

pcbBytesNeeded - [out] Pointer to a variable that receives the number of bytes needed to store the configuration information, if the function fails with ERROR_INSUFFICIENT_BUFFER.

 

Return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). The following error codes can be set by the service control manager. Others can be set by the registry functions that are called by the service control manager.

  1. ERROR_ACCESS_DENIED - The handle does not have the SERVICE_QUERY_CONFIG access right.

  2. ERROR_INSUFFICIENT_BUFFER - There is more service configuration information than would fit into the lpBuffer buffer. The number of bytes required to get all the information is returned in the pcbBytesNeeded parameter. Nothing is written to lpBuffer.

  3. ERROR_INVALID_HANDLE - The specified handle is invalid.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions. The QueryServiceConfig2() function returns the optional configuration information stored in the service control manager database for the specified service. You can change this configuration information by using the ChangeServiceConfig2() function. You can change and query additional configuration information using the ChangeServiceConfig() and QueryServiceConfig() functions, respectively.

 

Table 15.

 

UnlockServiceDatabase()

 

Item

Description

Function

UnlockServiceDatabase().

Use

Unlocks a service control manager database by releasing the specified lock.

Prototype

BOOL UnlockServiceDatabase(SC_LOCK ScLock);

Parameters

ScLock - [in] Lock obtained from a previous call to the LockServiceDatabase() function.

Return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). 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_INVALID_SERVICE_LOCK - The specified lock is invalid.

Include file

<windows.h>

Remark

-

 

Table 16.

 

StartService()

 

Item

Description

Function

StartService().

Use

Starts a service.

Prototype

BOOL StartService( SC_HANDLE hService, DWORD dwNumServiceArgs, LPCTSTR* lpServiceArgVectors);

Parameters

hService - [in] Handle to the service. This handle is returned by the OpenService() or CreateService() function, and it must have the SERVICE_START access right.

dwNumServiceArgs - [in] Number of strings in the lpServiceArgVectors array. If lpServiceArgVectors is NULL, this parameter can be zero.

lpServiceArgVectors - [in] Pointer to an array of pointers to null-terminated strings to be passed to a service as arguments. Driver services do not receive these arguments. If no arguments are passed to the service, this parameter can be NULL. The service accesses these arguments through its ServiceMain() function. The first argument (argv[0]) is the name of the service by default, followed by the arguments, if any, in the lpServiceArgVectors array.

Return value

See below.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions. More remarks below.

 

Table 17.

 

Return Values

 

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). The following error codes can be set by the service control manager. Others can be set by the registry functions that are called by the service control manager.

 

Return code

Description

ERROR_ACCESS_DENIED

The handle does not have the SERVICE_START access right.

ERROR_INVALID_HANDLE

The handle is invalid.

ERROR_PATH_NOT_FOUND

The service binary file could not be found.

ERROR_SERVICE_ALREADY_RUNNING

An instance of the service is already running.

ERROR_SERVICE_DATABASE_LOCKED

The database is locked.

ERROR_SERVICE_DEPENDENCY_DELETED

The service depends on a service that does not exist or has been marked for deletion.

ERROR_SERVICE_DEPENDENCY_FAIL

The service depends on another service that has failed to start.

ERROR_SERVICE_DISABLED

The service has been disabled.

ERROR_SERVICE_LOGON_FAILED

The service could not be logged on. This error occurs if the service was started from an account that does not have the "Log on as a service" right.

ERROR_SERVICE_MARKED_FOR_DELETE

The service has been marked for deletion.

ERROR_SERVICE_NO_THREAD

A thread could not be created for the service.

ERROR_SERVICE_REQUEST_TIMEOUT

The process for the service was started, but it did not call StartServiceCtrlDispatcher(), or the thread that called StartServiceCtrlDispatcher() may be blocked in a control handler function.

 

Table 18

 

Some Remarks

 

When a driver service is started, the StartService() function does not return until the device driver has finished initializing. When a service is started, the Service Control Manager (SCM) spawns the service process, if necessary. If the specified service shares a process with other services, the required process may already exist. The StartService() function does not wait for the first status update from the new service, because it can take a while. Instead, it returns when the SCM receives notification from the service control dispatcher that the ServiceMain() thread for this service was created successfully. The SCM sets the following default status values before returning from StartService():

  1. Current state of the service is set to SERVICE_START_PENDING.

  2. A control accepted is set to none (zero).

  3. The CheckPoint value is set to zero.

  4. The WaitHint time is set to 2 seconds.

 

The calling process can determine if the new service has finished its initialization by calling the QueryServiceStatus() function periodically to query the service's status. A service cannot call StartService() during initialization. The reason is that the SCM locks the service control database during initialization, so a call to StartService() will block. Once the service reports to the SCM that it has successfully started, it can call StartService(). As with ControlService(), StartService() will block for 30 seconds if any service is busy handling a control code. If the busy service still has not returned from its handler function when the timeout expires, StartService() fails with ERROR_SERVICE_REQUEST_TIMEOUT. This is because the SCM processes only one service control notification at a time.

-----------------------------------------------End part 3/4---------------------------------------------

 

 

Further reading and digging:

 

  1. Microsoft Visual C++, online MSDN.

  2. Structure, enum, union and typedef story can be found at C enum, typedef, define etc..

  3. For Multibytes, Unicode characters and Localization please refer to Unicode & Multibyte 1 (Story) and Unicode & Multibyte 2 (Implementation).

  4. Windows data type information is in Windows data type.

  5. Check the best selling C / C++ and Windows books at Amazon.com.

 

 

 

 

 

 

 

 

 

| Previous | Main | Next | Site Index | Download | Disclaimer | Privacy |