FreeSWITCH channels are always, deterministically, in one specific state of a finite state machine. There are rules for going from one state to another, and you can ask FreeSWITCH core to alert your module whenever a channel changes state.

There are 12 states a channel can be in (init, routing, execute, hangup, exchange_media, soft_execute, consume_media, hibernate, reset, park, reporting, destroy), plus the state none, which a channel is supposed to never assume.

State changes are important moments, particularly for billing and accounting (start of media flows, hangup), but you may want to trigger some procedures in other cases too, for example, when a channel is parked.

Our implementation first declares which state changes we want to deal with (LOAD function will register this table with FreeSWITCH core), INIT, and HANGUP.

Then it defines the function we'll use to react to those changes (you can have different functions for each state). Inside the function, you must deal with all state changes.

We use one only function for all state changes, example_on_state_change(). It gets the channel object from the session object has been passed to it, then reads and sets a variable on that channel, checks the state we're in, prints a log line, then calls it a day and returns successfully.