File System Provider::GetShareProperties

File System Provider::GetShareProperties

Returns file system properties and Microsoft® Active Directory® security attributes for the specified share. Used by Microsoft® Provisioning Framework (MPF).

XML Input Schema
The following code fragment shows the format for sending data to this procedure. For more information on individual elements and attributes, see the Elements and Attributes table.
<executeData>1..1
  <shareName>1..1</shareName>
  <sourcePath machine="..">1..1</sourcePath>
</executeData>
XML Output Schema
The following code fragment shows the format for data this procedure returns. For more information on individual elements and attributes, see the Elements and Attributes table.
<executeData>1..1
  <result>1..1
	<properties comments=".." maxUser="..">1..1</properties>
	<security>1..1
	<acl>1..1
		<ace>0..unbounded
		<permission>1..unbounded</permission>
		<mode>1..1</mode>
		<trusteeForm>1..1</trusteeForm>
		<trustee>1..1</trustee>
		<trusteeType>0..1</trusteeType>
		<inheritance>0..unbounded</inheritance>
		<objectTypeName>0..1</objectTypeName>
		<inheritedObjectTypeName>0..1</inheritedObjectTypeName>
		</ace>
	</acl>
	</security>
  </result>
</executeData>
Elements and Attributes
The following table describes the XML elements and attributes. Unless otherwise indicated, the data type is string.
Element Description, relationships, and attributes

ace Description:
Access control entries (ACEs) for the share to retrieve attributes for.
Parent:
acl

Children:
inheritance (minOccurs="0" maxOccurs="*", output only)
inheritedObjectTypeName (minOccurs="0" maxOccurs="1", output only)
mode (minOccurs="1" maxOccurs="1", output only)
objectTypeName (minOccurs="0" maxOccurs="1", output only)
permission (minOccurs="1" maxOccurs="*", output only)
trustee (minOccurs="1" maxOccurs="1", output only)
trusteeForm (minOccurs="1" maxOccurs="1", output only)
trusteeType (minOccurs="0" maxOccurs="1", output only)

acl Description:
Discretionary access control list (DACL) or system access control list (SACL) for the share to retrieve attributes for. The returned list contains both inherited and non-inherited ACEs.
Parent:
security

Child:
ace (minOccurs="0" maxOccurs="*")

executeData Description:
Encapsulates the procedure's input and output data.
Children:
dirName (minOccurs="1" maxOccurs="1", input only)
result (minOccurs="1" maxOccurs="1", output only)
sourcePath (minOccurs="1" maxOccurs="1", input only)
inheritance
Description:
Set of bit flags that determines whether other containers or objects can inherit the access control entry (ACE) from the primary object to which the DACL or SACL is attached. This value can be either a number or an AceFlags string. (See the AceFlags table following the sample code.)
The value for this element corresponds to the inheritance portion (low-order byte) of the AceFlags member of the ACE_HEADER structure. This parameter can be NO_INHERITANCE to indicate that the ACE is not inheritable, or it can be a combination of the values from the AceFlags table following the sample code. An ace parent can have multiple inheritance elements whose values are concatenated by a bitwise OR to build a single inheritance value.

The following example creates an ACE with an inheritance value of 3.
<ace>
  <inheritance>SUB_OBJECTS_ONLY_INHERIT</inheritance>
  <inheritance>2</inheritance>
</ace>
AceFlags values:

0x0 NO_INHERITANCE Default. This ACE will not be inherited by other objects.

0x1 SUB_OBJECTS_ONLY_INHERIT Non-container objects contained by the primary object inherit the ACE.

0x2 SUB_CONTAINERS_ONLY_INHERIT Other containers contained by the primary object inherit the ACE.

0x3 SUB_CONTAINERS_AND_OBJECTS_INHERIT Both containers and non-container objects contained by the primary object inherit the ACE.

0x4 INHERIT_NO_PROPAGATE The SUB_OBJECTS_ONLY_INHERIT and SUB_CONTAINERS_ONLY_INHERIT flags are not propagated to an inherited ACE.

0x8 INHERIT_ONLY The ACE does not apply to the primary object to which the DACL or SACL is attached, but objects contained by the primary object inherit the ACE.

