[This is a preview of an interface that may appear in future releases of Windows.]
The SetNamedSecurityInfoEx function sets the specified security information for an object specified by name.
SetNamedSecurityInfoEx differs from the SetNamedSecurityInfo function in that it allows you to set access-control information for the properties on an object, as well as for the object itself. In addition, SetNamedSecurityInfoEx uses provider-independent access flags, but SetNamedSecurityInfo uses Windows NT-specific access flags.
DWORD SetNamedSecurityInfoEx(
|
LPCTSTR lpObject, |
// name of the object |
|
SE_OBJECT_TYPE ObjectType, |
// type of object |
|
SECURITY_INFORMATION SecurityInfo, |
// type of security information to set |
|
LPCTSTR lpProvider, |
// name of provider to handle request |
|
PACTRL_ACCESS pAccessList, |
// pointer to the DACL information |
|
PACTRL_AUDIT pAuditList, |
// pointer to the SACL information |
|
LPTSTR lpOwner, |
// name of the object’s owner |
|
LPTSTR lpGroup, |
// name of the object’s primary group |
|
PACTRL_OVERLAPPED pOverlapped |
// pointer to a structure for asynchronous operation |
|
); |
|
Value |
Meaning |
|
OWNER_SECURITY_INFORMATION |
Set the object’s owner. The lpOwner parameter points to the new name of the object’s owner. |
|
GROUP_SECURITY_INFORMATION |
Set the object’s primary group. The lpGroup parameter points to the new name of the object’s primary group. |
|
DACL_SECURITY_INFORMATION |
Set the discretionary access-control list (DACL) for the object. The pAccessList parameter points to a structure containing new access-control information for the object. For DS objects, the pAccessList buffer can also contain access-control information for any properties on the object. |
|
SACL_SECURITY_INFORMATION |
Set the system access-control list (SACL) for the object. The pAuditList parameter points to a structure containing new audit-control information for the object. For DS objects, the pAuditList buffer can also contain audit-control information for any properties on the object. |
The function uses a NULL owner for objects on systems other than Windows NT
that do not support object owners.
The function uses a NULL primary group for objects on systems other than
Windows NT that do not support object groups.
If this parameter is NULL, the function is performed synchronously and does not return until the operation has been completed. Note that a synchronous operation can take an extended period of time and cannot be cancelled.
If the function succeeds, the return value is ERROR_SUCCESS. If the pOverlapped parameter was NULL, the function successfully set the specified security information. If pOverlapped was not NULL, the function started the asynchronous operation.
If the function fails, the return value can be one of the following error codes.
|
Value |
Meaning |
|
ERROR_BAD_PROVIDER |
The lpProvider parameter specified an invalid provider name. |
|
ERROR_INVALID_PARAMETER |
An invalid parameter was specified. |
|
ERROR_NOT_ENOUGH_MEMORY |
A memory allocation failed |
If the pOverlapped parameter is points to a valid ACTRL_OVERLAPPED structure, SetNamedSecurityInfoEx returns immediately and returns a handle to an event object in the hEvent member of the ACTRL_OVERLAPPED structure. The system sets this event object to the signaled state when the operation has been completed. You can call the GetOverlappedAccessResults function to wait for the operation to be completed and retrieve the results of the asynchronous operation. Alternatively, you can call one of the wait functions, such as WaitForSingleObject, to wait for the event object to be signaled, and then call GetOverlappedAccessResults to determine the results of the operation. The wait functions also allow you to specify a time-out interval; if the interval elapses before the event is signaled, you can call the CancelOverlappedAccess function to cancel the asynchronous operation. If the pOverlapped parameter is NULL, the operation is performed synchronously.
To set the security information for a DS object and all its properties, specify SE_DS_OBJECT in the ObjectType parameter and use the pAccessList and pAuditList parameters to specify the security information. Set the pPropertyAccessList member of the ACTRL_ACCESS or ACTRL_AUDIT structure to point to an array of ACTRL_PROPERTY_ENTRY structures. Use one ACTRL_PROPERTY_ENTRY structure to specify access-control information for the object, and additional structures to specify information for each property that requires explicit security. Properties that are not explicitly identified in the array of ACTRL_PROPERTY_ENTRY structures are protected only by the object’s access control.
For file, registry, and DS objects, the SetNamedSecurityInfoEx function can propagate access-control information to the child objects of the specified object. This can occur when the child objects inherit access-control entries from their parent object. This propagation can be time consuming, so you might want to perform it as an asynchronous operation.
Currently, the import library for the SetNamedSecurityInfoEx function is ACCSRC.LIB. This is temporary. Eventually, the import library will be ADVAPI32.LIB. Meanwhile, any source code that links with the ACCSRC.LIB library must call the AccProvInit macro as follows:
DWORD dwErrcode;
AccProvInit(dwErrcode);
if(dwErrcode != ERROR_SUCCESS)
{
// Consider this an error...
}
ACTRL_ACCESS, ACTRL_AUDIT, ACTRL_PROPERTY_ENTRY, GetNamedSecurityInfoEx, GetSecurityInfoEx, SE_OBJECT_TYPE, SECURITY_INFORMATION, SetSecurityInfoEx