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.
(clear-all-event-handlers conn)
Clears the event handler map of a connection.
Clears the event handler map of a connection.
(close {:keys [aleph-stream event-chan closed? on-close-fn] :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 conn-timeout async-thread-type on-close
incoming-buffer-size]
:or {host "127.0.0.1"
port 8021
password "ClueCon"
conn-timeout 10
async-thread-type :thread
incoming-buffer-size 32}
: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"
.:conn-timeout
- (optional) Connection timeout in seconds.
Defaults to 10
.async-thread-type
- (optional) The type of thread to spawn for event
dispatcher. Valid values are - thread
and go-block
.
Default is - thread
.on-close
- (optional) A single-arity function which will be called after
the connection closes. Call signature is: (fn [fscon])
.incoming-buffer-size
- (optional) Number of messages to buffer on the
receive side before applying back-pressure.
Defaults to 32.You can add extra keyword arguments to fine tune behavior of aleph.tcp/client
function.
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"`. * `:conn-timeout` - (optional) Connection timeout in seconds. Defaults to `10`. * `async-thread-type` - (optional) The type of thread to spawn for event dispatcher. Valid values are - `thread` and `go-block`. Default is - `thread`. * `on-close` - (optional) A single-arity function which will be called after the connection closes. Call signature is: `(fn [fscon])` . * `incoming-buffer-size` - (optional) Number of messages to buffer on the receive side before applying back-pressure. Defaults to 32. You can add extra keyword arguments to fine tune behavior of `aleph.tcp/client` function. __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 custom-init-fn pre-init-fn async-thread-type
on-close incoming-buffer-size]
:or {custom-init-fn nil
pre-init-fn nil
async-thread-type :thread
incoming-buffer-size 32}
: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.:custom-init-fn
- (Optional) A function with signature: (fn [conn chan-data])
.
If provided, it will replace the builtin function which sends
initiation rites, like linger
and myevents
upon connection
creation.:pre-init-fn
- (Optional) A function with signature: (fn [conn chan-data])
.
If provided, this function is called before event dispatcher
is turned on and before connection initiation function is called.
If you predictably want to receive all early events sent by
freeswitch, setup your event handlers here.:async-thread-type
- (Optional) A keyword indicating types of threads to spawn
for event handling and dispatch. Valid values are -
:thread
and :go-block
. Default is :thread
.on-close
- (optional) A single-arity function which will be called after
the connection closes. Call signature is: (fn [fscon])
.incoming-buffer-size
- (optional) Number of messages to buffer on the
receive side before applying back-pressure.
Defaults to 32.Returns:
An aleph server object.
Notes:
.close
method of the returned
server object.:go-block
as :async-thread-type
.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. * `:custom-init-fn` - (Optional) A function with signature: `(fn [conn chan-data])`. If provided, it will replace the builtin function which sends initiation rites, like `linger` and `myevents` upon connection creation. * `:pre-init-fn` - (Optional) A function with signature: `(fn [conn chan-data])`. If provided, this function is called before event dispatcher is turned on and before connection initiation function is called. If you predictably want to receive all early events sent by freeswitch, setup your event handlers here. * `:async-thread-type` - (Optional) A keyword indicating types of threads to spawn for event handling and dispatch. Valid values are - `:thread` and `:go-block`. Default is `:thread`. * `on-close` - (optional) A single-arity function which will be called after the connection closes. Call signature is: `(fn [fscon])` . * `incoming-buffer-size` - (optional) Number of messages to buffer on the receive side before applying back-pressure. Defaults to 32. __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. * Two threads/go-blocks are spawned to handle a each connection. If you are on budget, pass `:go-block` as `:async-thread-type`.
(req conn cmd-line cmd-hdrs cmd-body)
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.
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