0x10 INHERITED_ACE The permission or restriction is inherited from the parent object.

Parent:
ace
inheritedObjectTypeName Description:
Identifies the type of objects that can inherit the ACE. If the value for the trusteeForm node is TRUSTEE_IS_OBJECTS_AND_NAME, inheritedObjectTypeName must be a valid lightweight directory access protocol (LDAP) display name in the Active Directory schema. For TRUSTEE_IS_OBJECTS_AND_SID, this must be an LDAP path or a globally unique identifier (GUID) of an extended right. If it begins with "LDAP://", the procedure gets the object and stores the "rightsGUID" of the object. Otherwise, the string must be a GUID string such as "{12345678-1234-1234-1234-123456789abc}".
There is no default value. The procedure will fail if this element exists and trusteeForm is not TRUSTEE_IS_OBJECTS_AND_NAME or TRUSTEE_IS_OBJECTS_AND_SID.

Parent:
ace

mode Description:
Indicates whether the DACL or SACL allows or denies the specified access rights. Specifies a value from the following ACCESS_MODE enumeration.

2 Indicates an ACCESS_ALLOWED_ACE that allows the specified rights.

3 Indicates an ACCESS_DENIED_ACE that denies the specified rights.

Parent:
ace

objectTypeName Description:
String that identifies the type of object, property set, or property protected by the ACE. If this ACE is inherited, it identifies the type of object, property set, or property protected by the inherited ACE. If the trusteeForm node is TRUSTEE_IS_OBJECTS_AND_NAME, objectTypeName must be a valid LDAP display name in the Active Directory schema. For TRUSTEE_IS_OBJECTS_AND_SID, this must be an LDAP path or GUID of an extended right. If it begins with "LDAP://", the procedure gets the object and stores the "rightsGUID" of the object. Otherwise, the string must be a GUID string such as "{12345678-1234-1234-1234-123456789abc}". The permission element should be ADS_RIGHT_DS_CONTROL_ACCESS when setting an extended right. There can be at most one of these elements. There is no default value. The procedure will fail if this element exists and trusteeForm is not TRUSTEE_IS_OBJECTS_AND_NAME or TRUSTEE_IS_OBJECTS_AND_SID.
Parent:
ace

permission Description:
Value containing standard, specific, and generic rights. These rights are used in ACEs and are the primary means of specifying the requested or granted access to an object. This value can be either a number or string from any of the following tables. Multiple permission elements can be concatenated by a bitwise OR to create a single value.

Standard and generic permissions (ACCESS_MASK):

0x00010000L DELETE Delete access

0x00020000L READ_CONTROL Read access to the owner, group, and discretionary access control list (DACL) of the security descriptor

0x00040000L WRITE_DAC Write access to the DACL

0x00080000L WRITE_OWNER Write access to owner

0x00100000L SYNCHRONIZE Microsoft® Windows NT® and Windows® 2000: Synchronize access

0x01000000L ACCESS_SYSTEM_SECURITY Access system security (ACCESS_SYSTEM_SECURITY). This flag is not a typical access type. It is used to indicate access to a SACL. This type of access requires the calling process to SE_SECURITY_NAME (Manage auditing and security log) privilege. If this flag is set in the access mask of an audit access ACE (successful or unsuccessful access), the SACL access will be audited.

0x02000000L MAXIMUM_ALLOWED Maximum allowed

0x10000000L GENERIC_ALL Generic all

0x20000000L GENERIC_EXECUTE Generic execute

0x40000000L GENERIC_WRITE Generic write

0x80000000L GENERIC_READ Generic read

Active Directory permissions (ADS_RIGHTS_ENUM):

0x1 ADS_RIGHT_DS_CREATE_CHILD The right to create children of the object. The ObjectType member of an ACE can contain a GUID that identifies the type of child object whose creation is being controlled. If ObjectType does not contain a GUID, the ACE controls the creation of all child object types.

0x2 ADS_RIGHT_DS_DELETE_CHILD The right to delete children of the object. The ObjectType member of an ACE can contain a GUID that identifies a type of child object whose deletion is being controlled. If ObjectType does not contain a GUID, the ACE controls the deletion of all child object types.

