wntAccessDel

Removes Discretionary Access Control List [DACL, a.k.a. permission] records from a resource.

Syntax:

wntAccessDel(server-name, resource/share-name, account-name, object-type[, flags])

Parameters:

(s) server-name Name of a network file server or empty string ("") to indicate the current machine.

(s) resource/share-name Identifies the object to be modified.

(s) account-name Name of a user or a group for whom access is being deleted. If necessary, it can be fully qualified as 'server\user'.

(i) object-type Identifies the object type of the 'resource/share-name'. See below.

(i) flags [optional] Controls behavior of the function. See below.

Returns:

(i) 1 [@TRUE] or 0 [@FALSE]. See below.

Server-Name

All attempts to work with permissions or auditing settings on remote computers will require that those remote computers have the "Server" service running.

Object-Type

Object-type	Resource/share-name description
100	Share (e.g., a directory share or a printer share). This is just the name of the share; no server information should be included with the share name [e.g. "MyShare", not "MyServer\MyShare"].
200	Printer object. The syntax for the resource name must be "\\server-name\printer-object-name". If the printer is on a remote NT/2K system then the server name must be passed as the first parameter [e.g. "\\server-name"] in addition to the resource name [that also contains the server name]. Whenever the permissions or audit settings on a printer object are changed, the permissions on any print shares associated with that printer object will also be modified. Printer object security and printer share security are linked at a very low level in WinNT/Win2K. Adding various types of permissions to a printer object will automatically add certain corresponding types of permissions to all printer shares associated with the printer object. These "linked" permissions are not identical, in that, if you grant one type of permissions on the printer object for a user/group, then a more generic set of permissions gets set on any associated printer shares. Security for printer objects can be managed. Security on printer shares should never be directly modified since the modifications will most likely be undone if the share's printer object security is ever directly modified.
300	Directory or file in a NTFS partition. This can be either a UNC folder/file specification [e.g. "\\server-name\share-name\some-folder\some-file"], or it can be a reference to a folder/file on a drive letter. If the referenced folder/file is on a drive letter that is mapped to a remote server, or it is a UNC specification for a folder/file on a remote server, then the "server-name" parameter's value must specify the name of the remote server [with a pair of leading backslash "\\" characters].
301	Directory in a NTFS partition, and all its subdirectories (*)
302	Directory in a NTFS partition, and all files in the directory (*)
303	Directory in a NTFS partition, and all its subdirectories, and all files in the directory and all its subdirectories (*)
400	Registry key. This should be the handle of an open registry key (opened with the RegOpenKey() function), or a predefined registry handle. (Registration Functions are listed in the WIL help file under "Registration Database Operations".)
401	Registry key, and all its subkeys (*). See object type 400.
500	Window station Use extreme caution when altering the security of a window station or desktop object. Improperly manipulating the security of a window station or desktop object may result in making your system unusable and may require a hard-reset of the system in order to regain access to the system console [e.g. the keyboard, mouse and monitor]
501	Desktop Use extreme caution when altering the security of a window station or desktop object. Improperly manipulating the security of a window station or desktop object may result in making your system unusable and may require a hard-reset of the system in order to regain access to the system console [e.g. the keyboard, mouse and monitor]
600	Service Display Name Manipulates the security settings on NT services.
601	Service Key Name Manipulates the security settings on NT services.

* Note: the object types 301, 302, 303 and 401 cannot be used to manipulate ACLs on resources that are located on a Win2K system. Whenever one of these object types is specified for a resource on a Win2K system, the object type will automatically be converted to either "300" or "400" as is appropriate. This restriction was implemented due to the fact that Win2K does have inheritable ACLs that do get automatically propagated to all child objects under a folder or registry key. Allowing a user to explicitly add/remove an ACE [which is also inheritable] to/from an entire hierarchy of folders & files or registry keys could have a negative effect by creating unexpected types of access or auditing ACLs.

Flags

The flags value is an integer bit mask value. The values of different flag bits may be bit-wise OR'd together if multiple flag bits are to be "set" [e.g. enabled] at the same time. The following flag bits are valid:

Flag bit number	Flag bit value when set/enabled	Flag bit meaning
0	1	A SID string has been passed in as the value of the "account-name" parameter.
5	32	Display a progress dialog box while removing permissions.
6	64	Force a 1 second delay between updates to the progress dialog box. Note: this flag slows down the processing to be able to see what was going on in the progress dialog
7	128	If folders or files are being handled [e.g. object type 300, 301, 302 or 303], then display long names instead of short 8.3 names.

Returns

The return value of wntAccessDel() will be 1 [@TRUE] if it successfully processes all of the resources that were specified.

Certain object types, namely folders & files and registry keys, can have recursive processing performed to remove an ACE from the DACL of multiple objects, such as when an entire subdirectory tree is processed or when a branch of the registry is processed. Also, on Win2K, ACL inheritance may cause recursive processing to happen even though only a single folder or registry key has had its DACL modified. If recursive processing is done and one or more child objects cannot have their DACLs properly accessed/modified, then wntAccessDel() will return a value of 0 [@FALSE]. The wntLastErrMsg() function should be called with an error code of "-1" specified to get the list of objects that could not be properly processed.

Please note that it is possible for wntAccessDel() to return a zero value and not cause the script to abort with an error. The only time that wntAccessDel() will raise an error that needs to be trapped with the use of ErrorMode(@OFF) is when the specific resource/share-name that has been specified cannot have its DACL modified properly. Any other errors that occur during recursive processing of child objects simply result in wntAccessDel() returning a zero value [@FALSE]. It is the programmer's responsibility to check the return value of wntAccessDel() and then execute any error handling code should a zero value be returned.

Note: The function wntAccessDel() cannot be used to delete inherited ACEs from the DACL of a folder, file or registry key. Per Microsoft's requirements, inherited ACEs can only be removed from an object in one of two ways. The first way is to delete the explicitly assigned ACE from which the ACE was inherited. This is done by working backup up the folder or registry key hierarchy looking for the explicilty assigned ACE on a parent folder/key and then deleting it when it is found. This will have the effect of removing all ACEs which were inherited from the explicitly assigned ACE. The second way to achieve this is to disable ACL inheritance on the specified folder/file/key, specifying that inherited ACEs are to be removed or else converted to explicitly assigned ACEs [which may then be deleted with wntAccessDel()]. Use the wntAccessMod() function with Request #2 to disable the ACL inheritance on a folder/file/key. Refer to the wntAccessMod() function documentation for more details.

Note: It is not possible for WinNT v3.51/v4.0 to properly manage the permissions on a remote Win2K [or newer] systems. Attempting to use the wnt[Access|Audit]*() functions on WinNT v3.51/v4.0 to view/modify the permissions on a remote Win2K [or newer] system will result in error 716 [Win2K or newer required] being raised.

Example: