freeswitch-clj.core — freeswitch-clj 0.2.1

Contains functions to communicate with freeswitch using ESL.

bind-event clj

(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.

Keyword args: All key value pairs are treated as event headers to match against.

Returns: nil

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 clj

(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.

connect clj

(connect &
         {:keys [host port password]
          :or {host "127.0.0.1" port 8021 password "ClueCon"}
          :as kwargs})

Make an inbound connection to freeswitch.

Keyword args:

• :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 clj

(disconnect conn)

Gracefully disconnect from freeswitch by sending an 'exit' command.

Args:

• conn - The connection map.

Returns: nil

listen clj

(listen & {:keys [port handler] :as kwargs})

Listen for outbound connections from freeswitch.

Keyword args:

• :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.

norm-kv clj

(norm-kv [k v])

Convert a key-val pair into a normalized string, joined by colon.

req clj

(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.

req-api clj

(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.

Example: ;; Send a 'status' api request. (println (req-api conn "status"))

req-bgapi clj

(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).

Example: ;; Execute a 'status' api request in background. (req-bgapi conn (fn [conn rslt] (println rslt)) "status")

req-call-execute clj

(req-call-execute conn
                  app-cmd
                  &
                  {:keys [chan-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"

Keyword args:

• :chan-uuid - The UUID of the target channel. Unnecessary in outbound mode.
• :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 clj

(req-cmd conn cmd)

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.

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 clj

(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]).

Keyword args:

• :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.

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 clj

(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.
• Any other keyword arguments are treated as headers for the event.

Returns: Response of the command.

req-sendmsg clj

(req-sendmsg conn & {:keys [chan-uuid body] :as headers})

Make a 'sendmsg' request to control a call.

Args:

• conn - The connection map.

Keyword args:

• :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 clj

(unbind-event conn & {:as event-headers})

Unbind the associated handler for an event.

Args:

• conn - The connection map.

Keyword args: Event headers to match against.

Returns: nil