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