{"id":16389276,"url":"https://github.com/marcelog/elixir_mod_event","last_synced_at":"2025-03-16T16:31:09.293Z","repository":{"id":34628804,"uuid":"38578740","full_name":"marcelog/elixir_mod_event","owner":"marcelog","description":"Elixir client for the FreeSWITCH mod_event_socket","archived":false,"fork":false,"pushed_at":"2023-11-20T22:17:42.000Z","size":39,"stargazers_count":24,"open_issues_count":2,"forks_count":23,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-12T04:32:07.477Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcelog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-07-05T18:09:01.000Z","updated_at":"2024-03-29T02:07:12.000Z","dependencies_parsed_at":"2022-08-28T13:00:49.906Z","dependency_job_id":null,"html_url":"https://github.com/marcelog/elixir_mod_event","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelog%2Felixir_mod_event","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelog%2Felixir_mod_event/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelog%2Felixir_mod_event/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelog%2Felixir_mod_event/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcelog","download_url":"https://codeload.github.com/marcelog/elixir_mod_event/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221665864,"owners_count":16860321,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T04:32:11.042Z","updated_at":"2024-10-27T10:55:01.640Z","avatar_url":"https://github.com/marcelog.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/marcelog/elixir_mod_event.svg)](https://travis-ci.org/marcelog/elixir_mod_event)\n\n# elixir_mod_event\nElixir client for the [FreeSWITCH mod_event_socket](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket).\n\nIt also supports the [mod_erlang_event](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event).\n\n----\n\n# Using it with Mix\n\nTo use it in your Mix projects, first add it as a dependency:\n\n```elixir\ndef deps do\n  [{:elixir_mod_event, \"~\u003e 0.0.6\"}]\nend\n```\nThen run mix deps.get to install it.\n\n----\n\n# Documentation\n\nFeel free to take a look at the [documentation](http://hexdocs.pm/elixir_mod_event/)\nserved by hex.pm or the source itself to find more.\n\n----\n\n# Inbound Mode (TCP connection)\n\n## Starting a TCP connection\nTo connect to FreeSWITCH just start a [Connection](https://github.com/marcelog/elixir_mod_event/blob/master/lib/elixir_mod_event/connection.ex),\nwhich is just a [GenServer](http://elixir-lang.org/docs/v1.0/elixir/GenServer.html) that you\ncan plug into your own supervisor tree.\n```elixir\n\u003e alias FSModEvent.Connection, as: C\n\u003e C.start :connection_name, fs_host, fs_port, fs_password\n{:ok, #PID\u003c0.158.0\u003e}\n```\n\nYou can also start and link the connection:\n```elixir\n\u003e C.start :connection_name, fs_host, fs_port, fs_password\n{:ok, #PID\u003c0.159.0\u003e}\n```\n\n## Results\nWhen executing a command (either in foreground or background) or receiving events,\nthe result will be a [Packet](https://github.com/marcelog/elixir_mod_event/blob/master/lib/elixir_mod_event/packet.ex),\nwith a structure with some fields of interest:\n\n * **success**: Boolean. When executing foreground commands will be true if the command\n was executed successfuly.\n * **type**: String. The type of the packet (e.g: \"text/event-plain\", \"command/reply\", etc).\n * **payload**: Map or String. Depends on the type of the packet.\n * **length**: Payload length, useful when the payload is a string.\n * **job_id**: String. May contain a job id, related to a response or an event.\n * **headers**: Map. Packet headers.\n * **custom_payload**: String. May contain additional payload, depends on the packet and command sent/received.\n\n### Receiving events\n\nTo receive events register processes with a filter function like this:\n```elixir\n\u003e C.start_listening :fs1\n```\n\nThe default filter function will let all events pass through to the process, but\nyou can specify a custom filter function:\n```elixir\n\u003e C.start_listening :fs1, fn(pkt) -\u003e pkt.payload[\"event-name\"] === \"HEARTBEAT\" end\n```\n\nTo unregister the listener process:\n```elixir\n\u003e C.stop_listening :fs1\n```\n\n**NOTE**: The caller process will be monitored and auto-unregister when the registered process dies.\n\n## Examples\n\n### [api](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-api)\nSends a [command](https://freeswitch.org/confluence/display/FREESWITCH/mod_commands).\n\n```elixir\n\u003e C.api :fs1, \"host_lookup\", \"google.com\"\n%FSModEvent.Packet{\n  payload: '173.194.42.78',\n  ...\n}\n```\n\n### [bgapi](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-bgapi)\nLike `api` but runs the command without blocking the process. The calling process will\nreceive a message with the result of the command. Be sure to subscribe to the\n[BACKGROUND_JOB](https://freeswitch.org/confluence/display/FREESWITCH/Event+List#EventList-Otherevents) event.\n\n```elixir\n\u003e C.event :fs1, \"BACKGROUND_JOB\"\n\u003e C.bgapi :fs1, \"md5\", \"some_data\"\n\"b857e1dd-e4de-424e-9ff6-8e05e9a076d9\"\n\u003e flush\n{:fs_job_result, \"b857e1dd-e4de-424e-9ff6-8e05e9a076d9\", %FSModEvent.Packet{\n  custom_payload: '0d9247cbce34aba4aca8d5c887a0f0a4',\n  ...\n}}\n```\n\n### [linger](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-linger)\n```elixir\n\u003e C.linger :fs1\n```\n\n### [nolinger](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-nolinger)\n```elixir\n\u003e C.nolinger :fs1\n```\n\n### [event](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-event)\n```elixir\n\u003e C.event :fs1, \"all\"\n\u003e C.event :fs1, \"CUSTOM\", \"conference::maintenance\"\n```\n\n### [myevents](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-SpecialCase-'myevents')\n```elixir\n\u003e C.myevents :fs1, \"e96b78d8-1dc2-4634-84c4-58366f1a92b1\"\n```\n\n### [divert_events](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-divert_events)\n```elixir\n\u003e C.enable_divert_events :fs1\n\u003e C.disable_divert_events :fs1\n```\n\n### [filter](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-filter)\n```elixir\n\u003e C.filter :fs1, \"Event-Name\", \"CHANNEL_EXECUTE\"\n```\n\n### [filter_delete](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-filterdelete)\n```elixir\n\u003e C.filter_delete :fs1, \"Event-Name\", \"CHANNEL_EXECUTE\"\n```\n\n### [sendevent](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-sendevent)\n```elixir\n\u003e C.sendevent :fs1, \"custom_event\", [{\"header1\", \"value1\"}], \"custom payload\"\n```\n\n### [sendmsg](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-sendmsg)\n```elixir\n\u003e C.sendmsg_exec :fs1, \"e96b78d8-1dc2-4634-84c4-58366f1a92b1\", \"uuid_answer\", \"e96b78d8-1dc2-4634-84c4-58366f1a92b1\"\n\u003e C.sendmsg_hangup :fs1, \"e96b78d8-1dc2-4634-84c4-58366f1a92b1\", 16\n\u003e C.sendmsg_unicast :fs1, \"e96b78d8-1dc2-4634-84c4-58366f1a92b1\", \"tcp\", \"native\", \"127.0.0.1\", 8025, \"127.0.0.1\", 8026\n\u003e C.sendmsg_nomedia :fs1, \"e96b78d8-1dc2-4634-84c4-58366f1a92b1\", \"info\"\n```\n\n### [exit](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-exit)\n```elixir\n\u003e C.exit :fs1\n```\n\n### [log](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-log)\n```elixir\n\u003e C.log :fs1, \"debug\"\n```\n\n### [nolog](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-nolog)\n```elixir\n\u003e C.nolog :fs1\n```\n\n### [nixevent](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-nixevent)\n```elixir\n\u003e C.nixevent :fs1, \"all\"\n```\n\n### [noevents](https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket#mod_event_socket-noevents)\n```elixir\n\u003e C.noevents :fs1\n```\n\n----\n\n# Inbound Mode (Erlang node connection)\n\nTo \"talk\" to the FreeSWITCH erlang node, use the [Erlang](https://github.com/marcelog/elixir_mod_event/blob/master/lib/elixir_mod_event/erlang.ex) module:\n\n```elixir\n\u003e alias FSModEvent.Erlang, as: E\n\u003e node = :\"freeswitch@host.local\"\n```\n\n### [api](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event#mod_erlang_event-api)\nSends a [command](https://freeswitch.org/confluence/display/FREESWITCH/mod_commands).\n\n```elixir\n\u003e E.api node, \"host_lookup\", \"google.com\"\n\"173.194.42.82\"\n```\n\n### [bgapi](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event#mod_erlang_event-bgapi)\nLike `api` but runs the command without blocking the process. The caller process will\nreceive a message with a tuple like this:\n\n```elixir\n  {:fs_job_result, job_id, status, result}\n```\n\n  Where:\n\n```elixir\n  job_id :: String.t\n\n  status :: :ok | :error\n\n  result :: :timeout | String.t\n```\n\n```elixir\n\u003e E.bgapi node, \"md5\", \"some_data\"\n\"4a41cfc1-d9b7-4966-95d0-5de5ec690a07\"\n\n\u003e flush\n{:fs_job_result, \"4a41cfc1-d9b7-4966-95d0-5de5ec690a07\", :ok,\n \"0d9247cbce34aba4aca8d5c887a0f0a4\"}\n```\n\n### [register_event_handler](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event#mod_erlang_event-register_event_handler)\n```elixir\n\u003e E.register_event_handler node\n```\n\n### [event](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event#mod_erlang_event-event)\n```elixir\n\u003e E.event node, \"all\"\n\u003e E.event node, \"CUSTOM\", \"conference::maintenance\"\n```\n\n### [nixevent](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event#mod_erlang_event-nixevent)\n```elixir\n\u003e E.nixevent node, \"all\"\n```\n\n### [noevents](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event#mod_erlang_event-noevents)\n```elixir\n\u003e E.noevents node\n```\n\n### [register_log_handler](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event#mod_erlang_event-register_log_handler)\n```elixir\n\u003e E.register_log_handler node\n```\n\n### [set_log_level](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event#mod_erlang_event-set_log_level)\n```elixir\n\u003e E.set_log_level node, \"debug\"\n```\n\n### [nolog](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event#mod_erlang_event-nolog)\n```elixir\n\u003e E.nolog node\n```\n\n### [exit](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event#mod_erlang_event-exit)\n```elixir\n\u003e E.exit node\n```\n\n### [sendmsg](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event#mod_erlang_event-sendmsg)\n```elixir\n\u003e E.sendmsg_exec node, \"e96b78d8-1dc2-4634-84c4-58366f1a92b1\", \"uuid_answer\", \"e96b78d8-1dc2-4634-84c4-58366f1a92b1\"\n\u003e E.sendmsg_hangup node, \"e96b78d8-1dc2-4634-84c4-58366f1a92b1\", 16\n\u003e E.sendmsg_unicast node, \"e96b78d8-1dc2-4634-84c4-58366f1a92b1\", \"tcp\", \"native\", \"127.0.0.1\", 8025, \"127.0.0.1\", 8026\n\u003e E.sendmsg_nomedia node, \"e96b78d8-1dc2-4634-84c4-58366f1a92b1\", \"info\"\n```\n\n### [pid](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event#mod_erlang_event-getpid)\n```elixir\n\u003e E.pid node\n```\n\n### [handlecall](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event#mod_erlang_event-handlecall)\n```elixir\n\u003e E.handlecall node, \"e96b78d8-1dc2-4634-84c4-58366f1a92b1\"\n\u003e E.handlecall node, \"e96b78d8-1dc2-4634-84c4-58366f1a92b1\", :my_call_handler\n```\n\n### Configuration hooks\nYou can also configure FreeSWITCH by sending and receiving regular erlang messages by\nbinding to the needed configuration sections. See [XML Search Bindings](https://freeswitch.org/confluence/display/FREESWITCH/mod_erlang_event#mod_erlang_event-XMLsearchbindings).\n\nThe format and sections correspond to the ones supported by [mod_xml_curl](https://freeswitch.org/confluence/display/FREESWITCH/mod_xml_curl).\n\n```elixir\n# Bind to the \"directory\" section\n\u003e E.config_bind node, \"directory\"\n\n# Sample XML text\n\u003e xml = \"\u003c?xml version='1.0' en ... \"\n\n# After a configuration message is received, a reply can be sent.\n\u003e receive do\n    {:fetch, :directory, \"domain\", \"name\", domain_name, uuid, headers} -\u003e\n      E.config_reply node, uuid, xml\n  after 10 -\u003e :ok\n  end\n```\n\n----\n\n# License\nThe source code is released under Apache 2 License.\n\nCheck [LICENSE](https://github.com/marcelog/elixir_mod_event/blob/master/LICENSE) file for more information.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcelog%2Felixir_mod_event","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcelog%2Felixir_mod_event","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcelog%2Felixir_mod_event/lists"}