LockServiceDatabase

LockServiceDatabase

The LockServiceDatabase function requests ownership of the service control manager database lock. Only one process can own the lock at any given time.

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. For more information, see Service Security and Access Rights.

Return Values

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.

Return code	Description
ERROR_ACCESS_DENIED	The handle does not have the SC_MANAGER_LOCK access right.
ERROR_INVALID_HANDLE	The specified handle is invalid.
ERROR_SERVICE_DATABASE_LOCKED	The database is locked.

Remarks

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.

Example Code

For an example, see Changing a Service Configuration.

Requirements

Client	Requires Windows XP, Windows 2000 Professional, or Windows NT Workstation.
Server	Requires Windows Server 2003, Windows 2000 Server, or Windows NT Server.
Header	Declared in Winsvc.h; include Windows.h.
Library	Link to Advapi32.lib.
DLL	Requires Advapi32.dll.