Win32-security 0.1 → 0.1.1

raw patch · 5 files changed

+35/−9 lines, 5 files

Files

• Win32-security.cabal +1/−1
• cbits/Win32Security.c +2/−2
• src/System/Win32/Security/AccessControl.hsc +14/−3
• src/System/Win32/Security/SecurityInfo.hsc +17/−2
• src/System/Win32/Security/Sid.hsc +1/−1

@@ -1,5 +1,5 @@ name:             Win32-security
-version:          0.1
+version:          0.1.1
 synopsis:         Haskell bindings to a security-related functions of the Windows API
 license:          MIT
 license-file:     LICENSE

@@ -1,9 +1,9 @@ #include "Win32Security.h"
 
-void LocalFreeFinaliser(void* p) {
+void HS_Win32Security_LocalFreeFinaliser(void* p) {
   LocalFree(p);
 }
 
-void CloseHandleFinaliser(HANDLE h) {
+void HS_Win32Security_CloseHandleFinaliser(HANDLE h) {
   CloseHandle(h);
 }

@@ -28,6 +28,7 @@ import System.Win32.Security.Sid
 import System.Win32.Types
 import System.IO.Unsafe
+import qualified System.Win32.Error as E -- documentation comments
 import qualified System.Win32.Error.Foreign as E
 
 #include <windows.h>
@@ -124,9 +125,13 @@       withSidPtr sid $ \pSid ->
         copyBytes aceSidPtr pSid sidLength
 
--- | Creates an Acl from a list of access control entries. ACL revision is assumed to be ACL_REVISION because
--- ACL_REVISION_DS is not supported yet.
-aclFromList :: [Ace] -> Acl
+-- | Creates an Acl from a list of access control entries. ACL revision is
+-- assumed to be ACL_REVISION because ACL_REVISION_DS is not supported yet.
+aclFromList :: [Ace]
+    -> Acl
+    -- ^ This function will throw a 'E.Win32Exception' exception when the
+    -- internal Win32 call returns an error condition. Microsoft's
+    -- documentation does not list which errors are likely to occur.
 aclFromList aces =
   let acesAndSizes = map (\ace -> (ace, aceSize ace)) aces
       aclSize = #{size ACL} + (sum $ map snd acesAndSizes)
@@ -142,6 +147,12 @@         acesAndSizes
     return $ Acl $ withForeignPtr aclData
 
+-- | Official prototype:
+-- BOOL WINAPI InitializeAcl(
+--   _Out_  PACL pAcl,
+--   _In_   DWORD nAclLength,
+--   _In_   DWORD dwAclRevision
+-- );
 foreign import WINDOWS_CCONV unsafe "windows.h InitializeAcl"
   c_InitializeAcl
     :: PACL -- pAcl

@@ -35,6 +35,7 @@ import System.Win32.Security.Sid
 import System.Win32.Security.AccessControl
 import qualified Data.Text as T
+import qualified System.Win32.Error as E -- documentation comments
 import qualified System.Win32.Error.Foreign as E
 import qualified System.Win32.Security.MarshalText as T
 
@@ -100,7 +101,11 @@   , securityInfoDescriptor :: SecurityDescriptor
   }
 
-getNamedSecurityInfo :: T.Text -> SecurityObjectType -> SecurityInformation -> IO GetSecurityInfoResult
+getNamedSecurityInfo :: T.Text -> SecurityObjectType -> SecurityInformation
+    -> IO GetSecurityInfoResult
+    -- ^ This function will throw a 'E.Win32Exception' exception when the
+    -- internal Win32 call returns an error condition. Microsoft's
+    -- documentation does not list which errors are likely to occur.
 getNamedSecurityInfo objectName (SecurityObjectType objectType) (SecurityInformation securityInfo) =
   T.useAsPtr0 objectName $ \pObjectName ->
   alloca $ \ppSidOwner ->
@@ -145,7 +150,7 @@       }
 
 {-# CFILES cbits/Win32Security.c #-}
-foreign import ccall "Win32Security.h &LocalFreeFinaliser"
+foreign import ccall "Win32Security.h &HS_Win32Security_LocalFreeFinaliser"
   localFreeFinaliser :: FunPtr (Ptr a -> IO ())
 
 data SetSecurityInfoAcl
@@ -182,6 +187,16 @@       ProtectedAcl x -> withAclPtr x act
       UnprotectedAcl x -> withAclPtr x act
 
+-- | Official prototype:
+-- DWORD WINAPI SetNamedSecurityInfo(
+--   _In_      LPTSTR pObjectName,
+--   _In_      SE_OBJECT_TYPE ObjectType,
+--   _In_      SECURITY_INFORMATION SecurityInfo,
+--   _In_opt_  PSID psidOwner,
+--   _In_opt_  PSID psidGroup,
+--   _In_opt_  PACL pDacl,
+--   _In_opt_  PACL pSacl
+-- );
 foreign import WINDOWS_CCONV "windows.h SetNamedSecurityInfoW"
   c_SetNamedSecurityInfoW
     :: LPWSTR -- pObjectName

@@ -258,7 +258,7 @@       act pSid
 
 {-# CFILES cbits/HsWin32.c #-}
-foreign import ccall "HsWin32.h &CloseHandleFinaliser"
+foreign import ccall "HsWin32.h &HS_Win32Security_CloseHandleFinaliser"
     c_CloseHandleFinaliser :: FunPtr (Ptr a -> IO ())
 
 foreign import WINDOWS_CCONV unsafe "windows.h GetTokenInformation"