Expand Minimize

LsaOpenPolicy function

The LsaOpenPolicy function opens a handle to the Policy object on a local or remote system.

You must run the process "As Administrator" so that the call doesn't fail with ERROR_ACCESS_DENIED.

Syntax


NTSTATUS LsaOpenPolicy(
  _In_     PLSA_UNICODE_STRING SystemName,
  _In_     PLSA_OBJECT_ATTRIBUTES ObjectAttributes,
  _In_     ACCESS_MASK DesiredAccess,
  _Inout_  PLSA_HANDLE PolicyHandle
);

Parameters

SystemName [in]

A pointer to an LSA_UNICODE_STRING structure that contains the name of the target system. The name can have the form "ComputerName" or "\\ComputerName". If this parameter is NULL, the function opens the Policy object on the local system.

ObjectAttributes [in]

A pointer to an LSA_OBJECT_ATTRIBUTES structure that specifies the connection attributes. The structure members are not used; initialize them to NULL or zero.

DesiredAccess [in]

An ACCESS_MASK that specifies the requested access rights. The function fails if the DACL of the target system does not allow the caller the requested access. To determine the access rights that you need, see the documentation for the LSA functions with which you want to use the policy handle.

PolicyHandle [in, out]

A pointer to an LSA_HANDLE variable that receives a handle to the Policy object.

When you no longer need this handle, pass it to the LsaClose function to close it.

Return value

If the function succeeds, the function returns STATUS_SUCCESS.

If the function fails, it returns an NTSTATUS code. For more information, see LSA Policy Function Return Values.

You can use the LsaNtStatusToWinError function to convert the NTSTATUS code to a Windows error code.

Remarks

To administer the local security policy of a local or remote system, you must call the LsaOpenPolicy function to establish a session with that system's LSA subsystem. LsaOpenPolicy connects to the LSA of the target system and returns a handle to the Policy object of that system. You can use this handle in subsequent LSA function calls to administer the local security policy information of the target system.

For an example that demonstrates calling this function see Opening a Policy Object Handle.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Ntsecapi.h

Library

Advapi32.lib

DLL

Advapi32.dll

See also

LSA_HANDLE
LSA_OBJECT_ATTRIBUTES
LSA_UNICODE_STRING
LsaClose
LsaNtStatusToWinError

 

 

Community Additions

ADD
Show:
© 2014 Microsoft