-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Alternative error handling for Win32 foreign calls
--   
--   This package provides an alternative to the Win32 library's error
--   handling mechanism. The goal is to provide a nearly drop-in
--   replacement for Win32's error-handling functions while offering the
--   following benefits:
--   
--   <ul>
--   <li>Ability to distinguish between different Win32 error codes.</li>
--   <li>Ability to catch Win32 exceptions separately from other exception
--   types.</li>
--   <li>Ability to query for the generating function's name and standard
--   system error massage associated with the exception.</li>
--   </ul>
@package Win32-errors
@version 0.2.2.6


-- | This module provides functions which can be used as drop-in
--   replacements for Win32 when writing wrappers to foreign imports.
--   
--   You will likely need to import modules from Win32 as well. To avoid
--   accidentally calling the standard error handling functions it's a good
--   idea to hide a few names:
--   
--   <pre>
--   import qualified System.Win32.Error.Foreign as E
--   import System.Win32 hiding (failIfFalse_, failIf, failUnlessSuccess, failWith)
--   </pre>
--   
--   Handling error conditions in Windows revolves around a thread-local
--   global variable representing the most recent error condition.
--   Functions indicate that an error occurred in various ways. The C++
--   programmer will observe that a function failed, and immediately call
--   GetLastError to retrieve details on the possible cause or to get a
--   localized error message which can be relayed to a human in some way.
--   
--   There are some cases where an error code may mean different things
--   depending on varying context, but in general these codes are globally
--   unique. Microsoft documents which error codes may be expected for any
--   given function.
--   
--   When working with functions exported by Win32, error conditions are
--   dealt with using the <a>IOError</a> exception type. Most native Win32
--   functions return an error code which can be used to determine whether
--   something went wrong during its execution. By convention these
--   functions are all named something of the form "c_DoSomething" where
--   <a>DoSomething</a> matches the name given by Microsoft. A haskell
--   wrapper function named "doSomething" will typically, among other
--   things, check this error code. Based on its value the operating system
--   will be queried for additional error information, and a Haskell
--   exception will be thrown.
--   
--   Consider the <a>createFile</a> function used to open existing files
--   which may or may not actually exist.
--   
--   <pre>
--   createFile "c:\\nofilehere.txt" gENERIC_READ
--              fILE_SHARE_NONE Nothing oPEN_EXISTING 0 Nothing
--   </pre>
--   
--   If no file by that name exists the underlying <a>c_CreateFile</a> call
--   will return <a>iNVALID_HANDLE_VALUE</a>. This will result in an
--   <a>IOError</a> exception being thrown with a <a>String</a> value
--   indicating the function and file name. Internally, the <a>IOError</a>
--   will also contain the error code, which will be converted to a general
--   Haskell value.
--   
--   The Win32-errors package works similarly. A (simplified) wrapper
--   around c_CreateFile could be written as follows. Source code from the
--   Win32 package often provides a good starting point:
--   
--   <pre>
--   createFile name access mode = withTString name $ \ c_name -&gt;
--       E.failIf (== E.toDWORD E.InvalidHandle) "CreateFile" $
--       c_CreateFile c_name access fILE_SHARE_NONE nullPtr
--                    mode 0 nullPtr
--   </pre>
module System.Win32.Error.Foreign

-- | Copied from the Win32 package. Use this to throw a Win32 exception
--   when an action returns a value satisfying the given predicate. The
--   exception thrown will depend on a thead-local global error condition.
--   The supplied <a>Text</a> value should be set to the human-friendly
--   name of the action that triggered the error.
failIf :: (a -> Bool) -> Text -> IO a -> IO a

-- | This function mirrors the Win32 package's <a>failIfFalse_</a>
--   function.
failIfFalse_ :: Text -> IO Bool -> IO ()

-- | This function mirrors the Win32 package's <a>failIfNull</a> function.
failIfNull :: Text -> IO (Ptr a) -> IO (Ptr a)

-- | Perform the supplied action, and throw a <a>Win32Exception</a>
--   exception if the return code is anything other than <a>Success</a>.
--   The supplied action returns a <a>DWORD</a> instead of an
--   <a>ErrCode</a> so that foreign imports can be used more conveniently.
failUnlessSuccess :: Text -> IO DWORD -> IO ()

-- | Throw a <a>Win32Exception</a> exception for the given function name
--   and error code.
failWith :: Text -> ErrCode -> IO a

-- | Windows maintains a thread-local value representing the previously
--   triggered error code. Calling <a>errorWin</a> will look up the value,
--   and throw a <a>Win32Exception</a> exception. The supplied <a>Text</a>
--   argument should be set to the name of the function which triggered the
--   error condition.
--   
--   Calling this action when no error has occurred (0x00000000 --
--   ERROR_SUCCESS) will result in an exception being thrown for the
--   <a>Success</a> error code.
errorWin :: Text -> IO a


