Takes/sets ownership of an object.
wntOwnerSet(server-name, reg-key, resource-name, object-type, account-name[, flags])
Parameters:
(s) server-name: Name of a network file server or empty string ("") to indicate the current machine.
(i) reg-key: Handle of an open registry key or 0 [zero]. See below.
(s) resource-name: Identifies the object to be modified.
(i) object-type: Identifies the object type of the 'resource/share-name' object. See below.
(s) account-name: Name of a user or a group to whom ownership of the object is to be assigned. If necessary, it can be fully qualified as 'server\user'.
(i) flags: [optional] Controls behavior of the function. See below.
(i) 1 [@TRUE] or 0 [@FALSE]. See below
Server-Name
All attempts to work with ownership settings on remote computers will require that those remote computers have the "Server" service running.
Reg-key
If the object-type is 400 then the value of this parameter may contain the value of a registry key handle or zero. The resource-name parameter may also contain a string representing the name of a subkey path located under the key identified by the handle value passed in for the value of this parameter. If this parameter's value is zero then a registry key handle may be passed in [as a string value] as the value of the resource-name parameter. Registry key handles may be obtained using the RegOpenKey() function, the RegConnect() function or one of the pre-defined registry key handle values may be used.
If the object-type is not 400 then this parameter's value should be zero.
Resource-name
This parameter specifies the name of the resource for which ownership information is to be obtained. Refer to the object-type table for a description of the format in which various names have to be specified in order for them to be properly handled by this function.
Object-Type
|
Object-type |
Resource/share-name description |
|
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].
Surprise! Printer objects do have ownership, both individual ownership and group ownership, just like folders, files and registry keys. You can now get/set the ownership information on printer objects.
|
|
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. |
Please note that the legacy object types of 350 and 450 are still supported. Specifying an object type of 350 or 450 is the same as specifying an object type of 300 or 400 and having a flags bit mask value with flag bit #1 [value of 2] enabled. If you want to perform a recursive processing of folders & files or registry keys to change their ownership and reset their permissions at the same time then you must specify an object type of 301, 302, 303 or 401 as well as a flags bit mask value that has flag bit #1 [value of 2] enabled.
Account-name
If the value of 'account-name' is specified as an empty string then the ownership of the object will be changed to be the account that the user logged on with. If the user logged on with one account but is now impersonating another account then a blank string passed in as 'account-name' will result in the ownership of the object being changed to be the account that the user is currently impersonating.
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.
|
|
1 |
2 |
"Zap" the permissions on the specified object. This means that in addition to setting the ownership of the specified object, the DACL of the object will also have all explicitly assigned permissions records [e.g. ACEs] removed from it. Inherited permissions on Win2K [and newer] will not be removed from the DACL as a result of enabling this flag bit. This change to the DACL is done after the ownership of the object has been modified.
|
|
4 |
16 |
When this flag bit is enabled, the object's group ownership information will be modified in place of the object's individual ownership information. All securable objects under WinNT / Win2K [and newer] have both an [individual] owner and group owner. Enabling this flag simply results in modifying the group ownership information, and this flag bit may be used in combination with any of the other flag bits.
Please note that there are very few administration tools under WinNT/Win2K that even display this information, let alone tools that allow you to change this information. Modify the group ownership information at your own risk!
|
|
5 |
32 |
Display a progress dialog box while changing ownership [and possibly zapping the 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.
|
Here are some common flags values:
If you want to take [individual] ownership of the object, flags = 0 and 'account-name' may be specified as either the account name that you used to logon with or it may be a blank string [e.g. ""].
If you want to set the group ownership of the object, flags = 16 and 'account-name" should be specified as either a group account name [e.g. "Power Users"] or as a user account name.
If you want to set the [individual] ownership of an object using a SID string in place of an account name, flags = 1 and 'account-name' contains the SID string value.
If you want to set the group ownership of an object using a SID string in place of an account name, flags = 17 and 'account-name' contains the SID string value.
In the previously mentioned scenarios, adding a value of "2" to the flags value would result in the removal of any explicitly assigned permissions on the specified object. On Win2K [and newer], inherited permissions would remain unchanged.
The return value of wntOwnerSet() 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 set the ownership on an entire subfolder hierarchy or on an entire branch of the registry. 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 by enabling the "Zap Permissions" flag bit [flag bit #1, value = 2]. If recursive processing is done and one or more child objects cannot have their ownership properly modified or their DACLs cannot be properly accessed/modified, then wntOwnerSet() 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 wntOwnerSet() to return a zero value and not cause the script to abort with an error. The only time that wntOwnerSet() 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 ownershipr or DACL modified properly. Any other errors that occur during recursive processing of child objects simply result in wntOwnerSet() returning a zero value [@FALSE]. It is the programmer's responsibility to check the return value of wntOwnerSet() and then execute any error handling code should a zero value be returned.
Note:
There are some conditions requirements that have an effect on what types of ownership changes may be made with this function.
One or more of the following conditions must be satisfied to be able to use this function successfully:
· you have WRITE_OWNER access, and you are assigning ownership to yourself, and you are not the Administrator account [e.g. your SID is not "S-1-5-32-500"], or
· you have enabled SeTakeOwnershipPrivilege, and you are assigning ownership to yourself, and you are not the Administrator account [e.g. your SID is not "S-1-5-32-500"], or
· you have enabled SeRestorePrivilege. In this case, you can assign ownership to any SID that you take a fancy to.
The function wntSetOwner() will attempt to enable both SeTakeOwnershipPrivilege and SeRestorePrivilege if it can do so. If it fails to enable either of these privileges no errors will be returned, but the attempt at setting the ownership will then be constrained by the first condition listed above.
; Load Appropriate Extender AddExtender('wwwnt34i.dll',0,'wwwnt64i.dll')
;For a file – explicitly set the ownership: ErrorMode(@OFF) Result = wntOwnerSet("", 0, "f:\test\myfile.txt", 300, "Administrators", 0) RC = LastError() ErrorMode(@ON) Message("Set Ownership",StrCat("Result = ",Result,"; LastError = ",RC))
;For a file – current user takes ownership: ErrorMode(@OFF) Result = wntOwnerSet("", 0, "f:\test\myfile.txt", 300, "", 0) RC = LastError() ErrorMode(@ON) Message("Set Ownership",StrCat("Result = ",Result,"; LastError = ",RC))
;For a registry key – explicitly set the ownership: ErrorMode(@OFF) Result = wntOwnerSet("", @REGMACHINE, "Software\Test", 400, "Administrators", 0) RC = LastError() ErrorMode(@ON) Message("Set Ownership",StrCat("Result = ",Result,"; LastError = ",RC))
;For a registry key – current user takes ownership: ErrorMode(@OFF) Result = wntOwnerSet("", @REGMACHINE, "Software\Test", 400, "", 0) RC = LastError() ErrorMode(@ON) Message("Set Ownership",StrCat("Result = ",Result,"; LastError = ",RC)) Exit