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


-- | Log to syslog over a network via UDP
--   
--   Supports <a>RFC 5424</a>, <a>RFC 3164</a>, or any arbitrary protocol.
@package hsyslog-udp
@version 0.2.3


-- | Log messages to syslog over a network via UDP, with protocols such as
--   <a>RFC 5424</a> or <a>RFC 3164</a>.
--   
--   The following features are currently missing (but may be provided in
--   future releases):
--   
--   <ul>
--   <li>validation of string identifiers such as <tt>APP-NAME</tt> or
--   <tt>MSGID</tt></li>
--   <li>support for <tt>STRUCTURED-DATA</tt> (RFC 5424 only)</li>
--   </ul>
module System.Posix.Syslog.UDP

-- | Log messages are prioritized with one of the following levels:
--   
--   <pre>
--   &gt;&gt;&gt; [minBound..maxBound] :: [Priority]
--   [Emergency,Alert,Critical,Error,Warning,Notice,Info,Debug]
--   </pre>
--   
--   The <a>Ord</a> instance for <a>Priority</a> considers the more urgent
--   level lower than less urgent ones:
--   
--   <pre>
--   &gt;&gt;&gt; Emergency &lt; Debug
--   True
--   
--   &gt;&gt;&gt; minimum [minBound..maxBound] :: Priority
--   Emergency
--   
--   &gt;&gt;&gt; maximum [minBound..maxBound] :: Priority
--   Debug
--   </pre>
data Priority :: *

-- | the system is unusable
Emergency :: Priority

-- | action must be taken immediately
Alert :: Priority

-- | critical conditions
Critical :: Priority

-- | error conditions
Error :: Priority

-- | warning conditions
Warning :: Priority

-- | normal but significant condition
Notice :: Priority

-- | informational
Info :: Priority

-- | debug-level messages
Debug :: Priority

-- | Syslog distinguishes various system facilities. Most applications
--   should log in <tt>USER</tt>.
data Facility :: *

-- | kernel messages
Kernel :: Facility

-- | user-level messages (default unless set otherwise)
User :: Facility

-- | mail system
Mail :: Facility

-- | network news subsystem
News :: Facility

-- | UUCP subsystem
UUCP :: Facility

-- | system daemons
Daemon :: Facility

-- | security and authorization messages
Auth :: Facility

-- | clock daemon
Cron :: Facility

-- | line printer subsystem
LPR :: Facility

-- | reserved for local use
Local0 :: Facility

-- | reserved for local use
Local1 :: Facility

-- | reserved for local use
Local2 :: Facility

-- | reserved for local use
Local3 :: Facility

-- | reserved for local use
Local4 :: Facility

-- | reserved for local use
Local5 :: Facility

-- | reserved for local use
Local6 :: Facility

-- | reserved for local use
Local7 :: Facility
newtype AppName

-- | see <tt><a>APP-NAME</a></tt>
AppName :: ByteString -> AppName
newtype HostName

-- | see <tt><a>HOSTNAME</a></tt>; fetch via <a>getHostName</a>
HostName :: ByteString -> HostName
newtype PriVal

-- | see <tt><a>PRI</a></tt>; construct via <a>maskedPriVal</a>
PriVal :: CInt -> PriVal
newtype ProcessID

-- | see <tt><a>PROCID</a></tt>; fetch via <a>getProcessId</a>
ProcessID :: ByteString -> ProcessID
newtype MessageID

-- | see <tt><a>MSGID</a></tt>
MessageID :: ByteString -> MessageID
type Severity = Priority
type SeverityMask = [Priority]
data StructuredData

-- | see <tt><a>STRUCTURED-DATA</a></tt> (unsupported)
StructuredData :: StructuredData

-- | Return a function that logs to syslog via UDP.
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import System.Posix.Syslog.UDP
--   
--   main = do
--     syslog &lt;- defaultConfig &gt;&gt;= initSyslog
--     putStrLn "huhu"
--     syslog USER Debug "huhu"
--   </pre>
--   
--   This makes no assumptions about socket connection status or endpoint
--   availability. Any errors while sending are silently ignored.
initSyslog :: SyslogConfig -> IO SyslogFn

-- | The type of function returned by <a>initSyslog</a>.
type SyslogFn = Facility  facility to log to -> Severity  severity under which to log -> Text  message body -> IO ()

