freeswitch-clj.core — freeswitch-clj 1.3.0-SNAPSHOT-3

Contains functions to communicate with freeswitch using ESL.

ack-closure clj

(ack-closure conn)

ack-drainage clj

(ack-drainage conn)

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.

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 clj

(clear-all-event-handlers conn)

Clears the event handler map of a connection.

close clj

(close {:keys [aleph-stream event-chan resp-chans-queue-atom on-close-fn
               closed?]
        :as conn})

Close a freeswitch connection.

Note:

Normally, you should use disconnect function to gracefully disconnect, which sends protocol epilogue.

close-conn-on-error clj macro

(close-conn-on-error conn & body)

connect clj

(connect &
         {:keys [host port password conn-timeout async-thread-type on-close
                 incoming-buffer-size resp-timeout]
          :or {host "127.0.0.1"
               port 8021
               password "ClueCon"
               conn-timeout 10
               async-thread-type :thread
               incoming-buffer-size 32
               resp-timeout default-server-response-timeout}
          :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.

• :resp-timeout - (optional) Seconds to wait for server response, for some necessary automatic commands. Defaults to 30 seconds. Throws exception after the timeout.

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

default-server-response-timeout clj

disconnect clj

(disconnect conn)

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

Args:

• conn - The connection map.

Returns:

nil

event-dispatcher-key-sort-comparator clj

(event-dispatcher-key-sort-comparator key-a key-b)

listen clj

(listen &
        {:keys [port handler custom-init-fn pre-init-fn async-thread-type
                on-close incoming-buffer-size resp-timeout]
         :or {custom-init-fn nil
              pre-init-fn nil
              async-thread-type :thread
              incoming-buffer-size 32
              resp-timeout default-server-response-timeout}
         :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. conn is automatically closed after handler exits.
• :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.
• :resp-timeout - (optional) Seconds to wait for server response, for some necessary automatic commands. Defaults to 30 seconds. Throws exception after the timeout.

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 clj

(req conn cmd-line cmd-hdrs cmd-body)

Make a request to freeswitch.

Args:

• conn - Freeswitch connection.
• cmd-line - The request to send.
• cmd-hdrs - Request headers map.
• cmd-body - The body of the request.

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
         &
         {:keys [resp-timeout]
          :or {resp-timeout default-server-response-timeout}})

Convenience function to make an api request.

Args:

• conn - The connection map.
• api-cmd - Api command string with arguments.

Kwargs:

• :resp-timeout - (optional) Seconds to wait for server response, before throwing an exception. Defaults to 30 seconds.

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 clj

(req-bgapi conn
           handler
           api-cmd
           &
           {:keys [resp-timeout]
            :or {resp-timeout default-server-response-timeout}})

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.

Kwargs:

• :resp-timeout - (optional) Seconds to wait for server response, before throwing an exception. Defaults to 30 seconds.

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 clj

(req-call-execute
  conn
  app-cmd
  &
  {:keys [chan-uuid event-uuid start-handler end-handler event-lock loops
          resp-timeout]
   :or {event-lock false loops 1 resp-timeout default-server-response-timeout}
   :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.
• :resp-timeout - (optional) Seconds to wait for server response, before throwing an exception. Defaults to 30 seconds.

Returns:

Command response.

req-cmd clj

(req-cmd conn
         cmd
         &
         {:keys [resp-timeout]
          :or {resp-timeout default-server-response-timeout}})

Send a simple command request.

Args:

• conn - The connection map.
• cmd - The command string including additional arguments.

Kwargs:

• :resp-timeout - (optional) Seconds to wait for server response, before throwing an exception. Defaults to 30 seconds.

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 clj

(req-event conn
           handler
           &
           {:keys [event-name resp-timeout]
            :or {resp-timeout default-server-response-timeout}
            :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.

• :resp-timeout - (optional) Seconds to wait for server response, before throwing an exception. Defaults to 30 seconds.

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

(req-sendevent conn
               event-name
               &
               {:keys [body resp-timeout]
                :or {resp-timeout default-server-response-timeout}
                :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.
• :resp-timeout - (optional) Seconds to wait for server response, before throwing an exception. Defaults to 30 seconds.
• 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 resp-timeout]
              :or {resp-timeout default-server-response-timeout}
              :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.
• :resp-timeout - (optional) Seconds to wait for server response, before throwing an exception. Defaults to 30 seconds.
• 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.

req-sync clj

(req-sync conn
          cmd-line
          cmd-hdrs
          cmd-body
          &
          {:keys [resp-timeout]
           :or {resp-timeout default-server-response-timeout}})

Make a request to freeswitch and wait for response.

Args:

• conn - Freeswitch connection.
• cmd-line - The request to send.
• cmd-hdrs - Request headers map.
• cmd-body - The body of the request.

Kwargs:

• :resp-timeout - (optional) Seconds to wait for server response, before throwing an exception. Defaults to 30 seconds.

Returns:

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.

unbind-event clj

(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

warn-on-handler-less-event? clj