Contains functions to communicate with freeswitch using ESL.
Contains functions to communicate with freeswitch using ESL.
(bind-event conn handler & {:as event-headers})
Bind a handler function to the event.
Args:
conn
- The connection map.handler
- The event handler function. It's signature should be:
(fn [conn event-map])
. Handler return value does not
matter.Kwargs:
All key value pairs are treated as event headers to match against.
Returns:
nil
Usage Example:
;; Set a catch-all-stray event handler.
(bind-event conn
(fn [conn event]
(println "I match all stray events!")))
;; Create a BACKGROUND_JOB event handler.
(bind-event conn
(fn [conn event]
(println "I match all BG_JOB events."))
:event-name "BACKGROUND_JOB")
;; Create BACKGROUND_JOB event handler for a specific job-uuid.
(bind-event conn
(fn [conn event]
(println "I match BG_JOB with specific UUID."))
:event-name "BACKGROUND_JOB"
:job-uuid "1234")
Note:
req-event
.Bind a handler function to the event. __Args:__ * `conn` - The connection map. * `handler` - The event handler function. It's signature should be: `(fn [conn event-map])`. Handler return value does not matter. __Kwargs:__ All key value pairs are treated as event headers to match against. __Returns:__ `nil` __Usage Example:__ ;; Set a catch-all-stray event handler. (bind-event conn (fn [conn event] (println "I match all stray events!"))) ;; Create a BACKGROUND_JOB event handler. (bind-event conn (fn [conn event] (println "I match all BG_JOB events.")) :event-name "BACKGROUND_JOB") ;; Create BACKGROUND_JOB event handler for a specific job-uuid. (bind-event conn (fn [conn event] (println "I match BG_JOB with specific UUID.")) :event-name "BACKGROUND_JOB" :job-uuid "1234") __Note:__ * This does not send an 'event' command to freeswitch. * Generally, you should use it's higher-level cousin: [[req-event]]. * Only one event handler is allowed per match criteria. New bindings override the old ones. * Specific handlers has higher priority than generalized ones. The catch-all-stray handler has lowest priority.
(close {:keys [aleph-stream event-chan closed?] :as conn})
Close a freeswitch connection.
Note:
Normally, you should use disconnect
function to
gracefully disconnect, which sends protocol epilogue.
Close a freeswitch connection. __Note:__ Normally, you should use [[disconnect]] function to gracefully disconnect, which sends protocol epilogue.
(connect &
{:keys [host port password]
:or {host "127.0.0.1" port 8021 password "ClueCon"}
:as kwargs})
Make an inbound connection to freeswitch.
Kwargs:
:host
- (optional) Hostname or ipaddr of the freeswitch ESL server.
Defaults to "127.0.0.1"
.:port
- (optional) Port where freeswitch is listening.
Defaults to 8021
.:password
- (optional) Password for freeswitch inbound connection.
Defaults to "ClueCon"
.Returns:
A map describing the connection.
Note:
Blocks until authentication step is complete.
Make an inbound connection to freeswitch. __Kwargs:__ * `:host` - (optional) Hostname or ipaddr of the freeswitch ESL server. Defaults to `"127.0.0.1"`. * `:port` - (optional) Port where freeswitch is listening. Defaults to `8021`. * `:password` - (optional) Password for freeswitch inbound connection. Defaults to `"ClueCon"`. __Returns:__ A map describing the connection. __Note:__ Blocks until authentication step is complete.
(disconnect conn)
Gracefully disconnect from freeswitch by sending an 'exit' command.
Args:
conn
- The connection map.Returns:
nil
Gracefully disconnect from freeswitch by sending an 'exit' command. __Args:__ * `conn` - The connection map. __Returns:__ `nil`
(listen & {:keys [port handler] :as kwargs})
Listen for outbound connections from freeswitch.
Kwargs:
:port
- Port to listen for freeswitch connections.:handler
- A function with signature: (fn [conn chan-data])
.
conn
is a connection map which can be used with any
requester function, like: req-cmd
, req-api
etc.
chan-data
is information about current channel.Returns:
An aleph server object.
Notes:
.close
method of the returned
server object.Listen for outbound connections from freeswitch. __Kwargs:__ * `:port` - Port to listen for freeswitch connections. * `:handler` - A function with signature: `(fn [conn chan-data])`. `conn` is a connection map which can be used with any requester function, like: [[req-cmd]], [[req-api]] etc. `chan-data` is information about current channel. __Returns:__ An aleph server object. __Notes:__ * Connection auto listens for 'myevents'. But no event handler is bound. * To stop listening for connections, call `.close` method of the returned server object.
(req conn cmd-line cmd-hdrs cmd-body)
Make a request to freeswitch.
Args:
Returns:
An async/promise-chan
which returns the response when available.
NOTE:
This is a low level function, intended to be used by other
high-level functions like req-cmd
etc.
Make a request to freeswitch. Args: * conn - Freeswitch connection. Returns: An `async/promise-chan` which returns the response when available. NOTE: This is a low level function, intended to be used by other high-level functions like `req-cmd` etc.
(req-api conn api-cmd)
Convenience function to make an api request.
Args:
conn
- The connection map.api-cmd
- Api command string with arguments.Returns:
A response map with following keys:
* :ok
- Whether the operation succeeded.
* :result
- The result of the api request.
Usage Example:
;; Send a 'status' api request.
(println (req-api conn "status"))
Convenience function to make an api request. __Args:__ * `conn` - The connection map. * `api-cmd` - Api command string with arguments. __Returns:__ A response map with following keys: * `:ok` - Whether the operation succeeded. * `:result` - The result of the api request. __Usage Example:__ ;; Send a 'status' api request. (println (req-api conn "status"))
(req-bgapi conn handler api-cmd)
Make a background api request.
Args:
conn
- The connection map.handler
- Result handler function. Signature is: (fn [conn rslt])
.
rslt
is a map with following keys:
* :ok
- Designates success of api operation.
* :result
- Result of the api command.
* :event
- The event which delivered the result.api-cmd
- Api command string with arguments.Returns:
The command response (not the api result).
Usage Example:
;; Execute a 'status' api request in background.
(req-bgapi
conn
(fn [conn rslt] (println rslt))
"status")
Make a background api request. __Args:__ * `conn` - The connection map. * `handler` - Result handler function. Signature is: `(fn [conn rslt])`. `rslt` is a map with following keys: * `:ok` - Designates success of api operation. * `:result` - Result of the api command. * `:event` - The event which delivered the result. * `api-cmd` - Api command string with arguments. __Returns:__ The command response (not the api result). __Usage Example:__ ;; Execute a 'status' api request in background. (req-bgapi conn (fn [conn rslt] (println rslt)) "status")
(req-call-execute conn
app-cmd
&
{:keys [chan-uuid event-uuid start-handler end-handler
event-lock loops]
:or {event-lock false loops 1}
:as kwargs})
Send a 'sendmsg' request to a channel (or current channel, in case of freeswitch-outbound mode) to execute a dialplan application.
Args:
app-cmd
- The dialplan app to execute, including it's arguments.
i.e. "playback /tmp/myfile.wav"Kwargs:
:chan-uuid
- The UUID of the target channel. Unnecessary in outbound mode.:event-uuid
- (optional) An UUID to track the events generated by the command.
If not provided, a random UUID is used. Note that as of freeswitch
1.6, this UUID is returned as value of the :application-uuid
header
of the event.:start-handler
- (optional) Function to process the 'CHANNEL_EXECUTE' event.:end-handler
- (optional) Function to process the 'CHANNEL_EXECUTE_COMPLETE' event.:event-lock
- (optional) Whether to execute apps in sync. Defaults to false.:loops
- (optional) The number of times the app will be executed. Defaults to 1.Returns:
Command response.
Send a 'sendmsg' request to a channel (or current channel, in case of freeswitch-outbound mode) to execute a dialplan application. __Args:__ * `app-cmd` - The dialplan app to execute, including it's arguments. i.e. "playback /tmp/myfile.wav" __Kwargs:__ * `:chan-uuid` - The UUID of the target channel. Unnecessary in outbound mode. * `:event-uuid` - (optional) An UUID to track the events generated by the command. If not provided, a random UUID is used. Note that as of freeswitch 1.6, this UUID is returned as value of the `:application-uuid` header of the event. * `:start-handler` - (optional) Function to process the 'CHANNEL_EXECUTE' event. * `:end-handler` - (optional) Function to process the 'CHANNEL_EXECUTE_COMPLETE' event. * `:event-lock` - (optional) Whether to execute apps in sync. Defaults to false. * `:loops` - (optional) The number of times the app will be executed. Defaults to 1. __Returns:__ Command response.
(req-cmd conn cmd)
Send a simple command request.
Args:
Returns:
A response map with key :ok
bound to a boolean value
describing success of the operation.
Usage Example:
;; Send a 'noevents' command.
(req-cmd conn "noevents")
Note:
Don't use this function to send special commands, like - 'bgapi', 'sendmsg' etc. Rather use the high level functions provided for each.
Send a simple command request. __Args:__ * conn - The connection map. * cmd - The command string including additional arguments. __Returns:__ A response map with key `:ok` bound to a boolean value describing success of the operation. __Usage Example:__ ;; Send a 'noevents' command. (req-cmd conn "noevents") __Note:__ Don't use this function to send special commands, like - 'bgapi', 'sendmsg' etc. Rather use the high level functions provided for each.
(req-event conn handler & {:keys [event-name] :as event-headers})
Request to listen for an event and bind a handler for it.
Args:
conn
- The connection map.handler
- Event handler function with signature:
(fn [conn event-map])
.Kwargs:
:event-name
- Name of the event. Special value ALL
means
subscribe to all events and the handler matches
any value for :event-name.
:event-subclass
to match for custom
events.Returns:
Response of the event command.
Usage Examples:
;; Listen for a regular event. (req-event conn (fn [conn event] (println "Got a call update!")) :event-name "CALL_UPDATE")
;; Listen for a custom event with specific subclass. (req-event conn (fn [conn event] (println "Inside a menu!")) :event-name "CUSTOM" :event-subclass "menu:enter")
;; Listen for all events and setup a catch-all-stray handler. (req-event conn (fn [conn event] (println event)) :event-name "ALL")
Request to listen for an event and bind a handler for it. __Args:__ * `conn` - The connection map. * `handler` - Event handler function with signature: `(fn [conn event-map])`. __Kwargs:__ * `:event-name` - Name of the event. Special value `ALL` means subscribe to all events and the handler matches any value for `:event-name.` * All other keyword arguments are treated as event headers to match against. Like `:event-subclass` to match for custom events. __Returns:__ Response of the event command. __Usage Examples:__ ;; Listen for a regular event. (req-event conn (fn [conn event] (println "Got a call update!")) :event-name "CALL_UPDATE") ;; Listen for a custom event with specific subclass. (req-event conn (fn [conn event] (println "Inside a menu!")) :event-name "CUSTOM" :event-subclass "menu:enter") ;; Listen for all events and setup a catch-all-stray handler. (req-event conn (fn [conn event] (println event)) :event-name "ALL")
(req-sendevent conn event-name & {:keys [body] :as event-headers})
Send a generated event to freeswitch.
Args:
conn
- The connection map.event-name
- The name of the event.Keyword args:
:body
- (optional) The body of the event.Returns:
Response of the command.
Send a generated event to freeswitch. __Args:__ * `conn` - The connection map. * `event-name` - The name of the event. __Keyword args:__ * `:body` - (optional) The body of the event. * Any other keyword arguments are treated as headers for the event. __Returns:__ Response of the command.
(req-sendmsg conn & {:keys [chan-uuid body] :as headers})
Make a 'sendmsg' request to control a call.
Args:
conn
- The connection map.Kwargs:
:chan-uuid
- The UUID of target channel. Not required in outbound mode.:body
- (optional) Body of the message.Returns:
Reponse of the command.
Note:
To execute a dialplan app or hangup the call, use higher
level funcs like req-call-execute
which provide automated
event listener setup.
Make a 'sendmsg' request to control a call. __Args:__ * `conn` - The connection map. __Kwargs:__ * `:chan-uuid` - The UUID of target channel. Not required in outbound mode. * `:body` - (optional) Body of the message. * Any other keyword arguments are treated as headers for the message. __Returns:__ Reponse of the command. __Note:__ To execute a dialplan app or hangup the call, use higher level funcs like [[req-call-execute]] which provide automated event listener setup.
(unbind-event conn & {:as event-headers})
Unbind the associated handler for an event.
Args:
conn
- The connection map.Kwargs:
Event headers to match against.
Returns:
nil
Unbind the associated handler for an event. __Args:__ * `conn` - The connection map. __Kwargs:__ Event headers to match against. __Returns:__ `nil`
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close