INetCfgLock::AcquireWriteLock method

Artigo
06/19/2017

The AcquireWriteLock method requests that the operating system grant a lock on network configuration so a particular client can configure network components and binding paths.

Syntax

HRESULT AcquireWriteLock(
  [in]            DWORD   cmsTimeout,
  [in]            LPCWSTR pszwClientDescription,
  [out, optional] LPWSTR  *ppszwClientDescription
);

Parameters

cmsTimeout [in]
Specifies the time, in milliseconds, to wait for the operating system to grant the lock on network configuration before timing out.
pszwClientDescription [in]
Pointer to a constant null-terminated string of 16-bit Unicode characters containing the name of the client that requests control over network configuration.
ppszwClientDescription [out, optional]
Pointer to a buffer that receives a constant null-terminated string of 16-bit Unicode characters containing the name of the client that currently controls network configuration if the operating system refused to grant the lock.

Return value

Returns zero (S_OK) if successful, indicating that the operating system granted the lock; otherwise returns one of the following codes:

Return code	Description
S_FALSE	The wait time, cmsTimeout, elapsed before the operating system granted the lock.
NETCFG_E_NEED_REBOOT	A system reboot is required before the lock can be granted. AcquireWriteLock can also return other NETCFG_* codes that are defined in Netcfgx.h.

S_FALSE

The wait time, cmsTimeout, elapsed before the operating system granted the lock.

NETCFG_E_NEED_REBOOT

A system reboot is required before the lock can be granted.

AcquireWriteLock can also return other NETCFG_* codes that are defined in Netcfgx.h.

Remarks

Applications can only call AcquireWriteLock either before they call the INetCfg::Initialize method, or after they call the INetCfg::Uninitialize method. In all other cases, calls to AcquireWriteLock return NETCFG_E_ALREADY_INITIALIZED. If the current user is not an administrator of the local computer, calls to AcquireWriteLock return E_ACCESSDENIED.

Calls to notify objects typically occur after the network configuration subsystem has called AcquireWriteLock to obtain control and INetCfg::Initialize to initialize itself. For this reason, notify objects should rarely, if ever, call AcquireWriteLock to request control over network configuration.

When an application calls AcquireWriteLock to request control over network configuration, it identifies the client requesting control by passing the client's name in the pszwClientDescription parameter. If the application subsequently requests control for a different client, the network configuration subsystem refuses and can display a message stating the name of the client that already has control.

If a call to AcquireWriteLock returns the name of the client that already has control of network configuration at ppszwClientDescription, AcquireWriteLock allocates the memory required to store the string that contains the name. After applications finish with the name, they must call the COM CoTaskMemFree function to release the memory. For more information about CoTaskMemFree, see the Microsoft Windows SDK.

Requirements

Target platform	Desktop
Header	Netcfgx.h (include Netcfgx.h)

Compartilhar via