-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Interfaces with FreeSwitch Event Socket. -- -- Interfaces with FreeSwitch Event Socket. This should be considered an -- alpha release and has not been tested extensively. @package EventSocket @version 0.1 -- | This module provides an interface for the FreeSwitch event socket - -- http://wiki.freeswitch.org/wiki/Event_Socket. -- -- Developed by David Austin -- (mailto:vulpyne+haskelleventsocket@teliax.com) -- -- Released to the Open Source Software community by Teliax Inc -- (http://www.teliax.com/) module Network.EventSocket -- | Basically, an event. Used and returned by some of the lower level -- Eventsocket routines. data EventSocketMessage EventSocketMessage :: EventType -> EvtKVMap -> Bool -> Either ByteString EvtKVMap -> EventSocketMessage -- | Type of the event. esmType :: EventSocketMessage -> EventType -- | The headers FreeSwitch sent. esmHeaders :: EventSocketMessage -> EvtKVMap -- | Is this a positive response? esmSuccess :: EventSocketMessage -> Bool -- | Either a ByteString or a parsed KV map depending on the type of -- response. esmData :: EventSocketMessage -> Either ByteString EvtKVMap -- | The state of the event socket connection. data EventSocketIO h => EventSocketState h m -- | Mainly FreeSwitch events. -- -- More information for FreeSwitch-specific events: -- http://wiki.freeswitch.org/wiki/Event_list data EventType -- | Sent when the initial negotiation is done. E_Start :: EventType -- | Sent when ending. E_End :: EventType -- | Sent when the Freeswitch event name could not be parsed. E_Other :: ByteString -> EventType -- | FreeSwitch API reply. E_APIResponse :: EventType -- | FreeSwitch command reply. E_CommandReply :: EventType E_CHANNEL_CREATE :: EventType E_CHANNEL_DESTROY :: EventType E_CHANNEL_STATE :: EventType E_CHANNEL_ANSWER :: EventType E_CHANNEL_HANGUP :: EventType E_CHANNEL_HANGUP_COMPLETE :: EventType E_CHANNEL_EXECUTE :: EventType E_CHANNEL_EXECUTE_COMPLETE :: EventType E_CHANNEL_BRIDGE :: EventType E_CHANNEL_UNBRIDGE :: EventType E_CHANNEL_PROGRESS :: EventType E_CHANNEL_PROGRESS_MEDIA :: EventType E_CHANNEL_OUTGOING :: EventType E_CHANNEL_PARK :: EventType E_CHANNEL_UNPARK :: EventType E_CHANNEL_APPLICATION :: EventType E_CHANNEL_ORIGINATE :: EventType E_CHANNEL_UUID :: EventType E_SHUTDOWN :: EventType E_MODULE_LOAD :: EventType E_MODULE_UNLOAD :: EventType E_RELOADXML :: EventType E_NOTIFY :: EventType E_SEND_MESSAGE :: EventType E_RECV_MESSAGE :: EventType E_REQUEST_PARMS :: EventType E_CHANNEL_DATA :: EventType E_GENERAL :: EventType E_COMMAND :: EventType E_SESSION_HEARTBEAT :: EventType E_CLIENT_DISCONNECTED :: EventType E_SERVER_DISCONNECTED :: EventType E_SEND_INFO :: EventType E_RECV_INFO :: EventType E_CALL_SECURE :: EventType E_NAT :: EventType E_RECORD_START :: EventType E_RECORD_STOP :: EventType E_CALL_UPDATE :: EventType E_API :: EventType E_BACKGROUND_JOB :: EventType E_CUSTOM :: EventType E_RE_SCHEDULE :: EventType E_HEARTBEAT :: EventType E_DETECTED_TONE :: EventType E_ALL :: EventType E_LOG :: EventType E_INBOUND_CHAN :: EventType E_OUTBOUND_CHAN :: EventType E_STARTUP :: EventType E_PUBLISH :: EventType E_UNPUBLISH :: EventType E_TALK :: EventType E_NOTALK :: EventType E_SESSION_CRASH :: EventType E_DTMF :: EventType E_MESSAGE :: EventType E_PRESENCE_IN :: EventType E_PRESENCE_OUT :: EventType E_PRESENCE_PROBE :: EventType E_MESSAGE_WAITING :: EventType E_MESSAGE_QUERY :: EventType E_ROSTER :: EventType E_CODEC :: EventType E_DETECTED_SPEECH :: EventType E_PRIVATE_COMMAND :: EventType E_TRAP :: EventType E_ADD_SCHEDULE :: EventType E_DEL_SCHEDULE :: EventType E_EXE_SCHEDULE :: EventType -- | Error type thrown when something goes boom. data EventSocketError UnknownError :: EventSocketError NetworkError :: String -> EventSocketError ParseError :: String -> EventSocketError ProtocolError :: String -> EventSocketError GeneralError :: String -> EventSocketError -- | Event Socket commands. This list is far from complete. -- -- More information is available: -- http://wiki.freeswitch.org/wiki/Command_reference data EventSocketCommand -- | http://wiki.freeswitch.org/wiki/Event_Socket#event CmdEvents :: ByteString -> [ByteString] -> EventSocketCommand -- | Event format, either plain or XML. format :: EventSocketCommand -> ByteString -- | Event types. events :: EventSocketCommand -> [ByteString] -- | http://wiki.freeswitch.org/wiki/Event_Socket#filter CmdFilter :: Bool -> ByteString -> ByteString -> EventSocketCommand -- | Delete this filter instead of creating. isDelete :: EventSocketCommand -> Bool -- | Header to allow. eventHeader :: EventSocketCommand -> ByteString -- | Value to allow. eventValue :: EventSocketCommand -> ByteString -- | Turns on event socket linger, causing the event socket to send all -- remaining events before closing the connection. CmdLinger :: EventSocketCommand -- | Sets a channel variable. CmdSet :: ByteString -> ByteString -> EventSocketCommand -- | Set key. key :: EventSocketCommand -> ByteString -- | Set value. val :: EventSocketCommand -> ByteString -- | Hangs up the call. (Uses the UUID in the event socket state.) CmdHangup :: ByteString -> EventSocketCommand -- | Reason for hangup: -- http://wiki.freeswitch.org/wiki/Hangup_causes reason :: EventSocketCommand -> ByteString -- | Sleeps the specified number of milliseconds. -- http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_sleep CmdSleep :: Int -> EventSocketCommand -- | Duration to sleep. duration :: EventSocketCommand -> Int -- | Answers the call. CmdAnswer :: EventSocketCommand -- | Plays a sound file and waits for input. -- http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_play_and_get_digits CmdPlayGather :: Int -> Int -> Int -> Int -> ByteString -> ByteString -> ByteString -> ByteString -> ByteString -> EventSocketCommand minDigits :: EventSocketCommand -> Int maxDigits :: EventSocketCommand -> Int tries :: EventSocketCommand -> Int timeout :: EventSocketCommand -> Int terminators :: EventSocketCommand -> ByteString file :: EventSocketCommand -> ByteString invalidFile :: EventSocketCommand -> ByteString varName :: EventSocketCommand -> ByteString regexp :: EventSocketCommand -> ByteString -- | Bridges a call. -- http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_bridgecall CmdBridge :: [ByteString] -> EventSocketCommand destinations :: EventSocketCommand -> [ByteString] -- | Can speak simple output like digits or time. -- http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_say CmdSay :: ByteString -> EventSocketCommand text :: EventSocketCommand -> ByteString -- | Can speak arbitrary text using a TTS engine. -- http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_speak CmdSpeak :: ByteString -> EventSocketCommand text :: EventSocketCommand -> ByteString -- | Plays a sound file. -- http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_playback CmdPlay :: ByteString -> EventSocketCommand filename :: EventSocketCommand -> ByteString -- | Records a sound file. -- http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_record CmdRecord :: ByteString -> Int -> EventSocketCommand filename :: EventSocketCommand -> ByteString maxLength :: EventSocketCommand -> Int -- | Binds a meta application. -- http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_bind_meta_app CmdMetaApp :: Char -> Char -> Char -> ByteString -> EventSocketCommand listenKey :: EventSocketCommand -> Char listenTo :: EventSocketCommand -> Char respondOn :: EventSocketCommand -> Char appString :: EventSocketCommand -> ByteString -- | Sync point. CmdSync :: EventSocketCommand -- | Stores a session. Two user accessible fields exist: -- -- data EventSocketIO h => SessionState h m -- | Just a simple map ByteString to ByteString. type EvtKVMap = Map ByteString ByteString -- | UUIDs are currently just bytestrings. type ESUUID = ByteString data (Monad m, EventSocketIO h) => EventSocketT h m a -- | You may instance this class if you'd like to use a different handle -- type (or just read/write to the normal Handle in some special way.) class EventSocketIO h esioBReadLine :: EventSocketIO h => h -> IO ByteString esioBRead :: EventSocketIO h => h -> Int -> IO ByteString esioBWrite :: EventSocketIO h => h -> ByteString -> IO () esioFlush :: EventSocketIO h => h -> IO () esioReady :: EventSocketIO h => h -> IO Bool -- | Starts a listen socket for incoming EventSocket connections. You'll -- generally want to call connectInbound after the handler is -- triggered. startEventSocket :: HostName -> PortNumber -> (EventSocketState Handle m -> IO ()) -> IO () -- | Sends the initial connect message and receives a response. connectInbound :: (MonadIO m, EventSocketIO h) => EventSocketT h m EventSocketMessage -- | Runs the event socket monad transformer. runEventSocketT :: (MonadIO m, EventSocketIO h) => EventSocketT h m a -> EventSocketState h m -> m (Either EventSocketError a, EventSocketState h m) -- | SyncMode controls whether Event-Lock: true is sent with -- commands. modifySyncMode :: (Monad m, EventSocketIO h) => (Bool -> Bool) -> EventSocketT h m Bool -- | Modifies the debug level. At high values, the event socket library -- will spit out massive amounts of data to the console. modifyDebugLevel :: (Monad m, EventSocketIO h) => (Int -> Int) -> EventSocketT h m Int -- | Registers an event handler. If the UUID is left blank, it will trigger -- globally on all events of the appropriate type. -- -- Some event types (example E_CommandReply, E_APIResponse) do not have a -- UUID and therefore must be added as an global event if you wish to -- catch it. -- -- Since the event may return a new handler function on each invocation, -- an event handler may maintain private state this way. -- -- The event handler may return EHContinue to continue processing, -- EHStopEvents to stop processing events for that message or -- EHStopReading to exit the event reading loop entirely. -- -- Event handlers are only called from within -- eventSocketReadEventsUntil (and functions that use this: -- waitForEvent, commandAndReply, apiAndReply). -- -- Global events are processed first, then session events. -- -- You may not recurse into eventSocketReadEventUntil from -- within an event handler. registerEventHandler :: (MonadIO m, EventSocketIO h) => ByteString -> EventType -> Int -> EventHandlerFunc h m -> EventSocketT h m EventId -- | Given an event ID, it will remove that event if it exists. unregisterEventHandler :: (Monad m, EventSocketIO h) => EventId -> EventSocketT h m () type EventId = (Int, ByteString, EventType) data EventHandlerResult EHStopEvents :: EventHandlerResult EHContinue :: EventHandlerResult EHStopReading :: EventHandlerResult data EventSocketIO h => EventHandlerFunc h m EventHandlerFunc :: (EventSocketMessage -> EventSocketT h m (Maybe (EventHandlerFunc h m), EventHandlerResult)) -> EventHandlerFunc h m -- | Plays a 0 length tone stream to force a CHANNEL_EXECUTE_COMPLETE event -- as a synchronization point. Will wait forever if events aren't turned -- on. syncPoint :: (MonadIO m, EventSocketIO h) => EventSocketT h m [EventSocketMessage] -- | Runs a command of type EventSocketCommand. Behaves roughly the -- same as commandAndReply. esRun :: (MonadIO m, EventSocketIO h) => EventSocketCommand -> EventSocketT h m [EventSocketMessage] -- | Runs a sequence of EventSocketCommands. esRunActions :: (MonadIO m, EventSocketIO h) => [EventSocketCommand] -> EventSocketT h m [EventSocketMessage] -- | Gets a session if it exists. getSession :: (MonadIO m, EventSocketIO h) => ESUUID -> EventSocketT h m (Maybe (SessionState h m)) -- | Sends a raw command (such as an API command) to the event socket and -- waits for the response. apiAndReply :: (MonadIO m, EventSocketIO h) => ByteString -> ByteString -> EventSocketT h m [EventSocketMessage] -- | Sends a command and then waits for a response. commandAndReply :: (MonadIO m, EventSocketIO h) => ByteString -> ByteString -> EventSocketT h m [EventSocketMessage] -- | Run a monadic action with the specified UUID as the current UUID. Once -- the action completes, the previous UUID is restored iff it is the same -- as the original UUID. withUUID :: (Monad m, EventSocketIO h) => ByteString -> (EventSocketT h m a) -> EventSocketT h m a -- | Get the UUID of the main session. getUUID :: (MonadIO m, EventSocketIO h) => EventSocketT h m ESUUID -- | Sends a raw command to the event socket. sendAPI :: (MonadIO m, EventSocketIO h) => ByteString -> ByteString -> EventSocketT h m () -- | Sends a command to the event socket. sendCommand :: (MonadIO m, EventSocketIO h) => ByteString -> ByteString -> EventSocketT h m () -- | Waits forever for the specified event type. waitForEvent :: (MonadIO m, EventSocketIO h) => EventType -> EventSocketT h m [EventSocketMessage] -- | Reads messages from the event socket until a condition is true. -- -- The handler is called with Nothing to detect whether messages should -- be read (for example, check if the socket has data waiting.) -- -- At that point, the handler returns whether more messages should be -- read (True for more messages, False to stop reading messages.) -- -- The handler is called on each received message. -- -- At that the handler returns whether it is done (True for no more -- messages, False to continue reading messages.) eventSocketReadEventsUntil :: (MonadIO m, EventSocketIO h) => (Maybe EventSocketMessage -> EventSocketT h m Bool) -> EventSocketT h m (Bool, [EventSocketMessage]) -- | Creates a new EventSocketState. You may use your own handle type and -- functions for reading and writing data to it. newEventSocketState :: EventSocketIO h => h -> HostName -> PortNumber -> EventSocketState h m instance Show EventSocketMessage instance Eq EventSocketMessage instance Ord EventSocketMessage instance Show EventSocketError instance EventSocketIO h => Show (EventHandler h m) instance Show EventHandlerResult instance Eq EventHandlerResult instance EventSocketIO h => Show (SessionState h m) instance (Show h, EventSocketIO h) => Show (EventSocketState h m) instance Show EventSocketCommand instance Show EventType instance Eq EventType instance Ord EventType instance Read EventType instance Monad m => Monad (EventSocketT h m) instance MonadIO m => MonadIO (EventSocketT h m) instance Monad m => MonadState (EventSocketState h m) (EventSocketT h m) instance Monad m => MonadError EventSocketError (EventSocketT h m) instance EventSocketIO Handle instance Error EventSocketError instance EventSocketIO h => Eq (EventHandler h m) instance EventSocketIO h => Ord (EventHandler h m) instance Show (EventHandlerFunc h m) instance Show (h -> ByteString -> IO ()) instance Show (h -> Int -> IO ByteString) instance Show (h -> IO ByteString) instance EventSocketIO h => MonadTrans (EventSocketT h) instance (Monad m, EventSocketIO h) => Applicative (EventSocketT h m) instance (Monad m, EventSocketIO h) => Functor (EventSocketT h m)