-- | Configuration options for connecting and logging to your syslog
--   socket.
data SyslogConfig
SyslogConfig :: !AppName -> !HostName -> !ProcessID -> !SeverityMask -> !AddrInfo -> Protocol -> (SomeException -> IO ()) -> SyslogConfig

-- | see <tt><a>APP-NAME</a></tt>; fetch via <a>getAppName</a>
[appName] :: SyslogConfig -> !AppName

-- | see <tt><a>HOSTNAME</a></tt>; fetch via <a>getHostName</a>
[hostName] :: SyslogConfig -> !HostName

-- | see <tt><a>PROCID</a></tt>; fetch via <a>getProcessId</a>
[processId] :: SyslogConfig -> !ProcessID

-- | whitelist of priorities of logs to send
[severityMask] :: SyslogConfig -> !SeverityMask

-- | where to send the syslog packets; construct via
--   <a>resolveUdpAddress</a> or find via <a>getAddrInfo</a>
[address] :: SyslogConfig -> !AddrInfo

-- | protocol for formatting the message, such as <a>rfc5424Protocol</a> or
--   <a>rfc3164Protocol</a>
[protocol] :: SyslogConfig -> Protocol

-- | custom exception handler
[onException] :: SyslogConfig -> SomeException -> IO ()

-- | A convenient default config for connecting to <a>localhost</a>.
--   Provided for development/testing purposes.
defaultConfig :: IO SyslogConfig

-- | The default IPv4 address/port for syslog on a local machine. Provided
--   for development/testing purposes.
localhost :: AddrInfo
type Protocol = PriVal -> UTCTime -> HostName -> AppName -> ProcessID -> Text -> ByteString
rfc5424Protocol :: Protocol
rfc3164Protocol :: Protocol
rsyslogProtocol :: Protocol

-- | Construct a syslog UDP packet as dictated by <a>RFC 5424</a>. Note
--   that fields in a syslog packet are whitespace-delineated, so don't
--   allow whitespace in anything but the log message!
rfc5424Packet :: FormatTime t => PriVal -> Maybe t -> Maybe HostName -> Maybe AppName -> Maybe ProcessID -> Maybe MessageID -> Maybe StructuredData -> Text -> ByteString

-- | Construct a syslog UDP packet as dictated by <a>RFC 3164</a>. Note
--   that fields in a syslog packet are whitespace-delineated, so don't
--   allow whitespace in anything but the log message!
rfc3164Packet :: FormatTime t => PriVal -> t -> HostName -> AppName -> ProcessID -> Text -> ByteString

-- | Recommended rsyslog template <tt><a>RSYSLOG_ForwardFormat</a></tt>.
--   Same fields as RFC 3164, but with an RFC 3339 high-precision
--   timestamp.
rsyslogPacket :: FormatTime t => PriVal -> t -> HostName -> AppName -> ProcessID -> Text -> ByteString
getAppName :: IO AppName
getHostName :: IO HostName
getProcessId :: IO ProcessID

-- | Construct a <tt><a>PRI</a></tt>. <a>Nothing</a> indicates that the
--   severities are fully masked, and so no packet should be sent.
maskedPriVal :: SeverityMask -> Facility -> Severity -> Maybe PriVal

-- | Obtain an IPv4 <a>AddrInfo</a> for your <a>SyslogConfig</a> from a
--   hostname (or IPv4 address) and port. Sets the address protocol to
--   <a>Datagram</a>.
resolveUdpAddress :: Integral n => String -> n -> IO (Maybe AddrInfo)

-- | An <a>RFC 3339</a> high-precision timestamp.
rfc3339Timestamp :: FormatTime t => t -> ByteString
instance GHC.Show.Show System.Posix.Syslog.UDP.MessageID
instance GHC.Classes.Eq System.Posix.Syslog.UDP.MessageID
instance GHC.Show.Show System.Posix.Syslog.UDP.ProcessID
instance GHC.Classes.Eq System.Posix.Syslog.UDP.ProcessID
instance GHC.Show.Show System.Posix.Syslog.UDP.PriVal
instance GHC.Classes.Eq System.Posix.Syslog.UDP.PriVal
instance GHC.Show.Show System.Posix.Syslog.UDP.HostName
instance GHC.Classes.Eq System.Posix.Syslog.UDP.HostName
instance GHC.Show.Show System.Posix.Syslog.UDP.AppName
instance GHC.Classes.Eq System.Posix.Syslog.UDP.AppName