0x4 ADS_RIGHT_ACTRL_DS_LIST The right to list children of this object.

0x8 ADS_RIGHT_DS_SELF The right to modify the group membership of a group object.

0x10 ADS_RIGHT_DS_READ_PROP The right to read properties of the object. The ObjectType member of an ACE can contain a GUID that identifies a property set or property. If ObjectType does not contain a GUID, the ACE controls the right to read all of the object's properties.

0x20 ADS_RIGHT_DS_WRITE_PROP The right to write properties of the object. The ObjectType member of an ACE can contain a GUID that identifies a property set or property. If ObjectType does not contain a GUID, the ACE controls the right to write all of the object's properties.

0x40 ADS_RIGHT_DS_DELETE_TREE The right to delete all children of this object, regardless of the permission on the children.

0x80 ADS_RIGHT_DS_LIST_OBJECT The right to list an object. If the user is not granted such a right, the object is hidden from the user.

0x100 ADS_RIGHT_DS_CONTROL_ACCESS The right to perform an operation controlled by an extended access right. The ObjectType member of an ACE can contain a GUID that identifies the extended right. If ObjectType does not contain a GUID, the ACE controls the right to perform all extended right operations associated with the object.

0x10000 ADS_RIGHT_DELETE The right to delete the object.

0x20000 ADS_RIGHT_READ_CONTROL The right to read information from the security descriptor of the object, not including the information in the SACL.

0x40000 ADS_RIGHT_WRITE_DAC The right to modify the DACL in the object's security descriptor.

0x80000 ADS_RIGHT_WRITE_OWNER The right to assume ownership of the object. The user must be a trustee of the object. The user cannot transfer the ownership to other users.

0x100000 ADS_RIGHT_SYNCHRONIZE The right to use the object for synchronization. This enables a thread to wait until the object is in the signaled state.

0x1000000 ADS_RIGHT_ACCESS_SYSTEM_SECURITY The right to get or set the SACL in the object's security descriptor.

0x10000000 ADS_RIGHT_GENERIC_ALL The right to create or delete children, delete a subtree, read and write properties, examine children and the object itself, add and remove the object from the directory, and read or write with an extended right.

0x20000000 ADS_RIGHT_GENERIC_EXECUTE The right to list children of this object.

0x40000000 ADS_RIGHT_GENERIC_WRITE The right to write all the properties and write to the DACL. The user can add and remove the object to and from the directory.

0x80000000 ADS_RIGHT_GENERIC_READ The right to read from the security descriptor, examine the object as well as its children, and read all properties.

Registry permissions:

0x0001 KEY_QUERY_VALUE Permission to query subkey data.

0x0002 KEY_SET_VALUE Permission to set subkey data.

0x0004 KEY_CREATE_SUB_KEY Permission to create subkeys.

0x0008 KEY_ENUMERATE_SUB_KEYS Permission to enumerate subkeys.

0x0010 KEY_NOTIFY Permission for change notification.

0x0020 KEY_CREATE_LINK Permission to create a symbolic link.

0x20006 KEY_WRITE Combines the READ_CONTROL, KEY_SET_VALUE, and KEY_CREATE_SUB_KEY access rights.

0x20019 KEY_EXECUTE Permission for read access.

0x20019 KEY_READ Combines the READ_CONTROL, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY access rights.

0xF003F KEY_ALL_ACCESS Combines the KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, KEY_CREATE_SUB_KEY, KEY_CREATE_LINK, and KEY_SET_VALUE access rights, plus all the standard access rights except SYNCHRONIZE.

File system permissions:

0x0001 FILE_LIST_DIRECTORY, FILE_READ_DATA Right to read data from a file. For a directory, the right to list the contents of a directory.

0x0002 FILE_WRITE_DATA Right to write data to a file. For a directory, the right to create a file in a directory.

0x0004 FILE_ADD_SUBDIRECTORY, FILE_APPEND_DATA Right to append data to the file. For a directory, the right to create a subdirectory.

0x0008 FILE_READ_EA Right to read extended attributes.

