add advapi32/security documentation
James Hawkins
truiken at gmail.com
Wed Dec 15 15:14:29 CST 2004
Changelog
* Add security documentation.
--
James Hawkins
-------------- next part --------------
Index: dlls/advapi32/security.c
===================================================================
RCS file: /home/wine/wine/dlls/advapi32/security.c,v
retrieving revision 1.87
diff -u -r1.87 security.c
--- dlls/advapi32/security.c 8 Dec 2004 14:02:26 -0000 1.87
+++ dlls/advapi32/security.c 15 Dec 2004 21:55:32 -0000
@@ -375,18 +375,27 @@
/******************************************************************************
* AllocateAndInitializeSid [ADVAPI32.@]
*
- * PARAMS
- * pIdentifierAuthority []
- * nSubAuthorityCount []
- * nSubAuthority0 []
- * nSubAuthority1 []
- * nSubAuthority2 []
- * nSubAuthority3 []
- * nSubAuthority4 []
- * nSubAuthority5 []
- * nSubAuthority6 []
- * nSubAuthority7 []
- * pSid []
+ * Allocates and initializes a security identifier (SID) with up to eight
+ * subauthorities.
+ *
+ * PARAMS
+ * pIdentifierAuthority [I] Provides the top-level identifier authority
+ * value to set in the SID.
+ * nSubAuthorityCount [I] Number of subauthorities to place in the SID.
+ * nSubAuthority0 [I] Subauthority value to place in the SID.
+ * nSubAuthority1 [I] Subauthority value to place in the SID.
+ * nSubAuthority2 [I] Subauthority value to place in the SID.
+ * nSubAuthority3 [I] Subauthority value to place in the SID.
+ * nSubAuthority4 [I] Subauthority value to place in the SID.
+ * nSubAuthority5 [I] Subauthority value to place in the SID.
+ * nSubAuthority6 [I] Subauthority value to place in the SID.
+ * nSubAuthority7 [I] Subauthority value to place in the SID.
+ * pSid [I] Receives the pointer to the allocated and
+ * initialized SID struct.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI
AllocateAndInitializeSid( PSID_IDENTIFIER_AUTHORITY pIdentifierAuthority,
@@ -407,8 +416,14 @@
/******************************************************************************
* FreeSid [ADVAPI32.@]
*
+ * Frees a SID previously allocated using AllocateAndInitializeSid.
+ *
* PARAMS
- * pSid []
+ * pSid [I] Pointer to the SID struct to free.
+ *
+ * RETURNS
+ * Success: NULL
+ * Failure: pointer to the SID struct represented by pSid.
*/
PVOID WINAPI
FreeSid( PSID pSid )
@@ -420,10 +435,17 @@
/******************************************************************************
* CopySid [ADVAPI32.@]
*
+ * Copies a SID to a buffer.
+ *
* PARAMS
- * nDestinationSidLength []
- * pDestinationSid []
- * pSourceSid []
+ * nDestinationSidLength [I] Length, in bytes, of the buffer receiving the
+ * copy of the SID.
+ * pDestinationSid [O] Buffer that receives a copy of the SID.
+ * pSourceSid [I] SID struct to be copied.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI
CopySid( DWORD nDestinationSidLength, PSID pDestinationSid, PSID pSourceSid )
@@ -434,8 +456,15 @@
/******************************************************************************
* IsValidSid [ADVAPI32.@]
*
+ * Validates a SID by verifying that the revision number is within a known
+ * range, and that the number of subauthorities is less than the maximum.
+ *
* PARAMS
- * pSid []
+ * pSid [I] Pointer to the SID struct to validate.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero if the structure is not valid
*/
BOOL WINAPI
IsValidSid( PSID pSid )
@@ -445,10 +474,20 @@
/******************************************************************************
* EqualSid [ADVAPI32.@]
- *
+ *
+ * Tests two SID values for equality.
+ *
* PARAMS
- * pSid1 []
- * pSid2 []
+ * pSid1 [I] Pointer to the first SID struct.
+ * pSid2 [I] Pointer to the second SID struct.
+ *
+ * RETURNS
+ * Success: nonzero if the structures are equal
+ * Failure: zero if the structures are not equal.
+ *
+ * NOTES
+ * Two SIDS must match exactly to be considered equal.
+ * If either structure is invalid, the return value is undefined.
*/
BOOL WINAPI
EqualSid( PSID pSid1, PSID pSid2 )
@@ -458,6 +497,19 @@
/******************************************************************************
* EqualPrefixSid [ADVAPI32.@]
+ *
+ * Test two SID prefix values for equality.
+ *
+ * PARAMS
+ * pSid1 [I] Pointer to the first SID struct.
+ * pSid2 [I] Pointer to the second SID struct.
+ *
+ * RETURNS
+ * Success: nonzero if the prefixes are equal
+ * Failure: zero if the prefixes are not equal
+ *
+ * NOTES
+ * A SID prefix is the entire SID except for the last subauthority value.
*/
BOOL WINAPI EqualPrefixSid (PSID pSid1, PSID pSid2)
{
@@ -467,8 +519,15 @@
/******************************************************************************
* GetSidLengthRequired [ADVAPI32.@]
*
+ * Returns the length, in bytes, of the buffer required to store a SID with
+ * a specified number of subauthorities.
+ *
* PARAMS
- * nSubAuthorityCount []
+ * nSubAuthorityCount [I] Number of subauthorities to be stored in the SID.
+ *
+ * RETURNS
+ * Success: length, in bytes, of the buffer to store the SID
+ * Failure: function cannot fail
*/
DWORD WINAPI
GetSidLengthRequired( BYTE nSubAuthorityCount )
@@ -479,8 +538,16 @@
/******************************************************************************
* InitializeSid [ADVAPI32.@]
*
+ * Initializes a SID.
+ *
* PARAMS
- * pIdentifierAuthority []
+ * pSid [O] SID struct to be initialized.
+ * pIdentifierAuthority [I] SID_IDENTIFIER_AUTHORITY struct to set in the SID.
+ * nSubAuthorityCount [I] Number of subauthorities to set in the SID.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI
InitializeSid (
@@ -494,8 +561,17 @@
/******************************************************************************
* GetSidIdentifierAuthority [ADVAPI32.@]
*
+ * Returns a pointer to the SID_IDENTIFIER_AUTHORITY struct in a SID.
+ *
* PARAMS
- * pSid []
+ * pSid [I] Pointer to the SID to query.
+ *
+ * RETURNS
+ * Success: pointer to the SID_IDENTIFIER_AUTHORITY struct.
+ * Failure: undefined
+ *
+ * NOTES
+ * The function fails if the SID is invalid.
*/
PSID_IDENTIFIER_AUTHORITY WINAPI
GetSidIdentifierAuthority( PSID pSid )
@@ -506,9 +582,18 @@
/******************************************************************************
* GetSidSubAuthority [ADVAPI32.@]
*
+ * Returns a pointer to a specified subauthority in a SID.
+ *
* PARAMS
- * pSid []
- * nSubAuthority []
+ * pSid [I] Pointer to the SID to query.
+ * nSubAuthority [I] Index of the subauthority array element to get.
+ *
+ * RETURNS
+ * Success: pointer to the specified SID subauthority
+ * Failure: undefined
+ *
+ * NOTES
+ * The function fails if the SID is invalid or the index is out of bounds.
*/
PDWORD WINAPI
GetSidSubAuthority( PSID pSid, DWORD nSubAuthority )
@@ -519,8 +604,17 @@
/******************************************************************************
* GetSidSubAuthorityCount [ADVAPI32.@]
*
+ * Returns the subauthority count of a SID.
+ *
* PARAMS
- * pSid []
+ * pSid [I] Pointer to the SID to query.
+ *
+ * RETURNS
+ * Success: pointer to the subauthority count in the SID.
+ * Failure: undefined
+ *
+ * NOTES
+ * The function fails if the SID is invalid.
*/
PUCHAR WINAPI
GetSidSubAuthorityCount (PSID pSid)
@@ -531,8 +625,17 @@
/******************************************************************************
* GetLengthSid [ADVAPI32.@]
*
+ * Returns the length, in bytes, of a valid SID.
+ *
* PARAMS
- * pSid []
+ * pSid [I] SID struct whose length is returned.
+ *
+ * RETURNS
+ * Success: length, in bytes, of the SID if the SID is valid
+ * Failure: undefined
+ *
+ * NOTES
+ * The SID struct is assumed to be valid.
*/
DWORD WINAPI
GetLengthSid (PSID pSid)
@@ -548,9 +651,15 @@
/******************************************************************************
* InitializeSecurityDescriptor [ADVAPI32.@]
*
+ * Initializes a new security descriptor.
+ *
* PARAMS
- * pDescr []
- * revision []
+ * pDescr [O] SECURITY_DESCRIPTOR struct to initialize.
+ * revision [I] Revision level to assign to the security descriptor.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI
InitializeSecurityDescriptor( PSECURITY_DESCRIPTOR pDescr, DWORD revision )
@@ -561,6 +670,29 @@
/******************************************************************************
* MakeAbsoluteSD [ADVAPI32.@]
+ *
+ * Creates a security descriptor in absolute format by using a security
+ * descriptor in self-relative format as a template.
+ *
+ * PARAMS
+ * pSelfRelativeSD [I] SECURITY_DESCRIPTOR in self-relative format.
+ * pAbsoluteSD [O] Buffer that is filled with the main body of an
+ * absolute-format SD.
+ * lpdwAbsoluteSDSize [O] Size of the buffer pointed to by pAbsoluteSD.
+ * pDacl [O] Buffer filled with the DACL.
+ * lpdwDaclSize [O] Size of the buffer pointed to by pDacl.
+ * pSacl [O] Buffer filled with the SACL.
+ * lpdwSaclSize [O] Size of the buffer pointed to by pSacl.
+ * pOwner [O] Buffer filled with the SID of the owner of the
+ * absolute-format SD.
+ * lpdwOwnerSize [O] Size of the buffer pointed to by pOwner.
+ * pPrimaryGroup [O] Buffer filled with the SID of the absolute-format
+ * SD's primary group.
+ * lpdwPrimaryGroupSize [O] Size of the buffer pointed to by pPrimaryGroup.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI MakeAbsoluteSD (
IN PSECURITY_DESCRIPTOR pSelfRelativeSecurityDescriptor,
@@ -584,6 +716,20 @@
/******************************************************************************
* GetSecurityDescriptorLength [ADVAPI32.@]
+ *
+ * Returns the length, in bytes, of a structurally valid SD.
+ *
+ * PARAMS
+ * pSecurityDescriptor [I] SECURITY_DESCRIPTOR struct whose length the
+ * function returns.
+ *
+ * RETURN
+ * Success: length, in bytes, of the SECURITY_DESCRIPTOR struct.
+ * Failure: undefined
+ *
+ * NOTES
+ * The length includes the length of all associated structs.
+ * If the SECURITY_DESCRIPTOR struct is invalid, the function fails.
*/
DWORD WINAPI GetSecurityDescriptorLength( PSECURITY_DESCRIPTOR pDescr)
{
@@ -593,9 +739,19 @@
/******************************************************************************
* GetSecurityDescriptorOwner [ADVAPI32.@]
*
+ * Retrieves the owner information from a SD.
+ *
* PARAMS
- * pOwner []
- * lpbOwnerDefaulted []
+ * pSecurityDescriptor [I] SECURITY_DESCRIPTOR struct to query.
+ * pOwner [O] Pointer to a pointer to a SID that identifies
+ * the owner upon return.
+ * lpbOwnerDefaulted [O] Flag that is set to the value of the
+ * SE_OWNER_DEFAULTED flag in the
+ * SECURITY_DESCRIPTOR_CONTROL struct.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI
GetSecurityDescriptorOwner( PSECURITY_DESCRIPTOR pDescr, PSID *pOwner,
@@ -607,15 +763,38 @@
/******************************************************************************
* SetSecurityDescriptorOwner [ADVAPI32.@]
*
+ * Sets the owner information of an absolute-format SD.
+ *
* PARAMS
+ * pSecurityDescriptor [I/O] SECURITY_DESCRIPTOR struct whose owner is set.
+ * pOwner [I] SID struct for the SD's new primary owner.
+ * bOwnerDefaulted [I] Whether the owner info is derived from a default
+ * mechanism.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI SetSecurityDescriptorOwner( PSECURITY_DESCRIPTOR pSecurityDescriptor,
PSID pOwner, BOOL bOwnerDefaulted)
{
CallWin32ToNt (RtlSetOwnerSecurityDescriptor(pSecurityDescriptor, pOwner, bOwnerDefaulted));
}
+
/******************************************************************************
- * GetSecurityDescriptorGroup [ADVAPI32.@]
+ * GetSecurityDescriptorGroup [ADVAPI32.@]
+ *
+ * Retrieves the primary group info from a SD.
+ *
+ * PARAMS
+ * pSecurityDescriptor [I] SECURITY_DESCRIPTOR struct to query.
+ * pGroup [O] SID that identifies the primary group.
+ * lpbGroupDefaulted [O] Set to the value of the SE_GROUP_DEFAULTED flag in
+ * the SECURITY_DESCRIPTOR_CONTROL struct.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failuer: zero
*/
BOOL WINAPI GetSecurityDescriptorGroup(
PSECURITY_DESCRIPTOR SecurityDescriptor,
@@ -626,6 +805,18 @@
}
/******************************************************************************
* SetSecurityDescriptorGroup [ADVAPI32.@]
+ *
+ * Sets the primary group information of an absolute-format SD.
+ *
+ * PARAMS
+ * pSecurityDescriptor [I] SECURITY_DESCRIPTOR struct to set.
+ * pGroup [I] SID struct for the SD's new primary group.
+ * bGroupDefaulted [I] Whether the primary group info was derived from a
+ * default mechanism.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI SetSecurityDescriptorGroup ( PSECURITY_DESCRIPTOR SecurityDescriptor,
PSID Group, BOOL GroupDefaulted)
@@ -636,8 +827,14 @@
/******************************************************************************
* IsValidSecurityDescriptor [ADVAPI32.@]
*
+ * Determines whether the components of a SD are valid.
+ *
* PARAMS
- * lpsecdesc []
+ * pSecurityDescriptor [I] SECURITY_DESCRIPTOR struct to validate.
+ *
+ * RETURNS
+ * Success: nonzero if the components of the SD are valid
+ * Failure: zero if any of the components of the SD are invalid.
*/
BOOL WINAPI
IsValidSecurityDescriptor( PSECURITY_DESCRIPTOR SecurityDescriptor )
@@ -646,7 +843,20 @@
}
/******************************************************************************
- * GetSecurityDescriptorDacl [ADVAPI32.@]
+ * GetSecurityDescriptorDacl [ADVAPI32.@]
+ *
+ * Retrieves a pointer to the DACL in a specified SD.
+ *
+ * PARAMS
+ * pSecurityDescriptor [I] SECURITY_DESCRIPTOR struct that contains the DACL.
+ * lpbDaclPresent [O] Value that indicates the presence of a DACL.
+ * pDacl [O] Pointer to a pointer to an ACL.
+ * lpbDaclDefaulted [O] Flag set to the value of the SE_DACL_DEFAULTED flag
+ * in the SECURITY_DESCRIPTOR_CONTROL.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI GetSecurityDescriptorDacl(
IN PSECURITY_DESCRIPTOR pSecurityDescriptor,
@@ -659,7 +869,19 @@
}
/******************************************************************************
- * SetSecurityDescriptorDacl [ADVAPI32.@]
+ * SetSecurityDescriptorDacl [ADVAPI32.@]
+ *
+ * Sets information in a DACL.
+ *
+ * PARAMS
+ * pSecurityDescriptor [I/O] SECURITY_DESCRIPTOR struct to add the DACL to.
+ * bDaclPresent [I] Flag that indicates the presence of a DACL.
+ * pDacl [I] ACL struct that specifies the DACL for the SD.
+ * bDaclDefaulted [I] Flag that indicates the source of the DACL.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failrue: zero
*/
BOOL WINAPI
SetSecurityDescriptorDacl (
@@ -671,7 +893,21 @@
CallWin32ToNt (RtlSetDaclSecurityDescriptor (lpsd, daclpresent, dacl, dacldefaulted ));
}
/******************************************************************************
- * GetSecurityDescriptorSacl [ADVAPI32.@]
+ * GetSecurityDescriptorSacl [ADVAPI32.@]
+ *
+ * Retrives a pointer to the SACL in a specified SD.
+ *
+ * PARAMS
+ * pSecurityDescriptor [I] SECURITY_DESCRIPTOR struct that contains the SACL.
+ * lpbSaclPresent [O] Flag that indicates the presence of a SACL.
+ * pSacl [O] Pointer to a pointer to an ACL.
+ * lpbSaclDefaulted [O] Flag that is set to the value of the
+ * SE_SACL_DEFAULTED flag in the
+ * SECURITY_DESCRIPTOR_CONTROL.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI GetSecurityDescriptorSacl(
IN PSECURITY_DESCRIPTOR lpsd,
@@ -683,8 +919,20 @@
(PBOOLEAN)lpbSaclPresent, pSacl, (PBOOLEAN)lpbSaclDefaulted));
}
-/**************************************************************************
- * SetSecurityDescriptorSacl [ADVAPI32.@]
+/*****************************************************************************
+ * SetSecurityDescriptorSacl [ADVAPI32.@]
+ *
+ * Sets information in a SACL.
+ *
+ * PARAMS
+ * pSecurityDescriptor [I/O] SECURITY_DESCRIPTOR struct to add the SACL to.
+ * bSaclPresent [I] Indicates the presence of a SACL in the SD.
+ * pSacl [I] ACL struct that specifies the SACL for the SD.
+ * bSaclDefaulted [I] Indicates the source of the SACL.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failrue: zero
*/
BOOL WINAPI SetSecurityDescriptorSacl (
PSECURITY_DESCRIPTOR lpsd,
@@ -697,10 +945,17 @@
/******************************************************************************
* MakeSelfRelativeSD [ADVAPI32.@]
*
+ * Creates a SD in self-relative format by using a SD in absolute format as
+ * a template.
+ *
* PARAMS
- * lpabssecdesc []
- * lpselfsecdesc []
- * lpbuflen []
+ * pAbsoluteSD [I] SECURITY_DESCRIPTOR in absolute format.
+ * pSelfRelativeSD [O] Buffer filled with a SD in self-relative format.
+ * lpdwBufferLength [O] Size of the buffer pointed to by pSelfRelativeSD.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI
MakeSelfRelativeSD(
@@ -712,7 +967,19 @@
}
/******************************************************************************
- * GetSecurityDescriptorControl [ADVAPI32.@]
+ * GetSecurityDescriptorControl [ADVAPI32.@]
+ *
+ * Retrieves a SD control and revision information.
+ *
+ * PARAMS
+ * pSecurityDescriptor [I] SECURITY_DESCRIPTOR struct to query.
+ * pControl [O] SECURITY_DESCRIPTOR_CONTROL struct that receives
+ * the SD's control info.
+ * lpdwRevision [O] Receives the SD's revision value.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI GetSecurityDescriptorControl ( PSECURITY_DESCRIPTOR pSecurityDescriptor,
@@ -726,8 +993,19 @@
##############################
*/
-/*************************************************************************
+/******************************************************************************
* InitializeAcl [ADVAPI32.@]
+ *
+ * Initializes a new ACL struct.
+ *
+ * PARAMS
+ * pAcl [O] ACL struct to be initialized.
+ * nAclLength [I] Length, in bytes, of the buffer pointed to by pAcl.
+ * dwAclRevision [I] Revision level of the ACL struct being created.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
DWORD WINAPI InitializeAcl(PACL acl, DWORD size, DWORD rev)
{
@@ -735,7 +1013,20 @@
}
/******************************************************************************
- * AddAccessAllowedAce [ADVAPI32.@]
+ * AddAccessAllowedAce [ADVAPI32.@]
+ *
+ * Adds an access-allowed ACE to an ACL.
+ *
+ * PARAMS
+ * pAcl [I] Pointer to an ACL.
+ * dwAceRevision [I] Revision level of the ACL being modified.
+ * AccessMask [I] Mask of the access rights to be granted to the SID.
+ * pSid [I] SID representing a user, group, or logon account being
+ * granted access.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failrue: zero
*/
BOOL WINAPI AddAccessAllowedAce(
IN OUT PACL pAcl,
@@ -747,7 +1038,22 @@
}
/******************************************************************************
- * AddAccessAllowedAceEx [ADVAPI32.@]
+ * AddAccessAllowedAceEx [ADVAPI32.@]
+ *
+ * Adds an access-allowed ACE to the end of a DACL.
+ *
+ * PARAMS
+ * pAcl [I/O] Pointer to a DACL.
+ * dwAceRevision [I] Revision level of the DACL being modified.
+ * AceFlags [I] Set of bit flags that control ACE inheritance.
+ * AccessMask [I] Set of bit flags that specify the access rights that the
+ * new ACE allows for the SID.
+ * pSid [I] SID that identifies the user, group, or logon session to
+ * which the new ACE allows access.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI AddAccessAllowedAceEx(
IN OUT PACL pAcl,
@@ -760,7 +1066,21 @@
}
/******************************************************************************
- * AddAccessDeniedAce [ADVAPI32.@]
+ * AddAccessDeniedAce [ADVAPI32.@]
+ *
+ * Adds an access-denied ACE to and ACL.
+ *
+ * PARAMS
+ * pAcl [I/O] Pointer to an ACL.
+ * dwAceRevision [I] Revision level of the ACL being modified.
+ * AccessMask [I] Specifies the mask of access rights being denied to the
+ * specified SID.
+ * pSid [I] SID struct representing the user, group, or logon account
+ * being denied access.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI AddAccessDeniedAce(
IN OUT PACL pAcl,
@@ -772,7 +1092,22 @@
}
/******************************************************************************
- * AddAccessDeniedAceEx [ADVAPI32.@]
+ * AddAccessDeniedAceEx [ADVAPI32.@]
+ *
+ * Adds an access-denied ACE to the end of a DACL.
+ *
+ * PARAMS
+ * pAcl [I] Pointer to a DACL.
+ * dwAceRevision [I] Revision level of the DACL being modified.
+ * AceFlags [I] Set of bit flags that control ACE inheritance.
+ * AccessMask [I] Set of bit flags that specify the access rights that the
+ * new ACE denies to the specified SID.
+ * pSid [I] SID that identifies the user, group, or logon session to
+ * which the new ACE denies access.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI AddAccessDeniedAceEx(
IN OUT PACL pAcl,
@@ -785,7 +1120,21 @@
}
/******************************************************************************
- * AddAce [ADVAPI32.@]
+ * AddAce [ADVAPI32.@]
+ *
+ * Adds one ore more ACE to a specified ACL.
+ *
+ * PARAMS
+ * pAcl [I] Pointer to an ACL.
+ * dwAceRevision [I] Revision level of the ACL being modified.
+ * dwStartingAceIndex [I] Position in the ACL's list of ACEs at which to add
+ * new ACEs.
+ * pAceList [I] List of one or more ACEs to be added.
+ * nAceListLength [I] Size, in bytes, of the pAceList input buffer.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI AddAce(
IN OUT PACL pAcl,
@@ -799,6 +1148,16 @@
/******************************************************************************
* DeleteAce [ADVAPI32.@]
+ *
+ * Deletes an ACE from an ACL.
+ *
+ * PARAMS
+ * pAcl [I] Pointer to an ACL.
+ * dwAceIndex [I] The ACE to delete.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI DeleteAce(PACL pAcl, DWORD dwAceIndex)
{
@@ -806,7 +1165,17 @@
}
/******************************************************************************
- * FindFirstFreeAce [ADVAPI32.@]
+ * FindFirstFreeAce [ADVAPI32.@]
+ *
+ * Retrieves a pointer to the first free byte in an ACL.
+ *
+ * PARAMS
+ * pAcl [I] Pointer to an ACL.
+ * pAce [O] Pointer to a pointer to the first free position in the ACL.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI FindFirstFreeAce(IN PACL pAcl, LPVOID * pAce)
{
@@ -815,6 +1184,17 @@
/******************************************************************************
* GetAce [ADVAPI32.@]
+ *
+ * Obtains a pointer to an ACE in an ACL.
+ *
+ * PARAMS
+ * pAcl [I] Pointer to an ACL.
+ * dwAceIndex [I] Index of the ACE to be retrieved.
+ * pAce [O] Pointer to a pointer of the ACE.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failrue: zero
*/
BOOL WINAPI GetAce(PACL pAcl,DWORD dwAceIndex,LPVOID *pAce )
{
@@ -823,6 +1203,18 @@
/******************************************************************************
* GetAclInformation [ADVAPI32.@]
+ *
+ * Retrieves information about an ACL.
+ *
+ * PARAMS
+ * pAcl [I] Pointer to an ACL.
+ * pAclInformation [O] Buffer to receive requested information.
+ * nAclInformationLength [I] Size, in bytes, of pAclInformation buffer.
+ * dwAclInformationClass [I] Indicates the class of information requested.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI GetAclInformation(
PACL pAcl,
@@ -835,7 +1227,16 @@
}
/******************************************************************************
- * IsValidAcl [ADVAPI32.@]
+ * IsValidAcl [ADVAPI32.@]
+ *
+ * Validates an ACL.
+ *
+ * PARAMS
+ * pAcl [I] Pointer to an ACL struct to validate.
+ *
+ * RETURNS
+ * Success: nonzero if the ACL is valid
+ * Failure: zero if the ACL is invalid
*/
BOOL WINAPI IsValidAcl(IN PACL pAcl)
{
@@ -850,8 +1251,14 @@
/******************************************************************************
* AllocateLocallyUniqueId [ADVAPI32.@]
*
+ * Allocates a locally unique identifier (LUID).
+ *
* PARAMS
- * lpLuid []
+ * Luid [O] Pointer to a LUID struct that receives the allocated LUID.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI AllocateLocallyUniqueId( PLUID lpLuid )
{
@@ -953,7 +1360,7 @@
};
/******************************************************************************
- * LookupPrivilegeValueW [ADVAPI32.@]
+ * LookupPrivilegeValueW [ADVAPI32.@]
*
* See LookupPrivilegeValueA.
*/
@@ -991,14 +1398,14 @@
}
/******************************************************************************
- * LookupPrivilegeValueA [ADVAPI32.@]
+ * LookupPrivilegeValueA [ADVAPI32.@]
*
* Retrieves LUID used on a system to represent the privilege name.
*
* PARAMS
- * lpSystemName [I] Name of the system
- * lpName [I] Name of the privilege
- * lpLuid [O] Destination for the resulting LUID
+ * lpSystemName [I] Name of the system.
+ * lpName [I] Name of the privilege.
+ * lpLuid [O] Destination for the resulting LUID.
*
* RETURNS
* Success: TRUE. lpLuid contains the requested LUID.
@@ -1021,7 +1428,7 @@
/******************************************************************************
- * LookupPrivilegeNameA [ADVAPI32.@]
+ * LookupPrivilegeNameA [ADVAPI32.@]
*
* See LookupPrivilegeNameW
*/
@@ -1075,14 +1482,14 @@
}
/******************************************************************************
- * LookupPrivilegeNameW [ADVAPI32.@]
+ * LookupPrivilegeNameW [ADVAPI32.@]
*
* Retrieves the privilege name referred to by the LUID lpLuid.
*
* PARAMS
- * lpSystemName [I] Name of the system
- * lpLuid [I] Privilege value
- * lpName [O] Name of the privilege
+ * lpSystemName [I] Name of the system.
+ * lpLuid [I] Privilege value.
+ * lpName [O] Name of the privilege.
* cchName [I/O] Number of characters in lpName.
*
* RETURNS
@@ -1090,7 +1497,7 @@
* *lpLuid.
* Failure: FALSE.
*
- * REMARKS
+ * NOTES
* Only well-known privilege names (those defined in winnt.h) can be retrieved
* using this function.
* If the length of lpName is too small, on return *cchName will contain the
@@ -1140,15 +1547,17 @@
* Obtains Specified information about the security of a file or directory.
*
* PARAMS
- * lpFileName [I] Name of the file to get info for
- * RequestedInformation [I] SE_ flags from "winnt.h"
- * pSecurityDescriptor [O] Destination for security information
- * nLength [I] Length of pSecurityDescriptor
- * lpnLengthNeeded [O] Destination for length of returned security information
+ * lpFileName [I] Name of the file to get info for.
+ * RequestedInformation [I] SE_ flags from "winnt.h".
+ * pSecurityDescriptor [O] Destination for security information.
+ * nLength [I] Length of pSecurityDescriptor.
+ * lpnLengthNeeded [O] Destination for length of returned security
+ * information.
*
* RETURNS
* Success: TRUE. pSecurityDescriptor contains the requested information.
- * Failure: FALSE. lpnLengthNeeded contains the required space to return the info.
+ * Failure: FALSE. lpnLengthNeeded contains the required space to return
+ * the info.
*
* NOTES
* The information returned is constrained by the callers access rights and
@@ -1197,6 +1606,8 @@
/******************************************************************************
* LookupAccountSidA [ADVAPI32.@]
+ *
+ * See LookupAccountSidW.
*/
BOOL WINAPI
LookupAccountSidA(
@@ -1231,14 +1642,26 @@
/******************************************************************************
* LookupAccountSidW [ADVAPI32.@]
*
+ * Retrieves the name of the account for the input SID and the name of the
+ * first domain on which this SID is found.
+ *
* PARAMS
- * system []
- * sid []
- * account []
- * accountSize []
- * domain []
- * domainSize []
- * name_use []
+ * lpSystemName [I] Specifies the target computer.
+ * lpSid [I] Pointer to the SID to look up.
+ * lpName [O] Buffer that receives the account name that
+ * corresponds to the lpSid parameter.
+ * cchName [I/O] On input, specifies the size, in WCHARs, of
+ * lpName.
+ * lpReferencedDomainName [O] Buffer that receives the name of the domain
+ * where the account name was found.
+ * cchReferencedDomainName [I/O] On input, specifies the size, in WCHARs, of
+ * lpReferencedDomainName.
+ * peUse [O] Receives a SID_NAME_USE value that indicates
+ * the type of the account.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI
LookupAccountSidW(
@@ -1272,7 +1695,18 @@
/******************************************************************************
* SetFileSecurityA [ADVAPI32.@]
- * Sets the security of a file or directory
+ *
+ * Sets the security of a file or directory object.
+ *
+ * PARAMS
+ * lpFileName [I] File or directory to set security.
+ * SecurityInformation [I] SECURITY_INFORMATION struct that identifies the
+ * contents of the SD point to by pSecurityDescriptor.
+ * pSecurityDescriptor [I] SECURITY_DESCRIPTOR struct.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI SetFileSecurityA( LPCSTR lpFileName,
SECURITY_INFORMATION RequestedInformation,
@@ -1298,12 +1732,8 @@
/******************************************************************************
* SetFileSecurityW [ADVAPI32.@]
- * Sets the security of a file or directory
*
- * PARAMS
- * lpFileName []
- * RequestedInformation []
- * pSecurityDescriptor []
+ * See SetFileSecurityA.
*/
BOOL WINAPI
SetFileSecurityW( LPCWSTR lpFileName,
@@ -1347,11 +1777,17 @@
/******************************************************************************
* LsaOpenPolicy [ADVAPI32.@]
*
+ * Opens a handle to the policy object on a local or remote system.
+ *
* PARAMS
- * SystemName [I]
- * ObjectAttributes [I]
- * DesiredAccess [I]
- * PolicyHandle [I/O]
+ * SystemName [I] Name of the target system.
+ * ObjectAttributes [I] Specifies the common attributes.
+ * DesiredAccess [I] Specifies the requested access rights.
+ * PolicyHandle [I/O] Receives a handle to the policy object.
+ *
+ * RETURNS
+ * Success: STATUS_SUCCESS
+ * Failure: an NTSTATUS code, see MSDN
*/
NTSTATUS WINAPI
LsaOpenPolicy(
@@ -1372,6 +1808,17 @@
/******************************************************************************
* LsaQueryInformationPolicy [ADVAPI32.@]
+ *
+ * Retrieves information about a policy object.
+ *
+ * PARAMS
+ * PolicyHandle [I] Handle to a policy object.
+ * InformationClass [I] Type of information to retrieve.
+ * Buffer [O] Recieves the requested information.
+ *
+ * RETURNS
+ * Success: STATUS_SUCCESS
+ * Failure: an NTSTATUS code
*/
NTSTATUS WINAPI
LsaQueryInformationPolicy(
@@ -1463,6 +1910,24 @@
/******************************************************************************
* LsaLookupSids [ADVAPI32.@]
+ *
+ * Looks up the names that correspond to an array of SIDs.
+ *
+ * PARAMS
+ * PolicyHandle [I] Handle to a policy object.
+ * Count [I] Number of SIDs in the Sids array.
+ * Sids [I] Array of SID pointers to look up.
+ * ReferencedDomains [O] Contains in the struct an array that contains an
+ * entry for each domain in which a SID was found.
+ * Names [O] Contains in the struct an array that contains the
+ * name info for the corresponding entry in the Sids
+ * array.
+ *
+ * RETURNS
+ * Success: one of the following
+ * STATUS_SOME_NOT_MAPPED
+ * STATUS_SUCCESS
+ * Failure: an NTSTATUS code
*/
NTSTATUS WINAPI
LsaLookupSids(
@@ -1479,6 +1944,15 @@
/******************************************************************************
* LsaFreeMemory [ADVAPI32.@]
+ *
+ * Frees memory allocated for an output buffer by an LSA function call.
+ *
+ * PARAMS
+ * Buffer [I] Memory buffer that was allocated by an LSA function call.
+ *
+ * RETURNS
+ * Success: STATUS_SUCCESS
+ * Failure: an NTSTATUS code
*/
NTSTATUS WINAPI
LsaFreeMemory(IN PVOID Buffer)
@@ -1488,6 +1962,15 @@
}
/******************************************************************************
* LsaClose [ADVAPI32.@]
+ *
+ * Closes a handle to a policy or TrustedDomain object.
+ *
+ * PARAMS
+ * ObjectHandle [I] Handle to a policy object or a TrustedDomain.
+ *
+ * RETURNS
+ * Success: STATUS_SUCCESS
+ * Failure: an NTSTATUS code
*/
NTSTATUS WINAPI
LsaClose(IN LSA_HANDLE ObjectHandle)
@@ -1498,6 +1981,22 @@
/******************************************************************************
* LsaStorePrivateData [ADVAPI32.@]
+ *
+ * Stores or deletes the private data of a policy object under a specified
+ * registry key.
+ *
+ * PARAMS
+ * PolicyHandle [I] Handle to a policy object.
+ * KeyName [I] Name of the key under which the private data is stored.
+ * PrivateData [I] Private data to store.
+ *
+ * RETURNS
+ * Success: STATUS_SUCCESS
+ * Failure: an NTSTATUS code
+ *
+ * NOTES
+ * If PrivateData is NULL, the function deletes any private data stored under
+ * the key and deletes the key.
*/
NTSTATUS WINAPI LsaStorePrivateData( LSA_HANDLE PolicyHandle,
PLSA_UNICODE_STRING KeyName, PLSA_UNICODE_STRING PrivateData)
@@ -1508,6 +2007,18 @@
/******************************************************************************
* LsaRetrievePrivateData [ADVAPI32.@]
+ *
+ * Retrieves private data stored by the LsaStorePrivateData function.
+ *
+ * PARAMS
+ * PolicyHandle [I] Handle to a policy object.
+ * KeyName [I] Contains the name of the key where the private data is
+ * stored.
+ * PrivateData [I] Contains the private data.
+ *
+ * RETURNS
+ * Success: STATUS_SUCCESS
+ * Failure: an NTSTATUS code
*/
NTSTATUS WINAPI LsaRetrievePrivateData( LSA_HANDLE PolicyHandle,
PLSA_UNICODE_STRING KeyName, PLSA_UNICODE_STRING* PrivateData)
@@ -1519,8 +2030,15 @@
/******************************************************************************
* LsaNtStatusToWinError [ADVAPI32.@]
*
+ * Converts an NTSTATUS code returned by an LSA function to a Windows error
+ * code.
+ *
* PARAMS
- * Status [I]
+ * Status [I] An NTSTATUS code returned by an LSA function call.
+ *
+ * RETURNS
+ * Success: Windows error code that corresponds to the Status parameter
+ * Failure: ERROR_MR_MID_NOT_FOUND
*/
ULONG WINAPI
LsaNtStatusToWinError(NTSTATUS Status)
@@ -1544,8 +2062,14 @@
/******************************************************************************
* RevertToSelf [ADVAPI32.@]
*
+ * Terminates the impersonation of a client application.
+ *
* PARAMS
* void []
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI
RevertToSelf( void )
@@ -1556,6 +2080,17 @@
/******************************************************************************
* ImpersonateSelf [ADVAPI32.@]
+ *
+ * Obtains an access token that impersonates the security context of the
+ * calling process.
+ *
+ * PARAMS
+ * ImpersonationLevel [I] A SECURITY_IMPERSONATION_LEVEL enumerated type that
+ * supplies the impersonation level of the new token.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI
ImpersonateSelf(SECURITY_IMPERSONATION_LEVEL ImpersonationLevel)
@@ -1565,6 +2100,17 @@
/******************************************************************************
* ImpersonateLoggedOnUser [ADVAPI32.@]
+ *
+ * Lets the calling thread impersonate the security context of a logged-on
+ * user.
+ *
+ * PARAMS
+ * hToken [I] Handle to a primary or impersonation access token that
+ * represents a logged-on user.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI ImpersonateLoggedOnUser(HANDLE hToken)
{
@@ -1575,6 +2121,28 @@
/******************************************************************************
* AccessCheck [ADVAPI32.@]
*
+ * Determines whether a SD grants a specified set of access rights to the
+ * client identified by an access token.
+ *
+ * PARAMS
+ * pSecurityDescriptor [I] SECURITY_DESCRIPTOR struct against which access
+ * is checked.
+ * ClientToken [I] Handle to an impersonation toke that represents the
+ * client that is attempting to gain access.
+ * DesiredAccess [I] Access mask that specifies the access rights to
+ * check.
+ * GenericMapping [I] GENERIC_MAPPING associated with the object for
+ * which access is being checked.
+ * PrivilegeSet [O] Receives the privileges used to perform the access
+ * validation.
+ * PrivilegeSetLength [I] Size, in bytes, of PrivilegeSet parameter.
+ * GrantedAccess [O] Receives the granted access rights.
+ * AccessStatus [O] Receives the results of the access check.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
+ *
* FIXME check cast LPBOOL to PBOOLEAN
*/
BOOL WINAPI
@@ -1595,6 +2163,31 @@
/******************************************************************************
* AccessCheckByType [ADVAPI32.@]
+ *
+ * Determines whether a SD grants a specified set of access rights to the
+ * client identified by an access token.
+ *
+ * PARAMS
+ * pSecurityDescriptor [I] SECURITY_DESCRIPTOR against which access is
+ * checked.
+ * PrincipalSelfSid [I] Pointer to a SID.
+ * ClientToken [I] Handle to an impersonation token that represents
+ * the client trying to gain access.
+ * DesiredAccess [I] Access mask that specifies the access rights to
+ * check.
+ * ObjectTypeList [I] Array that identify the hierarchy of object
+ * types for which to check access.
+ * ObjectTypeListLength [I] Number of elements in the ObjectTypeList.
+ * GenericMapping [O] GENERIC_MAPPING struct for the object.
+ * PrivilegeSet [O] Receives the privileges used to perform access
+ * validation.
+ * PrivilegeSetLength [O] Size, in bytes, of PrivilegeSet.
+ * GrantedAccess [O] Receives the granted access rights.
+ * AccessStatus [O] Receives the results of the access check.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI AccessCheckByType(
PSECURITY_DESCRIPTOR pSecurityDescriptor,
@@ -1617,8 +2210,20 @@
}
-/*************************************************************************
+/******************************************************************************
* SetKernelObjectSecurity [ADVAPI32.@]
+ *
+ * Sets the security of a kernal object.
+ *
+ * PARAMS
+ * Handle [I] Handle to a kernel object for which security info
+ * is set.
+ * SecurityInformation [I] Components of the SD to set.
+ * SecurityDescriptor [I] SECURITY_DESCRIPTOR that contains the new info.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI SetKernelObjectSecurity (
IN HANDLE Handle,
@@ -1630,7 +2235,22 @@
/******************************************************************************
- * AddAuditAccessAce [ADVAPI32.@]
+ * AddAuditAccessAce [ADVAPI32.@]
+ *
+ * Adds a system-audit ACE to a system ACL. The access of an SID is audited.
+ *
+ * PARAMS
+ * pAcl [I/O] Pointer to an ACL.
+ * dwAceRevision [I] Revision level of the ACL being modified.
+ * dwAccessMask [I] Access rights to be audited.
+ * pSid [I] SID representing the process whose access is being
+ * audited.
+ * bAuditSuccess [I] Whether successful access attempts are to be audited.
+ * bAuditFailure [I] Whether unsuccessful access attempts are to be audited.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI AddAuditAccessAce(
IN OUT PACL pAcl,
@@ -1646,6 +2266,22 @@
/******************************************************************************
* LookupAccountNameA [ADVAPI32.@]
+ *
+ * Retrieves an SID for the account and the name of the domain on which the
+ * account was found.
+ *
+ * PARAMS
+ * lpSystemName [I] Specifies the name of the system.
+ * lpAccountName [I] Specifies the account name.
+ * Sid [O] The SID that corresponds to the account name.
+ * cbSid [I/O] Size of the Sid buffer.
+ * ReferencedDomainName [O] Name of the domain where the account name is.
+ * cchReferencedDomainName [I/O] Size, in CHARs, of ReferenceDomainName.
+ * peUse [O] Indicates the type of the account.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI
LookupAccountNameA(
@@ -1705,6 +2341,19 @@
/******************************************************************************
* PrivilegeCheck [ADVAPI32.@]
+ *
+ * Determines whether a specified set of privileges are enabled in an access
+ * token.
+ *
+ * PARAMS
+ * ClientToken [I] Access token representing a client process.
+ * RequiredPrivileges [I] PRIVILEGE_SET struct.
+ * pfResults [O] Indicates whether any or all of the specified
+ * privileges are enabled in the access token.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI PrivilegeCheck( HANDLE ClientToken, PPRIVILEGE_SET RequiredPrivileges, LPBOOL pfResult)
{
@@ -1716,6 +2365,27 @@
/******************************************************************************
* AccessCheckAndAuditAlarmA [ADVAPI32.@]
+ *
+ * Determines whether a SD grants a specified set of access rights to the
+ * client being impersonated by the calling thread.
+ *
+ * PARAMS
+ * SubsystemName [I] Name of the subsystem calling the function.
+ * HandleId [I] Client's handle to the object.
+ * ObjectTypeName [I] Type of object being created or accessed.
+ * ObjectName [I] Name of the object being created or accessed.
+ * SecurityDescriptor [I] SECURITY_DESCRIPTOR to check.
+ * DesiredAccess [I] Access rights to check.
+ * GenericMapping [I] GENERIC_MAPPING associated with the checked object.
+ * ObjectCreation [I] Determines whether to create a new object when
+ * access is granted.
+ * GrantedAccess [O] Receives the granted access rights.
+ * AccessStatus [O] Receives the results of the access check.
+ * pfGenerateOnClose [O] Flag set by the audit-generation.
+ *
+ * RETURNS
+ * Success: nonzero
+ * Failure: zero
*/
BOOL WINAPI AccessCheckAndAuditAlarmA(LPCSTR Subsystem, LPVOID HandleId, LPSTR ObjectTypeName,
LPSTR ObjectName, PSECURITY_DESCRIPTOR SecurityDescriptor, DWORD DesiredAccess,
@@ -1731,6 +2401,8 @@
/******************************************************************************
* AccessCheckAndAuditAlarmW [ADVAPI32.@]
+ *
+ * See AccessCheckAndAuditAlarmA.
*/
BOOL WINAPI AccessCheckAndAuditAlarmW(LPCWSTR Subsystem, LPVOID HandleId, LPWSTR ObjectTypeName,
LPWSTR ObjectName, PSECURITY_DESCRIPTOR SecurityDescriptor, DWORD DesiredAccess,
@@ -1747,6 +2419,22 @@
/******************************************************************************
* GetSecurityInfo [ADVAPI32.@]
+ *
+ * Retrieves a copy of the SD for an object specified by a handle.
+ *
+ * PARAMS
+ * handle [I] Handle to the object to query.
+ * ObjectType [I] Indicates the tpe of object.
+ * SecurityInfo [I] Type of security info to retrieve.
+ * ppsidOwner [O] Owner SID of the SD.
+ * ppsidGroup [O] Primary group SID of the SD.
+ * ppDacl [O] DACL of the SD.
+ * ppSacl [O] SACL of the SD.
+ * ppSecurityDescriptor [O] Security descriptor of the object.
+ *
+ * RETURNS
+ * Success: ERROR_SUCCESS
+ * Failure: nonzero error code from winerror.h
*/
DWORD WINAPI GetSecurityInfo(
HANDLE hObject, SE_OBJECT_TYPE ObjectType,
@@ -1760,7 +2448,7 @@
}
/******************************************************************************
- * GetSecurityInfoExW [ADVAPI32.@]
+ * GetSecurityInfoExW [ADVAPI32.@]
*/
DWORD WINAPI GetSecurityInfoExW(
HANDLE hObject, SE_OBJECT_TYPE ObjectType,
@@ -1775,6 +2463,15 @@
/******************************************************************************
* BuildTrusteeWithSidA [ADVAPI32.@]
+ *
+ * Initializes a TRUSTEE struct.
+ *
+ * PARAMS
+ * pTrustee [I/O] TRUSTEE sruct to initialize.
+ * pSid [I] SID struct that identifies the trustee.
+ *
+ * RETURNS
+ * Does not return a value.
*/
VOID WINAPI BuildTrusteeWithSidA(PTRUSTEEA pTrustee, PSID pSid)
{
@@ -1789,6 +2486,8 @@
/******************************************************************************
* BuildTrusteeWithSidW [ADVAPI32.@]
+ *
+ * See BuildTrusteeWithSidA.
*/
VOID WINAPI BuildTrusteeWithSidW(PTRUSTEEW pTrustee, PSID pSid)
{
@@ -1803,6 +2502,16 @@
/******************************************************************************
* BuildTrusteeWithNameA [ADVAPI32.@]
+ *
+ * Initializes a TRUSTEE struct.
+ *
+ * PARAMS
+ * pTrustee [I/O] TRUSTEE struct to initialize.
+ * pName [I] Name of the trustee for the ptstrName member of the TRUSTEE
+ * struct.
+ *
+ * RETURNS
+ * Does not return a value.
*/
VOID WINAPI BuildTrusteeWithNameA(PTRUSTEEA pTrustee, LPSTR name)
{
@@ -1817,6 +2526,8 @@
/******************************************************************************
* BuildTrusteeWithNameW [ADVAPI32.@]
+ *
+ * See BuildTrusteeWithNameA.
*/
VOID WINAPI BuildTrusteeWithNameW(PTRUSTEEW pTrustee, LPWSTR name)
{
@@ -1831,6 +2542,20 @@
/******************************************************************************
* SetEntriesInAclA [ADVAPI32.@]
+ *
+ * Creates a new ACL by merging new access control or audit control info into
+ * an existing ACL struct.
+ *
+ * PARAMS
+ * cCountOfExplicitEntries [I] Number of EXPLICIT_ACCESS structs.
+ * pListOfExplicitEntries [I] Array of EXPLICIT_ACCESS structs that describe
+ * the access control info to merge.
+ * OldAcl [I] Pointer to the existing ACL.
+ * NewAcl [O] Receives a pointer to the new ACL.
+ *
+ * RETURNS
+ * Success: ERROR_SUCCESS
+ * Failure: nonzero error code defined in winerror.h
*/
DWORD WINAPI SetEntriesInAclA( ULONG count, PEXPLICIT_ACCESSA pEntries,
PACL OldAcl, PACL* NewAcl )
@@ -1841,6 +2566,8 @@
/******************************************************************************
* SetEntriesInAclW [ADVAPI32.@]
+ *
+ * See SetEntiresInAclA.
*/
DWORD WINAPI SetEntriesInAclW( ULONG count, PEXPLICIT_ACCESSW pEntries,
PACL OldAcl, PACL* NewAcl )
@@ -1851,6 +2578,21 @@
/******************************************************************************
* SetNamedSecurityInfoA [ADVAPI32.@]
+ *
+ * Sets specified security info in the SD of a specified object.
+ *
+ * PARAMS
+ * pObjectName [I] Name of the object to set security info.
+ * ObjectType [I] Type of object named by the PObjectName parameter.
+ * SecurityInfo [I] Type of security information to set.
+ * psidOwner [I] Owner of the object.
+ * psidGroup [I] Primary group of the object.
+ * pDacl [I] New DACL for the object.
+ * pSacl [I] New SACL for the object.
+ *
+ * RETURNS
+ * Success: ERROR_SUCCESS
+ * Failure: nonzero error code defined in winerror.h
*/
DWORD WINAPI SetNamedSecurityInfoA(LPSTR pObjectName,
SE_OBJECT_TYPE ObjectType, SECURITY_INFORMATION SecurityInfo,
@@ -1886,12 +2628,12 @@
* been granted or not.
*
* PARAMS
- * GrantedAccess [I] The permissions that have been granted.
- * DesiredAccess [I] The permissions that you want to have.
+ * GrantedAccess [I] The permissions that have been granted.
+ * DesiredAccess [I] The permissions that you want to have.
*
* RETURNS
- * Nonzero if any of the permissions have been granted, zero if none of the
- * permissions have been granted.
+ * Nonzero if any of the permissions have been granted, zero if none of the
+ * permissions have been granted.
*/
BOOL WINAPI AreAnyAccessesGranted( DWORD GrantedAccess, DWORD DesiredAccess )
@@ -1901,6 +2643,8 @@
/******************************************************************************
* SetNamedSecurityInfoW [ADVAPI32.@]
+ *
+ * see SetNamedSecurityInfoA.
*/
DWORD WINAPI SetNamedSecurityInfoW(LPWSTR pObjectName,
SE_OBJECT_TYPE ObjectType, SECURITY_INFORMATION SecurityInfo,
@@ -1913,6 +2657,18 @@
/******************************************************************************
* GetExplicitEntriesFromAclA [ADVAPI32.@]
+ *
+ * Retrieves an array of structs that describe the ACEs in an ACL.
+ *
+ * PARAMS
+ * pacl [I] ACE struct to get ACE information.
+ * pcCountOfExplicitEntries [O] Receives number of EXPLICIT_ACCES structs.
+ * pListOfExplicitEntries [O] Receives pointer to array of EXPLICIT_ACCESS
+ * structs that describe the ACEs.
+ *
+ * RETURNS
+ * Success: ERROR_SUCCESS
+ * Failure: a nonzero error code defined in winerror.h
*/
DWORD WINAPI GetExplicitEntriesFromAclA( PACL pacl, PULONG pcCountOfExplicitEntries,
PEXPLICIT_ACCESSA* pListOfExplicitEntries)
@@ -1923,6 +2679,8 @@
/******************************************************************************
* GetExplicitEntriesFromAclW [ADVAPI32.@]
+ *
+ * See GetExplicitEntriesFromAclA.
*/
DWORD WINAPI GetExplicitEntriesFromAclW( PACL pacl, PULONG pcCountOfExplicitEntries,
PEXPLICIT_ACCESSW* pListOfExplicitEntries)
More information about the wine-patches
mailing list