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


-- | A library for writing AGI scripts for Asterisk
--   
--   Asterisk is an open-source Voice over IP server (VoIP). Asterisk
--   provides an Asterisk Gateway Interface (AGI), which can be used to
--   write external programs that interact with Asterisk. It is typically
--   used for creating Interactive Voice Response (IVR) systems.
@package AGI
@version 1.3

module Network.AGI

-- | DTMF digits
data Digit
Pound :: Digit
Star :: Digit
Zero :: Digit
One :: Digit
Two :: Digit
Three :: Digit
Four :: Digit
Five :: Digit
Six :: Digit
Seven :: Digit
Eight :: Digit
Nine :: Digit

-- | convert a <a>Digit</a> to its ASCII representation
ppDigit :: Digit -> Char

-- | convert a list of <a>Digit</a>s into a quoted string. The quoted
--   string format is used by many AGI commands
ppEscapeDigits :: [Digit] -> String

-- | convert a list of <a>Digit</a>s to an <a>Integer</a>. Will fail if the
--   list is empty or contains * or #
digitsToInteger :: [Digit] -> Maybe Integer
type AGI = AGIT IO

-- | Top-level wrapper for single-shot AGI scripts.
--   
--   Example:
--   
--   <pre>
--   main = run yourAGI Ignore
--   </pre>
run :: MonadIO m => AGIT m a -> Handler -> m a

-- | Top-level for long running AGI scripts.
--   
--   Example:
--   
--   <pre>
--   main = fastAGI Nothing yourAGI
--   </pre>
--   
--   You should be sure to compile with -threaded. Note that
--   <tt>yourAGI</tt> may be running simultaneously in multiple threads, so
--   you will need some concurrency control for shared data.
--   
--   TODO: support a hang-up handler TODO: ability to listen on a specific
--   IP address
fastAGI :: Maybe PortID -> (HostName -> PortNumber -> AGI a) -> IO ()

-- | runInternal - run an AGI script using the supplied Handles for input
--   and output
--   
--   You probably want <a>run</a> or <a>fastAGI</a>. This function is
--   exposed so that 3rd party libraries such as HAppS can easily add
--   support for FastAGI support.
--   
--   TODO: support general method of handling extra arguments (query_string
--   vs command-line arguments)
runInternal :: MonadIO m => AGIT m a -> Handle -> Handle -> m a
data SoundType
WAV :: SoundType
GSM :: SoundType

-- | send an AGI Command, and return the Response
--   
--   this function provides the low-level send/receive functionality.
sendRecv :: MonadIO m => Command -> AGIT m String

-- | <a>answer</a> channel if not already in answer state
answer :: MonadIO m => AGIT m Bool

-- | hangUp the specified channel
hangUp :: MonadIO m => Maybe String -> AGIT m Bool

-- | play a file and return and digits pressed
--   
--   See also: <a>streamFile</a>
getData :: MonadIO m => FilePath -> Maybe Integer -> Maybe Integer -> AGIT m (Maybe ([Digit], Bool))
data RecordResult
FailureToWrite :: RecordResult
FailureOnWaitFor :: RecordResult
HangUp :: RecordResult
Interrupted :: Digit -> RecordResult
Timeout :: RecordResult
RandomError :: String -> RecordResult

-- | say the given digit string
sayDigits :: MonadIO m => [Digit] -> [Digit] -> AGIT m (Maybe (Maybe Digit))

-- | <a>sayNumber</a> says the specified number
sayNumber :: MonadIO m => Integer -> [Digit] -> AGIT m (Maybe (Maybe Digit))

-- | playback the specified file, can be interupted by the given digits.
--   
--   See also: <a>getData</a>
streamFile :: MonadIO m => FilePath -> [Digit] -> Maybe Integer -> AGIT m (Either Integer (Maybe Digit, Integer))

-- | wait for channel to receive a DTMF digit.
--   
--   See also: <a>getData</a> for multiple digits
waitForDigit :: MonadIO m => Integer -> AGIT m (Maybe (Maybe Digit))

-- | record channel to a file
record :: MonadIO m => FilePath -> SoundType -> [Digit] -> Maybe Integer -> Maybe Integer -> Bool -> Maybe Integer -> AGIT m (RecordResult, Integer)
instance Typeable RecordResult
instance Typeable SoundType
instance Typeable Digit
instance Eq RecordResult
instance Show RecordResult
instance Data RecordResult
instance Eq SoundType
instance Enum SoundType
instance Data SoundType
instance Eq Digit
instance Ord Digit
instance Read Digit
instance Show Digit
instance Enum Digit
instance Data Digit
instance Monad m => Monad (AGIT m)
instance MonadIO m => MonadIO (AGIT m)
instance Functor m => Functor (AGIT m)
instance Monad m => MonadReader AGIEnv (AGIT m)
instance Show SoundType