0x0010 FILE_WRITE_EA Right to write extended attributes.

0x0020 FILE_EXECUTE Right to execute a program.

0x0020 FILE_TRAVERSE Right to execute a file. For a directory, the directory can be traversed.

0x0040 FILE_DELETE_CHILD For a directory, the right to delete a subdirectory.

0x0080 FILE_READ_ATTRIBUTES Right to read file attributes.

0x0100 FILE_WRITE_ATTRIBUTES Right to write file attributes.

0x120089 FILE_GENERIC_READ Combination of permissions.

0x1200A0 FILE_GENERIC_EXECUTE Combination of permissions.

0x120116 FILE_GENERIC_WRITE Combination of permissions.

Parent:
ace

properties Description:
Encapsulates miscellaneous properties of the share to retrieve attributes for.
Parent:
executeData

Attributes:

comments Optional. Comments on the share.

maxUser Optional. Maximum number of users permitted to access the share simultaneously. The value -1 denotes the maximum number of users allowed by the file system.

result Description:
Encapsulates the results of the get operation.
Parent:
executeData

Children:
properties (minOccurs="1" maxOccurs="1", output only)
security (minOccurs="1" maxOccurs="1", output only)

security Description:
Security information for the share.
Parent:
executeData

Child:
acl (minOccurs="1" maxOccurs="1")

shareName Description:
Name of the share to retrieve attributes for.
Parent:
executeData

sourcePath Description:
Share to retrieve attributes for.
Parent:
executeData

Attribute:

machine Required. Computer name of the share.

trustee Description:
Identifies the user, group, or program (such as a Microsoft® Win32® service) to which the ACE applies. Can be either a sAMAccountName, LDAP path or security ID (SID), depending on the value for the trusteeForm node. For TRUSTEE_IS_NAME or TRUSTEE_IS_OBJECTS_AND_NAME, trustee should be a valid sAMAccountName. For TRUSTEE_IS_SID or TRUSTEE_IS_OBJECTS_AND_SID, trustee must be a SID or LDAP path. If trustee begins with "LDAP://", the procedure assumes it is an LDAP path; otherwise, the procedure assumes trustee is a SID in string format. For LDAP path, the procedure gets the objectSid of the object and stores the SID.
Parent:
ace

trusteeForm Description:
Type of value in the trustee node. Specifies a value from the following TRUSTEE_FORM enumeration. If an objectTypeName or inheritedObjectTypeName is supplied, it should be either TRUSTEE_IS_OBJECTS_AND_NAME or TRUSTEE_IS_OBJECTS_AND_SID.

0 TRUSTEE_IS_SID trustee is the SID of the trustee.

1 TRUSTEE_IS_NAME trustee is the name of the trustee.

3 TRUSTEE_IS_OBJECTS_AND_SID trustee is the SID of the trustee and either objectTypeName or inheritedObjectTypeName is supplied.

4 TRUSTEE_IS_OBJECTS_AND_NAME trustee is the name of the trustee and either objectTypeName or inheritedObjectTypeName is supplied.

Parent:
ace

trusteeType Description:
Indicates whether the trustee is a user account, a group account, or the account type is unknown. Specifies a value from the TRUSTEE_TYPE enumeration. The default is TRUSTEE_IS_UNKNOWN.

0 TRUSTEE_IS_UNKNOWN Trustee type is unknown, but not necessarily invalid.

1 TRUSTEE_IS_USER Indicates a user.

2 TRUSTEE_IS_GROUP Indicates a group.

3 TRUSTEE_IS_DOMAIN Indicates an Active Directory or Windows NT domain.

4 TRUSTEE_IS_ALIAS Indicates an alias.

5 TRUSTEE_IS_WELL_KNOWN_GROUP Indicates a well-known group.

6 TRUSTEE_IS_DELETED Indicates a deleted account.

7 TRUSTEE_IS_INVALID Indicates an invalid trustee type.

8 TRUSTEE_IS_COMPUTER Indicates a computer.

Parent:
ace
See Also

CreateShare, DeleteShare, File System Provider, SetShareProperties

Top of Page
© 1999-2002 Microsoft Corporation. All rights reserved.