-- | This package assumes that you will be using strict <a>Text</a> values
--   for string handling. Consider using the following language pragma and
--   import statements:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   module Main where
--   
--   import Data.Text (Text)
--   import qualified Data.Text as T
--   import qualified Data.Text.Foreign as T
--   </pre>
--   
--   This module is intended to be imported qualified.
--   
--   <pre>
--   import System.Win32.Errors (ErrCode, Win32Exception)
--   import qualified System.Win32.Errors as E
--   </pre>
--   
--   See the <a>Win32Exception</a> type's documentation for an instructions
--   on working with functions that may throw exceptions of this type.
module System.Win32.Error

-- | Exception type for Win32 errors.
--   
--   This type will be thrown as an extensible exception when a foreign
--   call out to part of the Win32 indicates that an error has occurred. In
--   most cases you should wrap an IO computation in a call to
--   <a>tryWin32</a>.
--   
--   The following example uses the custom <tt>createFile</tt> function
--   described in <a>System.Win32.Error.Foreign</a>:
--   
--   <pre>
--   eHandle &lt;- do
--       h &lt;- E.tryWin32 $ createFile "c:\\missing.txt" gENERIC_READ oPEN_EXISTING
--       -- perform other actions
--       return h
--   case eHandle of
--     Right handle -&gt; do
--       -- do something with the file handle
--     Left w32Err -&gt; do
--       case E.errCode w32Err of
--         E.InvalidHandle -&gt; do
--           -- perform cleanup
--         -- handle other error codes.
--       T.putStrLn $ E.systemMessage w32Err
--   </pre>
data Win32Exception
Win32Exception :: Text -> ErrCode -> Text -> Win32Exception

-- | The foreign action which triggered this exception.
[function] :: Win32Exception -> Text

-- | The error code
[errCode] :: Win32Exception -> ErrCode

-- | The standard system message associated with the error code.
[systemMessage] :: Win32Exception -> Text

-- | Actions calling out to Win32 may throw exceptions. Wrapping the action
--   in <a>tryWin32</a> will catch <a>Win32Exception</a> exceptions, but
--   will allow any other exception type to pass through.
tryWin32 :: IO a -> IO (Either Win32Exception a)

-- | Convert an <a>ErrCode</a> into a <a>DWORD</a>.
toDWORD :: ErrCode -> DWORD

-- | Convert a <a>DWORD</a> into an <a>ErrCode</a>. Values which don't have
--   a corresponding constructor will end up becoming an <a>Other</a>.
fromDWORD :: DWORD -> ErrCode

-- | Win32 actions typically return an error code to indicate success or
--   failure. These codes are intended to be globally unique, though there
--   may be some overlap. MSDN documents which errors may be returned by
--   any given action.
--   
--   The naming of errors follows a convention. An error such as
--   ERROR_SUCCESS becomes <a>Success</a>, ERROR_FILE_NOT_FOUND becomes
--   <a>FileNotFound</a>, and so on. There are thousands of errors, so it
--   would be impractical to add them all. The <a>Other</a> constructor is
--   used to represent error codes which are not handled specifically.
--   
--   User's of this library are encouraged to submit new error codes. Add
--   new entries to System.Win32.Errors.Mapping. Send your pull requests
--   along with a link to relevent documentation to
--   <a>https://github.com/mikesteele81/Win32-errors.git</a>.
data ErrCode
InvalidHandleValue :: ErrCode
Success :: ErrCode
FileNotFound :: ErrCode
PathNotFound :: ErrCode
AccessDenied :: ErrCode
InvalidHandle :: ErrCode
InvalidData :: ErrCode
InvalidDrive :: ErrCode
CurrentDirectory :: ErrCode
NoMoreFiles :: ErrCode
CallNotImplemented :: ErrCode
MoreData :: ErrCode
NoMoreItems :: ErrCode
ServiceAlreadyRunning :: ErrCode
ServiceDisabled :: ErrCode
ServiceDoesNotExist :: ErrCode
ServiceCannotAcceptCtrl :: ErrCode
ServiceNotActive :: ErrCode
FailedServiceControllerConnect :: ErrCode
ExceptionInService :: ErrCode
ServiceSpecificError :: ErrCode
ServiceNotInExe :: ErrCode
RPCSServerUnavailable :: ErrCode
RPCSServerTooBusy :: ErrCode
NotAReparsePoint :: ErrCode
DhcpSubnetNotPresent :: ErrCode
DhcpElementCantRemove :: ErrCode
DhcpOptionNotPresent :: ErrCode
DhcpJetError :: ErrCode
DhcpNotReservedClient :: ErrCode
DhcpReservedClient :: ErrCode
DhcpIprangeExists :: ErrCode
DhcpReservedipExists :: ErrCode
DhcpInvalidRange :: ErrCode
DhcpIprangeConvIllegal :: ErrCode
ScopeRangePolicyRangeConflict :: ErrCode
DhcpFoIprangeTypeConvIllegal :: ErrCode
Other :: !DWORD -> ErrCode