api 1.6.0 changes

8/8/2019 API 1.6.0 Changes

1/92

Table of Contents

ast_agi_register...........................................................................................................................................4

ast_aji_send................................................................................................................................................ 5

ast_agi_unregister.......................................................................................................................................6

ast_append_ha............................................................................................................................................ 7

ast_category_new.......................................................................................................................................8

ast_cdr_serialize_variables.......................................................................................................................10

ast_channel_alloc..................................................................................................................................... 11

ast_channel_whisper_feed........................................................................................................................12

ast_channel_whisper_start....................................................................................................................... 13

ast_channel_whisper_stop........................................................................................................................ 14

ast_config_internal_load.......................................................................................................................... 15

ast_config_load........................................................................................................................................ 16

ast_console_toggle_mute......................................................................................................................... 17

ast_control_streamfile.............................................................................................................................. 18

ast_ctime.................................................................................................................................................. 20ast_ctime_r............................................................................................................................................... 20

ast_dtmf_stream....................................................................................................................................... 21

ast_dynamic_str_create............................................................................................................................ 23

ast_dynamic_str_thread_get.....................................................................................................................23

ast_dynamic_str_set................................................................................................................................. 23

ast_dynamic_str_thread_set..................................................................................................................... 23

ast_dynamic_str_thread_set_va................................................................................................................23

ast_dynamic_str_append.......................................................................................................................... 23

ast_dynamic_str_thread_append.............................................................................................................. 23

ast_dynamic_str_thread_append_va........................................................................................................ 23

ast_dynamic_str_thread_build_va............................................................................................................23

aes_encrypt_key128 ................................................................................................................................ 26

aes_encrypt_key192 ................................................................................................................................ 26

aes_encrypt_key256 ................................................................................................................................26

aes_encrypt_key ......................................................................................................................................26

aes_encrypt ..............................................................................................................................................26

aes_decrypt_key128 ................................................................................................................................ 26

aes_decrypt_key192 ................................................................................................................................ 26

aes_decrypt_key256 ................................................................................................................................26

aes_decrypt_key ......................................................................................................................................26

aes_decrypt ..............................................................................................................................................26ast_expr.................................................................................................................................................... 29

ast_get_enum............................................................................................................................................33

ast_hint_state_changed.............................................................................................................................35

ast_http_callback......................................................................................................................................36

ast_http_error........................................................................................................................................... 37

ast_http_setcookie.................................................................................................................................... 38

1

8/8/2019 API 1.6.0 Changes

2/92

AST_LIST_INSERT_BEFORE_CURRENT.......................................................................................... 39

AST_LIST_REMOVE_CURRENT.........................................................................................................39

ast_localtime............................................................................................................................................ 40

ast_mktime............................................................................................................................................... 41

ast_netsock_bind...................................................................................................................................... 43

ast_netsock_bindaddr...............................................................................................................................44

ast_monitor_start......................................................................................................................................45ast_rtp_get_quality................................................................................................................................... 46

ast_rtp_settos............................................................................................................................................48

ast_senddigit.............................................................................................................................................49

ast_senddigit_end.....................................................................................................................................50

ast_stream_and_wait................................................................................................................................ 51

ast_string_field_count..............................................................................................................................53

ast_string_field_free.................................................................................................................................53

ast_string_field_free_pools......................................................................................................................53

ast_string_field_free_all...........................................................................................................................53

ast_string_field_index.............................................................................................................................. 53

ast_string_field_index_free......................................................................................................................53

AST_THREADSTORAGE......................................................................................................................54

ast_tzsetwall............................................................................................................................................. 55

ast_variable_delete...................................................................................................................................56

ast_variable_new......................................................................................................................................58

ast_variable_update..................................................................................................................................59

config_load_func......................................................................................................................................61

fsk_serie................................................................................................................................................... 62

pbx_builtin_serialize_variables............................................................................................................... 63

struct agi_command................................................................................................................................. 64

struct aji_buddy........................................................................................................................................64struct aji_client......................................................................................................................................... 64

struct ast_call_feature...............................................................................................................................64

struct ast_channel..................................................................................................................................... 64

struct ast_channel_tech............................................................................................................................ 64

struct ast_cli_entry................................................................................................................................... 65

struct ast_custom_function.......................................................................................................................65

struct ast_datastore................................................................................................................................... 65

struct ast_dynamic_str..............................................................................................................................65

struct ast_filestream................................................................................................................................. 65

struct ast_format.......................................................................................................................................65

struct ast_format_list................................................................................................................................ 66struct ast_frame........................................................................................................................................ 66

struct ast_ha..............................................................................................................................................66

struct ast_http_uri.....................................................................................................................................66

struct ast_lastreloadtime...........................................................................................................................66

struct manager_action.............................................................................................................................. 66

2

8/8/2019 API 1.6.0 Changes

3/92

struct message.......................................................................................................................................... 67

struct ast_option_flags............................................................................................................................. 67

struct ast_rtp_protocol..............................................................................................................................67

struct ast_smdi_interface..........................................................................................................................67

struct ast_speech_engine.......................................................................................................................... 67

struct ast_speech_result............................................................................................................................67

struct ast_startuptime............................................................................................................................... 68struct ast_string_field_mgr...................................................................................................................... 68

struct ast_udptl_protocol.......................................................................................................................... 68

struct ast_variable.....................................................................................................................................68

char debug_filename................................................................................................................................ 68

struct fsk_data.......................................................................................................................................... 68

struct tone_zone....................................................................................................................................... 69

struct ast_audiohook.................................................................................................................................70

struct ast_flags......................................................................................................................................... 70

struct ast_rtp_quality................................................................................................................................ 71

struct ast_str..............................................................................................................................................71

struct ast_tcptls_session_instance ........................................................................................................... 72

struct ast_tm............................................................................................................................................. 72

3

8/8/2019 API 1.6.0 Changes

4/92

Function ast_agi_register

Location /include/asterisk/agi.h

1.4.0 prototype int ast_agi_register(agi_command *cmd);

1.6.0 prototype int ast_agi_register(struct ast_module *mod,

agi_command *cmd);

Changed

explanation

module parameter added to keep track which module

registered the AGI command as well as the reference

count

New types or

variables

none

No code examples required.

4

8/8/2019 API 1.6.0 Changes

5/92

Function ast_aji_send

Location /include/asterisk/jabber.h

1.4.0 prototype int ast_aji_send(struct aji_client *client, char

*address, char *message);

1.6.0 prototype int ast_aji_send_chat(struct aji_client *client,

char *address, char *message);

Changed

explanation

function renamed for clarity

New types or

variables

none

Note: a new ast_aji_send function is in 1.6.0

1.4.0 example:

static int manager_jabber_send( struct mansession *s, struct message

*m )

{

struct aji_client *client = NULL;

char *id = astman_get_header(m,"ActionID");

char *jabber = astman_get_header(m,"Jabber");

char *screenname = astman_get_header(m,"ScreenName");

char *message = astman_get_header(m,"Message");

...if (strchr(screenname, '@') && message){

--> ast_aji_send(client, screenname, message);

if (!ast_strlen_zero(id))

astman_append(s, "ActionID: %s\r\n",id);

astman_append(s, "Response: Success\r\n");

return 0;

}

...

1.6.0 example:

Exactly the same as above, except using the new function name:

--> ast_aji_send_chat(client, screenname, message);

5

8/8/2019 API 1.6.0 Changes

6/92

Function ast_agi_unregister


1.4.0 prototype void ast_agi_unregister(agi_command *cmd);

1.6.0 prototype int ast_agi_unregister(struct ast_module *mod,

agi_command *cmd);

Changed

explanation

module checked to modify usecount only if mod is not

the same as self

New types or

variables

none


6

8/8/2019 API 1.6.0 Changes

7/92

Function ast_append_ha

Location /include/asterisk/acl.h

1.4.0 prototype struct ast_ha *ast_append_ha(char *sense, char

*stuff, struct ast_ha *path);

1.6.0 prototype struct ast_ha *ast_append_ha(const char *sense,

const char *stuff, struct ast_ha *path, int *error);

Changed

explanation

optionally can pass int pointer which will be set to

1 upon any error

New types or

variables

none

1.4.0 example:

static struct sip_peer *build_peer(const char *name, struct

ast_variable *v, struct ast_variable *alt, int realtime){

...

if (!strcasecmp(v->name, "permit") || !strcasecmp(v->name,

"deny")) {

--> peer->ha = ast_append_ha(v->name, v->value, peer->ha);

}

1.6.0 example:

static struct sip_peer *build_peer(const char *name, structast_variable *v, struct ast_variable *alt, int realtime)

{

...

if (!strcasecmp(v->name, "permit") || !strcasecmp(v->name,

"deny")) {

int ha_error = 0;

--> peer->ha = ast_append_ha(v->name, v->value, peer->ha,

&ha_error);

if (ha_error)

ast_log(LOG_ERROR, "Bad ACL entry in configuration line%d : %s\n", v->lineno, v->value);

7

8/8/2019 API 1.6.0 Changes

8/92

Function ast_category_new

Location /include/asterisk/config.h

1.4.0 prototype struct ast_category *ast_category_new(const char

*name);

1.6.0 prototype struct ast_category *ast_category_new(const char

*name, const char *in_file, int lineno);

Changed

explanation

file and line numbers are used to determine exactly

where to save

New types or

variables

none

1.4.0 example:

static struct ast_config *realtime_directory(char *context){

struct ast_config *cfg;

struct ast_config *rtdata;

struct ast_category *cat;

struct ast_variable *var;

char *mailbox;

const char *fullname;

const char *hidefromdir;

char tmp[100];

/* Load flat file config. */

cfg = ast_config_load(VOICEMAIL_CONFIG);

/* Get realtime entries, categorized by their mailbox number

and present in the requested context */

rtdata = ast_load_realtime_multientry("voicemail", "mailbox

LIKE", "%", "context", context, NULL);

/* Context exist within the config file? If not, make one */

cat = ast_category_get(cfg, context);if (!cat) {

--> cat = ast_category_new(context);

...

8

8/8/2019 API 1.6.0 Changes

9/92

(continued)

1.6.0 example:

static struct ast_config *realtime_directory(char *context)

{


struct ast_config *rtdata;

struct ast_category *cat;

struct ast_variable *var;

char *mailbox;

struct ast_flags config_flags = { 0 };

/* Load flat file config. */

cfg = ast_config_load(VOICEMAIL_CONFIG, config_flags);

/* Get realtime entries, categorized by their mailbox number

and present in the requested context */

rtdata = ast_load_realtime_multientry("voicemail", "mailbox

LIKE", "%", "context", context, NULL);

/* Context exist within the config file? If not, make one */

cat = ast_category_get(cfg, context);

if (!cat) {

--> cat = ast_category_new(context, "", 99999);

...

9

8/8/2019 API 1.6.0 Changes

10/92

Function ast_cdr_serialize_variables

Location /include/asterisk/cli.h

1.4.0 prototype int ast_cdr_serialize_variables(struct ast_cdr *cdr,

char *buf, size_t size, char delim, char sep, int

recur);

1.6.0 prototype int ast_cdr_serialize_variables(struct ast_cdr *cdr,

struct ast_str **buf, char delim, char sep, int

recur);

Changed

explanation

ast_str is a nicer string data structure allowing

support for dynamic strings

New types or

variables

ast_str see page 91

/* both code examples assume 1 is a valid channel */

1.4.0 example:

char buf[2048];

struct ast_channel *c = ast_get_channel_by_name_locked(1);

--> if(c->cdr && ast_cdr_serialize_variables(c->cdr,buf, sizeof(buf),

'=', '\n', 1))

ast_cli(fd," CDR Variables:\n%s\n",buf);

1.6.0 example:

struct ast_str *out = ast_str_create(100);


--> if (c->cdr && ast_cdr_serialize_variables(c->cdr, &out, '=',

'\n', 1))

ast_cli(a->fd," CDR Variables:\n%s\n", out->str);

10

8/8/2019 API 1.6.0 Changes

11/92

Function ast_channel_alloc

Location /include/asterisk/channel.h

1.4.0 prototype struct ast_channel *ast_channel_alloc(int

needalertpipe, int state, const char *cid_num, const

char *cid_name, const char *name_fmt, ...);

1.6.0 prototype struct ast_channel *ast_channel_alloc(int needqueue,

int state, const char *cid_num, const char

*cid_name, const char *acctcode, const char *exten,

const char *context, const int amaflag, const char

*name_fmt, ...);

Changed

explanation

these channel properties are used for ast_cdr_init

New types or

variables

none

1.4.0 example:

int ast_masq_park_call(struct ast_channel *rchan, struct ast_channel

*peer, int timeout, int *extout)

{

struct ast_channel *chan;

struct ast_frame *f;

/* Make a new, fake channel that we'll use to masquerade in thereal one */

--> if (!(chan = ast_channel_alloc(0, AST_STATE_DOWN, 0, 0, "Parked/

%s",rchan->name))) {

...

1.6.0 example:

int ast_masq_park_call(struct ast_channel *rchan, struct ast_channel

*peer, int timeout, int *extout)

{struct ast_channel *chan;


char *orig_chan_name = NULL;

/* Make a new, fake channel that we'll use to masquerade in the

11

8/8/2019 API 1.6.0 Changes

12/92

real one */

--> if (!(chan = ast_channel_alloc(0, AST_STATE_DOWN, 0, 0, rchan-

>accountcode, rchan->exten, rchan->context, rchan->amaflags, "Parked/

%s",rchan->name))) {

...

12

8/8/2019 API 1.6.0 Changes

13/92

Function ast_channel_whisper_feed


1.4.0 prototype int ast_channel_whisper_feed(struct ast_channel

*chan, struct ast_frame *f);

1.6.0 prototype int ast_audiohook_write_frame(struct ast_audiohook

*audiohook, enum ast_audiohook_direction direction,

struct ast_frame *frame);

Changed

explanation

new audiohooks API redesigned to be better, more

stable, and allow easy addition of features

New types or

variables

ast_audiohook see page 90

1.4.0 example:

if ((beepstream = ast_openstream_full(chan, "beep", chan->language,

1))) {


while ((f = ast_readframe(beepstream))) {

--> ast_channel_whisper_feed(csth.spy.chan, f);

ast_frfree(f);

}

ast_closestream(beepstream);chan->stream = NULL;

}

1.6.0 example:

if (ast_test_flag(flags, OPTION_WHISPER) && f->frametype ==

AST_FRAME_VOICE) {

ast_audiohook_lock(&csth.whisper_audiohook);

--> ast_audiohook_write_frame(&csth.whisper_audiohook,

AST_AUDIOHOOK_DIRECTION_WRITE, f);ast_audiohook_unlock(&csth.whisper_audiohook);

ast_frfree(f);

continue;

}

13

8/8/2019 API 1.6.0 Changes

14/92

Function ast_channel_whisper_start


1.4.0 prototype int ast_channel_whisper_start(struct ast_channel

*chan);

1.6.0 prototype int ast_audiohook_init(struct ast_audiohook

*audiohook, enum ast_audiohook_type type, const char

*source);

Changed

explanation



New types or

variables


1.4.0 example:

if (ast_test_flag(flags, OPTION_WHISPER)) {

struct ast_filestream *beepstream;

int old_write_format = 0;

--> ast_channel_whisper_start(csth.spy.chan);

old_write_format = chan->writeformat;

...

1.6.0 example:


--> ast_audiohook_init(&csth.whisper_audiohook,

AST_AUDIOHOOK_TYPE_WHISPER, "ChanSpy");

start_spying(spyee, spyer_name, &csth.whisper_audiohook);

}

14

8/8/2019 API 1.6.0 Changes

15/92

Function ast_channel_whisper_stop


1.4.0 prototype void ast_channel_whisper_stop(struct ast_channel

*chan);

1.6.0 prototype int ast_audiohook_detach(struct ast_audiohook

*audiohook);

int ast_audiohook_destroy(struct ast_audiohook

*audiohook);

Changed

explanation



New types or

variables


1.4.0 example:

if (ast_test_flag(flags, OPTION_WHISPER) && csth.spy.chan)

--> ast_channel_whisper_stop(csth.spy.chan);

1.6.0 example:


ast_audiohook_lock(&csth.whisper_audiohook);

--> ast_audiohook_detach(&csth.whisper_audiohook);

ast_audiohook_unlock(&csth.whisper_audiohook);--> ast_audiohook_destroy(&csth.whisper_audiohook);

}

15

8/8/2019 API 1.6.0 Changes

16/92

Function ast_config_internal_load


1.4.0 prototype struct ast_config *ast_config_internal_load(const

char *configfile, struct ast_config *cfg, int

withcomments);

1.6.0 prototype struct ast_config *ast_config_internal_load(const

char *configfile, struct ast_config *cfg, struct

ast_flags flags, const char *suggested_incl_file,

const char *who_asked);

Changed

explanation

ast_flags parameter now handles comment flags,

suggested_include_file is used for keeping track of

destination file, and who_asked is used for config

file caching in the event the same file is loaded

for different modules

New types or

variables

ast_flags see page 90

1.4.0 example:

int read_config_maps(void)

{

struct ast_config *config, *configtmp;

struct ast_variable *v;

char *driver, *table, *database, *stringp;

clear_config_maps();

configtmp = ast_config_new();

configtmp->max_include_level = 1;

--> config = ast_config_internal_load(extconfig_conf, configtmp, 0);

1.6.0 example:

int read_config_maps(void)

{struct ast_config *config, *configtmp;


char *driver, *table, *database, *stringp, *tmp;

struct ast_flags flags = { 0 };

16

8/8/2019 API 1.6.0 Changes

17/92

clear_config_maps();

configtmp = ast_config_new();

configtmp->max_include_level = 1;

--> config = ast_config_internal_load(extconfig_conf, configtmp,

flags, "", "config.c");

17

8/8/2019 API 1.6.0 Changes

18/92

Function ast_config_load


1.4.0 prototype struct ast_config *ast_config_load(const char

*filename);

1.6.0 prototype #define ast_config_load(filename, flags)

ast_config_load2(filename, __FILE__, flags)

Changed

explanation

flags parameter allows more flexbility in loading

the config file:

CONFIG_FLAG_WITHCOMMENTS - load the file with

comments intact

CONFIG_FLAG_FILEUNCHANGED reload only if file

mtime has changed

CONFIG_FLAG_NOCACHE - don't cache file mtime

New types or

variables

none

1.4.0 example:

int ast_rtp_reload(void)

{


const char *s;

rtpstart = 5000;rtpend = 31000;

dtmftimeout = DEFAULT_DTMF_TIMEOUT;

--> cfg = ast_config_load("rtp.conf");

...

1.6.0 example:

static int __ast_rtp_reload(int reload)

{

struct ast_config *cfg;const char *s;

struct ast_flags config_flags = { reload ?

CONFIG_FLAG_FILEUNCHANGED : 0 };

--> if ((cfg = ast_config_load("rtp.conf", config_flags)) ==

18

8/8/2019 API 1.6.0 Changes

19/92

CONFIG_STATUS_FILEUNCHANGED)

return 0;

...

19

8/8/2019 API 1.6.0 Changes

20/92

Function ast_console_toggle_mute

Location /include/asterisk/logger.h

1.4.0 prototype void ast_console_toggle_mute(int fd);

1.6.0 prototype void ast_console_toggle_mute(int fd, int silent);

Changedexplanation

silent flag determines if silence info is printed toconsole

New types or

variables

none

1.4.0 example:

static int handle_logger_mute(int fd, int argc, char *argv[])

{

if (argc != 2)return RESULT_SHOWUSAGE;

--> ast_console_toggle_mute(fd);

return RESULT_SUCCESS;

}

1.6.0 example:

static char *handle_logger_mute(struct ast_cli_entry *e, int cmd,

struct ast_cli_args *a)

{switch (cmd) {

case CLI_INIT:

e->command = "logger mute";

e->usage =

"Usage: logger mute\n"

" Disables logging output to the current console,

making it possible to\n"

" gather information without being disturbed by

scrolling lines.\n";

return NULL;case CLI_GENERATE:

return NULL;

}

...

if (a->argc == 3 && !strcasecmp(a->argv[2], "silent"))

20

8/8/2019 API 1.6.0 Changes

21/92

--> ast_console_toggle_mute(a->fd, 1);

else

--> ast_console_toggle_mute(a->fd, 0);

return CLI_SUCCESS;

}

21

8/8/2019 API 1.6.0 Changes

22/92

Function ast_control_streamfile

Location /include/asterisk/app.h

1.4.0 prototype int ast_control_streamfile(struct ast_channel *chan,

const char *file, const char *fwd, const char *rev,

const char *stop, const char *pause, const char

*restart, int skipms);

1.6.0 prototype int ast_control_streamfile(struct ast_channel *chan,

const char *file, const char *fwd, const char *rev,

const char *stop, const char *pause, const char

*restart, int skipms, long *offsetms);

Changed

explanation

offsetms parameter determines how far to start

playing from (assuming 8kHz)

New types or

variables

none

1.4.0 example:

static int controlplayback_exec(struct ast_channel *chan, void *data)

{

int res = 0, priority_jump = 0;

int skipms = 0;

struct ast_module_user *u;

char *tmp;

int argc;char *argv[8];

enum arg_ids {

arg_file = 0,

arg_skip = 1,

arg_fwd = 2,

arg_rev = 3,

arg_stop = 4,

arg_pause = 5,

arg_restart = 6,

options = 7,};

skipms = argv[arg_skip] ? atoi(argv[arg_skip]) : 3000;

...

--> res = ast_control_streamfile(chan, argv[arg_file], argv[arg_fwd],

argv[arg_rev], argv[arg_stop], argv[arg_pause], argv[arg_restart],

22

8/8/2019 API 1.6.0 Changes

23/92

skipms);

...

23

8/8/2019 API 1.6.0 Changes

24/92

(continued)

1.6.0 example:

static int controlplayback_exec(struct ast_channel *chan, void *data)

{

int res = 0;

int skipms = 0;

long offsetms = 0;

char offsetbuf[20];

char stopkeybuf[2];

char *tmp;

struct ast_flags opts = { 0, };

char *opt_args[OPT_ARG_ARRAY_LEN];

AST_DECLARE_APP_ARGS(args,

AST_APP_ARG(filename);

AST_APP_ARG(skip);

AST_APP_ARG(fwd);

AST_APP_ARG(rev);

AST_APP_ARG(stop);

AST_APP_ARG(pause);

AST_APP_ARG(restart);

AST_APP_ARG(options);

);

skipms = args.skip ? (atoi(args.skip) ? atoi(args.skip) : 3000) :

3000;

...

if (args.options) {

ast_app_parse_options(cpb_opts, &opts, opt_args,

args.options);

if (ast_test_flag(&opts, OPT_OFFSET))

offsetms = atol(opt_args[OPT_ARG_OFFSET]);

}

--> res = ast_control_streamfile(chan, args.filename, args.fwd,

args.rev, args.stop, args.pause, args.restart, skipms, &offsetms);

...

24

8/8/2019 API 1.6.0 Changes

25/92

Function ast_ctime

ast_ctime_r

Location /include/asterisk/localtime.h

1.4.0 prototype char *ast_ctime(const time_t * const timep);

char *ast_ctime_r(const time_t * const timep, char

*buf);

1.6.0 prototype int ast_strftime(char *buf, size_t len, const char

*format, const struct ast_tm *tm);

Changed

explanation

function consolidation for easier usage and finer

time precision

New types or

variables

ast_tm see page 92

1.4.0 example:

char date[256];

time_t now;

time(&now);

--> ast_ctime_r(now, date);

1.6.0 example:

char date[256];

struct ast_tm tm;/* Set date format for voicemail mail */

--> ast_strftime(date, sizeof(date), "%A, %B %d, %Y at %r", &tm);

25

8/8/2019 API 1.6.0 Changes

26/92

Function ast_dtmf_stream

Location /include/asterisk/app.h

1.4.0 prototype int ast_dtmf_stream(struct ast_channel *chan, struct

ast_channel *peer, const char *digits, int between);

1.6.0 prototype int ast_dtmf_stream(struct ast_channel *chan, struct

ast_channel *peer, const char *digits, int between,

unsigned int duration);

Changed

explanation

duration parameter specifies length digit is played

given that duration is longer than

AST_DEFAULT_EMULATE_DTMF_DURATION (100ms)

New types or

variables

none

1.4.0 example:

static int senddtmf_exec(struct ast_channel *chan, void *data)

{

int res = 0;

struct ast_module_user *u;

char *digits = NULL, *to = NULL;

int timeout = 250;

if (ast_strlen_zero(data)) {

ast_log(LOG_WARNING, "SendDTMF requires an argument (digitsor *#aAbBcCdD)\n");

return 0;

}

u = ast_module_user_add(chan);

digits = ast_strdupa(data);

if ((to = strchr(digits,'|'))) {

*to = '\0';to++;

timeout = atoi(to);

}

if (timeout

8/8/2019 API 1.6.0 Changes

27/92

timeout = 250;

--> res = ast_dtmf_stream(chan,NULL,digits,timeout);

ast_module_user_remove(u);

return res;

}

27

8/8/2019 API 1.6.0 Changes

28/92

(continued)

1.6.0 example:

static int senddtmf_exec(struct ast_channel *chan, void *vdata)

{

int res = 0;

char *data;

int timeout = 0, duration = 0;


AST_APP_ARG(digits);

AST_APP_ARG(timeout);

AST_APP_ARG(duration);

);

if (ast_strlen_zero(vdata)) {

ast_log(LOG_WARNING, "SendDTMF requires an argument (digits

or *#aAbBcCdD)\n");

return 0;

}

data = ast_strdupa(vdata);

AST_STANDARD_APP_ARGS(args, data);

if (!ast_strlen_zero(args.timeout))

timeout = atoi(args.timeout);

if (!ast_strlen_zero(args.duration))

duration = atoi(args.duration);

--> res = ast_dtmf_stream(chan, NULL, args.digits, timeout

8/8/2019 API 1.6.0 Changes

29/92

Function ast_dynamic_str_create

ast_dynamic_str_thread_get

ast_dynamic_str_set

ast_dynamic_str_thread_set

ast_dynamic_str_thread_set_va

ast_dynamic_str_append

ast_dynamic_str_thread_append

ast_dynamic_str_thread_append_va

ast_dynamic_str_thread_build_va

Location /include/asterisk/threadstorage.h

1.4.0 prototype

(attributes

removed)

struct ast_dynamic_str

*ast_dynamic_str_create(size_t init_len);

struct ast_dynamic_str

*ast_dynamic_str_thread_get(struct ast_threadstorage

*ts, size_t init_len);

int ast_dynamic_str_set( struct ast_dynamic_str

**buf, size_t max_len, const char *fmt, ...);

ast_dynamic_str_thread_set( struct ast_dynamic_str

**buf, size_t max_len, struct ast_threadstorage *ts,

const char *fmt, ...);

int ast_dynamic_str_thread_set_va(struct

ast_dynamic_str **buf, size_t max_len, struct

ast_threadstorage *ts, const char *fmt, va_list ap);

int ast_dynamic_str_append(struct ast_dynamic_str

**buf, size_t max_len, const char *fmt, ...);

int ast_dynamic_str_thread_append(struct


ast_threadstorage *ts, const char *fmt, ...);

int ast_dynamic_str_thread_append_va(struct


ast_threadstorage *ts, const char *fmt, va_list ap);

int ast_dynamic_str_thread_build_va(struct

29

8/8/2019 API 1.6.0 Changes

30/92


ast_threadstorage *ts, int append, const char *fmt,

va_list ap);

1.6.0 prototype(attributes

removed)

struct ast_str *ast_str_alloca(size_t init_len);

struct ast_str *ast_str_create(size_t init_len);

struct ast_str *ast_str_thread_get(struct

ast_threadstorage *ts, size_t init_len);

int ast_str_set(struct ast_str **buf, size_t

max_len, const char *fmt, ...);

int ast_str_set_va(struct ast_str **buf, size_tmax_len, const char *fmt, va_list ap);

int ast_str_append(struct ast_str **buf, size_t

max_len, const char *fmt, ...);

int ast_str_append_va(struct ast_str **buf, size_t

max_len, const char *fmt, va_list ap);

Changed

explanation

There were multiple string APIs in Asterisk 1.4,

some with overlapping functionality. A new API

(ast_str) was written that centralizes all of the

string API code and was put in strings.h. This was

done so that complex string handling in Asterisk is

more consistent.

New types or

variables

ast_str see page 91

Generally, each function is called in the exact same way, except

using the new ast_str buffer. ast_dynamic_str_thread_append was

replaced with ast_str_append, ast_dyaamic_str_thread_set was replaced

with ast_str_set, and ast_dynamic_str_thread_build_va was replaced

with ast_build_string_va.

1.4.0 example:

30

8/8/2019 API 1.6.0 Changes

31/92

AST_THREADSTORAGE(ast_cli_buf, ast_cli_buf_init);

/*! \brief Initial buffer size for resulting strings in ast_cli() */

#define AST_CLI_INITLEN 256

void ast_cli(int fd, char *fmt, ...)

{

int res;

struct ast_dynamic_str *buf;

va_list ap;

31

8/8/2019 API 1.6.0 Changes

32/92

--> if (!(buf = ast_dynamic_str_thread_get(&ast_cli_buf,

AST_CLI_INITLEN)))

return;

va_start(ap, fmt);

--> res = ast_dynamic_str_thread_set_va(&buf, 0, &ast_cli_buf, fmt,

ap);

va_end(ap);

if (res != AST_DYNSTR_BUILD_FAILED)

ast_carefulwrite(fd, buf->str, strlen(buf->str), 100);

}

1.6.0 example:

AST_THREADSTORAGE(ast_cli_buf);

/*! \brief Initial buffer size for resulting strings in ast_cli() */

#define AST_CLI_INITLEN 256

void ast_cli(int fd, const char *fmt, ...)

{

int res;

struct ast_str *buf;

va_list ap;

--> if (!(buf = ast_str_thread_get(&ast_cli_buf, AST_CLI_INITLEN)))

return;

va_start(ap, fmt);

--> res = ast_str_set_va(&buf, 0, fmt, ap);

va_end(ap);

if (res != AST_DYNSTR_BUILD_FAILED)

ast_carefulwrite(fd, buf->str, strlen(buf->str), 100);

}

32

8/8/2019 API 1.6.0 Changes

33/92

Function aes_encrypt_key128

aes_encrypt_key192

aes_encrypt_key256

aes_encrypt_key

aes_encrypt

aes_decrypt_key128

aes_decrypt_key192

aes_decrypt_key256

aes_decrypt_key

aes_decrypt

Location /include/asterisk/aes.h

1.4.0 prototype aes_rval aes_encrypt_key128(const void *in_key,

aes_encrypt_ctx cx[1]);

aes_rval aes_encrypt_key192(const void *in_key,


aes_rval aes_encrypt_key256(const void *in_key,


aes_rval aes_encrypt_key(const void *in_key, int

key_len, aes_encrypt_ctx cx[1]);

aes_rval aes_encrypt(const void *in_blk, void

*out_blk, const aes_encrypt_ctx cx[1]);

aes_rval aes_decrypt_key128(const void *in_key,

aes_decrypt_ctx cx[1]);





aes_rval aes_decrypt_key(const void *in_key, int

key_len, aes_decrypt_ctx cx[1]);

aes_rval aes_decrypt(const void *in_blk, void

*out_blk, const aes_decrypt_ctx cx[1]);

33

8/8/2019 API 1.6.0 Changes

34/92

1.6.0 prototype Types differ based on available libraries.

int ast_aes_encrypt_key(key, context) ;

int ast_aes_decrypt_key(key, context);

int ast_aes_encrypt(in, out, context);

int ast_aes_decrypt(in, out, context);

Changedexplanation

Functions were unified without reguard to keysize.AES is implemented from the OpenSSL library if

available.

New types or

variables

none

1.4.0 example:

static void build_enc_keys(const unsigned char *digest,

aes_encrypt_ctx *ecx, aes_decrypt_ctx *dcx)

{

--> aes_encrypt_key128(digest, ecx);

--> aes_decrypt_key128(digest, dcx);

}

static void memcpy_decrypt(unsigned char *dst, const unsigned char

*src, int len, aes_decrypt_ctx *dcx)

{

unsigned char lastblock[16] = { 0 };

int x;while(len > 0) {

--> aes_decrypt(src, dst, dcx);

for (x=0;x

8/8/2019 API 1.6.0 Changes

35/92

(continued)

1.6.0 example:

static void build_enc_keys(const unsigned char *digest,

ast_aes_encrypt_key *ecx, ast_aes_decrypt_key *dcx)

{

--> ast_aes_encrypt_key(digest, ecx);

--> ast_aes_decrypt_key(digest, dcx);

}

static void memcpy_decrypt(unsigned char *dst, const unsigned char

*src, int len, ast_aes_decrypt_key *dcx)

{

unsigned char lastblock[16] = { 0 };

int x;

while(len > 0) {

--> ast_aes_decrypt(src, dst, dcx);

for (x=0;x

8/8/2019 API 1.6.0 Changes

36/92

Function ast_expr

Location /include/asterisk/pval.h

1.4.0 prototype int ast_expr(char *expr, char *buf, int length);

1.6.0 prototype int ast_expr(char *expr, char *buf, int length,

struct ast_channel *chan);

Changed

explanation

chan parameter is used for retrieving the values of

dialplan functions

New types or

variables

none

1.4.0 example:

static void pbx_substitute_variables_helper_full(struct ast_channel

*c, struct varshead *headp, const char *cp1, char *cp2, int count){

const char *tmp, *whereweare;

int length, offset, offset2, isfunction;

char *ltmp = NULL, *var = NULL, *workspace = NULL;

char *nextvar, *nextexp, *nextthing, *vars, *vare, *cp4;

int pos, brackets, needsub, len;

whereweare=tmp=cp1;

while (!ast_strlen_zero(whereweare) && count) {

/* Assume we're copying the whole remaining string */pos = strlen(whereweare);

nextvar = NULL;

nextexp = NULL;

nextthing = strchr(whereweare, '$');

if (nextthing) {

switch(nextthing[1]) {

case '{':

nextvar = nextthing;

pos = nextvar - whereweare;

break;case '[':

nextexp = nextthing;

pos = nextexp - whereweare;

break;

}

36

8/8/2019 API 1.6.0 Changes

37/92

}

if (pos) {

/* Can't copy more than 'count' bytes */

if (pos > count)

pos = count;

/* Copy that many bytes */

memcpy(cp2, whereweare, pos);

count -= pos;

cp2 += pos;

whereweare += pos;

}

if (nextvar) {

/* We have a variable. Find the start and end, and

determine if we are going to have to recursively call ourselves on

the contents */

vars = vare = nextvar + 2;

brackets = 1;

needsub = 0;

/* Find the end of it */

while (brackets && *vare) {

if ((vare[0] == '$') && (vare[1] == '{')) {

needsub++;

} else if (vare[0] == '{') {

brackets++;

} else if (vare[0] == '}') {

brackets--;

} else if ((vare[0] == '$') && (vare[1] == '['))

needsub++;

vare++;

}

if (brackets)ast_log(LOG_NOTICE, "Error in extension logic

(missing '}')\n");

len = vare - vars - 1;

/* Skip totally over variable string */

37

8/8/2019 API 1.6.0 Changes

38/92

whereweare += (len + 3);

if (!var)

var = alloca(VAR_BUF_SIZE);

/* Store variable name (and truncate) */

ast_copy_string(var, vars, len + 1);

/* Substitute if necessary */

if (needsub) {

if (!ltmp)

ltmp = alloca(VAR_BUF_SIZE);

memset(ltmp, 0, VAR_BUF_SIZE);

pbx_substitute_variables_helper_full(c, headp, var,

ltmp, VAR_BUF_SIZE - 1);

vars = ltmp;

} else {

vars = var;

}

if (!workspace)

workspace = alloca(VAR_BUF_SIZE);

workspace[0] = '\0';

parse_variable_name(vars, &offset, &offset2,

&isfunction);

if (isfunction) {

/* Evaluate function */

cp4 = ast_func_read(c, vars, workspace, VAR_BUF_SIZE)

? NULL : workspace;

ast_log(LOG_DEBUG, "Function result is '%s'\n", cp4 ?

cp4 : "(null)");

} else {

/* Retrieve variable value */pbx_retrieve_variable(c, vars, &cp4, workspace,

VAR_BUF_SIZE, headp);

}

if (cp4) {

cp4 = substring(cp4, offset, offset2, workspace,

38

8/8/2019 API 1.6.0 Changes

39/92

VAR_BUF_SIZE);

length = strlen(cp4);

if (length > count)

length = count;

memcpy(cp2, cp4, length);

count -= length;

cp2 += length;

}

} else if (nextexp) {

/* We have an expression. Find the start and end, and

determine if we are going to have to recursively call ourselves on

the contents */

vars = vare = nextexp + 2;

brackets = 1;

needsub = 0;

/* Find the end of it */

while(brackets && *vare) {

if ((vare[0] == '$') && (vare[1] == '[')) {

needsub++;

brackets++;

vare++;

} else if (vare[0] == '[') {

brackets++;

} else if (vare[0] == ']') {

brackets--;

} else if ((vare[0] == '$') && (vare[1] == '{')) {

needsub++;

vare++;

}

vare++;

}

if (brackets)

ast_log(LOG_NOTICE, "Error in extension logic

(missing ']')\n");len = vare - vars - 1;

/* Skip totally over expression */

whereweare += (len + 3);

39

8/8/2019 API 1.6.0 Changes

40/92

if (!var)

var = alloca(VAR_BUF_SIZE);

/* Store variable name (and truncate) */

ast_copy_string(var, vars, len + 1);

/* Substitute if necessary */

if (needsub) {

if (!ltmp)

ltmp = alloca(VAR_BUF_SIZE);

memset(ltmp, 0, VAR_BUF_SIZE);

pbx_substitute_variables_helper_full(c, headp, var,

ltmp, VAR_BUF_SIZE - 1);

vars = ltmp;

} else {

vars = var;

}

--> length = ast_expr(vars, cp2, count);

1.6.0 example:

Exactly the same as above, except using the additional chan

parameter.

--> length = ast_expr(vars, cp2, count, chan);

40

8/8/2019 API 1.6.0 Changes

41/92

Function ast_get_enum

Location /include/asterisk/enum.h

1.4.0 prototype int ast_get_enum(struct ast_channel *chan, const

char *number, char *location, int maxloc, char

*technology, int maxtech, char* suffix, char*

options, unsigned int record);

1.6.0 prototype int ast_get_enum(struct ast_channel *chan, const

char *number, char *location, int maxloc, char

*technology, int maxtech, char* suffix, char*

options, unsigned int record, struct enum_context

**argcontext);

Changed

explanation

Save pointer to enum_context which is later added to

the channel datastores. The stored information is

used for ensuring that interating through query

results does not result in repeated queries.

New types or

variables

none

1.4.0 example:

static int function_enum(struct ast_channel *chan, char *cmd, char

*data, char *buf, size_t len)

{

AST_DECLARE_APP_ARGS(args,AST_APP_ARG(number);

AST_APP_ARG(tech);

AST_APP_ARG(options);

AST_APP_ARG(record);

AST_APP_ARG(zone);

);

int res = 0;

char tech[80];

char dest[256] = "", tmp[2] = "";

struct ast_module_user *u;char *s, *p;

unsigned int record = 1;

buf[0] = '\0';

AST_STANDARD_APP_ARGS(args, data);

41

8/8/2019 API 1.6.0 Changes

42/92

ast_copy_string(tech, args.tech ? args.tech : "sip",

sizeof(tech));

...

record = atoi(args.record);

/* assume any '-' signs are stripped from args.number */

--> res = ast_get_enum(chan, args.number, dest, sizeof(dest), tech,

sizeof(tech), args.zone, args.options, record);

1.6.0 example:

static int enum_query_read(struct ast_channel *chan, const char *cmd,

char *data, char *buf, size_t len)

{

struct enum_result_datastore *erds;

struct ast_datastore *datastore;

char *parse, tech[128], dest[128];

int res = -1;


AST_APP_ARG(number);

AST_APP_ARG(tech);

AST_APP_ARG(zone);

);

parse = ast_strdupa(data);

AST_STANDARD_APP_ARGS(args, parse);

if (!args.zone)

args.zone = "e164.zone";

ast_copy_string(tech, args.tech ? args.tech : "sip",

sizeof(tech));

if (!(erds = ast_calloc(1, sizeof(*erds))))

goto finish;

if (!(erds->context = ast_calloc(1, sizeof(*erds->context)))) {

ast_free(erds);

goto finish;

}

42

8/8/2019 API 1.6.0 Changes

43/92

erds->id = ast_atomic_fetchadd_int((int *) &enum_datastore_id,

1);

snprintf(buf, len, "%u", erds->id);

if (!(datastore =

ast_channel_datastore_alloc(&enum_result_datastore_info, buf))) {

ast_free(erds->context);

ast_free(erds);

goto finish;

}

--> ast_get_enum(chan, args.number, dest, sizeof(dest), tech,

sizeof(tech), args.zone, "", 1, &erds->context);

43

8/8/2019 API 1.6.0 Changes

44/92

Function ast_hint_state_changed

Location /include/asterisk/pbx.h

1.4.0 prototype void ast_hint_state_changed(const char *device);

1.6.0 prototype Made private: void handle_statechange(const char

*device)

Changed

explanation

Function made private because device state handling

is now event based. The device state not longer

needs to be pushed to the hint handling.

New types or

variables

none


44

8/8/2019 API 1.6.0 Changes

45/92

Function ast_http_callback

Location /include/asterisk/http.h

1.4.0 prototype typedef char *(*ast_http_callback)(struct

sockaddr_in *requestor, const char *uri, struct

ast_variable *params, int *status, char **title, int

*contentlength);

1.6.0 prototype typedef struct ast_str *(*ast_http_callback)(struct

ast_tcptls_session_instance*ser, const char *uri,

struct ast_variable *params, int *status, char

**title, int *contentlength);

Changed

explanation

parameter changed to support http services over TLS

New types or

variables

ast_tcptls_session_instance see page 92


45

8/8/2019 API 1.6.0 Changes

46/92

Function ast_http_error


1.4.0 prototype char *ast_http_error(int status, const char *title,

const char *extra_header, const char *text);

1.6.0 prototype struct ast_str *ast_http_error(int status, const

char *title, const char *extra_header, const char

*text);

Changed

explanation

ast_str is a better string data structure allowing

support for dynamic strings which uses less memory

New types or

variables

ast_str see page 91

1.4.0 example:

char *c;

c = ast_http_error(404, "Not Found", NULL, "The requested URL was not

found on this serer.");

1.6.0 example:

struct ast_str *out = NULL;

out = ast_http_error(404, "Not Found", NULL,

"The requested URL was not found on this server.");

46

8/8/2019 API 1.6.0 Changes

47/92

8/8/2019 API 1.6.0 Changes

48/92

Function

(both defines)

AST_LIST_INSERT_BEFORE_CURRENT

AST_LIST_REMOVE_CURRENT

Location /include/asterisk/linkedlists.h

1.4.0 prototype AST_LIST_INSERT_BEFORE_CURRENT(head, elm, field),

AST_LIST_REMOVE_CURRENT(head, field)

1.6.0 prototype AST_LIST_INSERT_BEFORE_CURRENT(elm, field),

AST_LIST_REMOVE_CURRENT(field)

Changed

explanation

code improved to no longer require specifying the

head

New types or

variables

none

1.4.0 example:

static void reschedule_precache(const char *number, const char

*context, int expiration)

{

int len;

struct dundi_precache_queue *qe, *prev;

AST_LIST_LOCK(&pcq);

AST_LIST_TRAVERSE_SAFE_BEGIN(&pcq, qe, list) {

if (!strcmp(number, qe->number) && !strcasecmp(context, qe-

>context)) {--> AST_LIST_REMOVE_CURRENT(&pcq, list);

break;

}

}

1.6.0 example:

static void reschedule_precache(const char *number, const char

*context, int expiration)

{int len;

struct dundi_precache_queue *qe, *prev;

AST_LIST_LOCK(&pcq);

AST_LIST_TRAVERSE_SAFE_BEGIN(&pcq, qe, list) {

48

8/8/2019 API 1.6.0 Changes

49/92

if (!strcmp(number, qe->number) && !strcasecmp(context, qe-

>context)) {

--> AST_LIST_REMOVE_CURRENT(list);

break;

}

}

49

8/8/2019 API 1.6.0 Changes

50/92

Function ast_localtime


1.4.0 prototype struct tm *ast_localtime(const time_t *timep, struct

tm *p_tm, const char *zone);

1.6.0 prototype struct ast_tm *ast_localtime(const struct timeval

*timep, struct ast_tm *p_tm, const char *zone);

Changed

explanation

timeval includes further precision to the

microsecond

New types or

variables

ast_tm see page 92

1.4.0 example:

int ast_say_date_en(struct ast_channel *chan, time_t t, const char*ints, const char *lang)

{

struct tm tm;

char fn[256];

int res = 0;

--> ast_localtime(&t,&tm,NULL);

if (!res) {

snprintf(fn, sizeof(fn), "digits/day-%d", tm.tm_wday);

res = ast_streamfile(chan, fn, lang);

...

1.6.0 example:

int ast_say_date_en(struct ast_channel *chan, time_t t, const char

*ints, const char *lang)

{

struct ast_tm tm;

struct timeval tv = { t, 0 };

char fn[256];

int res = 0;--> ast_localtime(&tv, &tm, NULL);

if (!res) {

snprintf(fn, sizeof(fn), "digits/day-%d", tm.tm_wday);

res = ast_streamfile(chan, fn, lang);

...

50

8/8/2019 API 1.6.0 Changes

51/92

Function ast_mktime


1.4.0 prototype time_t ast_mktime(struct tm * const tmp, const char

*zone);

1.6.0 prototype struct timeval ast_mktime(struct ast_tm * const tmp,

const char *zone);

Changed

explanation

timeval includes further precision to the

microsecond

New types or

variables

ast_tm see page 92

1.4.0 example:

static int acf_strptime(struct ast_channel *chan, char *cmd, char*data,

char *buf, size_t len)

{


AST_APP_ARG(timestring);

AST_APP_ARG(timezone);

AST_APP_ARG(format);

);

struct tm time;

memset(&time, 0, sizeof(struct tm));...

if (!strptime(args.timestring, args.format, &time)) {

ast_log(LOG_WARNING, "C function strptime() output

nothing?!!\n");

} else {

--> snprintf(buf, len, "%d", (int) ast_mktime(&time,

args.timezone));

}

...

51

8/8/2019 API 1.6.0 Changes

52/92

(continued)

1.6.0 example:

static int acf_strptime(struct ast_channel *chan, const char *cmd,

char *data,

char *buf, size_t len)

{


AST_APP_ARG(timestring);

AST_APP_ARG(timezone);

AST_APP_ARG(format);

union {

struct ast_tm atm;

struct tm time;

} t = { { 0, }, };

...

struct timeval tv;

/* Since strptime(3) does not check DST, force ast_mktime()

to calculate it. */

t.atm.tm_isdst = -1;

--> tv = ast_mktime(&t.atm, args.timezone);

snprintf(buf, len, "%d", (int) tv.tv_sec);

...

52

8/8/2019 API 1.6.0 Changes

53/92

Function ast_netsock_bind

Location /include/asterisk/netsock.h

1.4.0 prototype struct ast_netsock *ast_netsock_bind(struct

ast_netsock_list *list, struct io_context *ioc,

const char *bindinfo, int defaultport, int tos,

ast_io_cb callback, void *data);



const char *bindinfo, int defaultport, int tos, int

cos, ast_io_cb callback, void *data);

Changed

explanation

Added quality of service parameter to denote

queueing priority to Linux kernel

New types or

variables

none

1.4.0 example:

static unsigned int tos = 0;

static struct ast_netsock_list *netsock;

static struct io_context *io;

struct ast_netsock *ns;

/* assuming netsock and io have already been properly allocated */

--> ns = ast_netsock_bind(netsock, io, "0.0.0.0", 4569, tos,socket_read, NULL)

1.6.0 example:

static unsigned int tos = 0;

static unsigned int cos = 0;

static struct ast_netsock_list *netsock;

static struct io_context *io;

struct ast_netsock *ns;

/* assuming netsock and io have already been properly allocated */

--> ns = ast_netsock_bind(netsock, io, "0.0.0.0", 4569, tos, cos,

socket_read, NULL)

53

8/8/2019 API 1.6.0 Changes

54/92

Function ast_netsock_bindaddr

Location /include/asterisk/netsock.h

1.4.0 prototype struct ast_netsock *ast_netsock_bindaddr(struct


struct sockaddr_in *bindaddr, int tos, ast_io_cb

callback, void *data);



const char *bindinfo, int defaultport, int tos, int

cos, ast_io_cb callback, void *data);

Changed

explanation

Added quality of service parameter to denote

queueing priority to Linux kernel

New types or

variables

none

1.4.0 example:

struct ast_netsock *ast_netsock_bind(struct ast_netsock_list *list,

struct io_context *ioc, const char *bindinfo, int defaultport, int

tos, ast_io_cb callback, void *data)

{

struct sockaddr_in sin;

char *tmp, *host, *port;

int portno;

memset(&sin, 0, sizeof(sin));

sin.sin_family = AF_INET;

sin.sin_port = htons(defaultport);

tmp = ast_strdupa(bindinfo);

host = strsep(&tmp, ":");

port = tmp;

if (port && ((portno = atoi(port)) > 0))

sin.sin_port = htons(portno);

inet_aton(host, &sin.sin_addr);

--> return ast_netsock_bindaddr(list, ioc, &sin, tos, callback,

data);

}

54

8/8/2019 API 1.6.0 Changes

55/92

1.6.0 example:

Same as above, except adding the new cos parameter. In this case, the

function would need modifying to pass cos in as a parameter as well.

--> return ast_netsock_bindaddr(list, ioc, &sin, tos, cos, callback,

data);

55

8/8/2019 API 1.6.0 Changes

56/92

Function ast_monitor_start

Location /include/asterisk/monitor.h

1.4.0 prototype int ast_monitor_start(struct ast_channel *chan,

const char *format_spec, const char *fname_base, int

need_lock );

1.6.0 prototype int ast_monitor_start(struct ast_channel *chan,

const char *format_spec, const char *fname_base, int

need_lock, int stream_action);

Changed

explanation

stream_action flag determines whether to record the

input and/or output streams

New types or

variables

none

1.4.0 example:

static int start_monitor_action(struct mansession *s, struct message

*m)

{

struct ast_channel *c = NULL;

char *name = astman_get_header(m, "Channel");

char *fname = astman_get_header(m, "File");

char *format = astman_get_header(m, "Format");

char *mix = astman_get_header(m, "Mix");

...--> if (ast_monitor_start(c, format, fname, 1))

...

1.6.0 example:

/* Streams recording control */

#define X_REC_IN 1

#define X_REC_OUT 2

static int start_monitor_action(struct mansession *s, const struct

message *m){

struct ast_channel *c = NULL;

const char *name = astman_get_header(m, "Channel");

const char *fname = astman_get_header(m, "File");

const char *format = astman_get_header(m, "Format");

56

8/8/2019 API 1.6.0 Changes

57/92

const char *mix = astman_get_header(m, "Mix");

...

c = ast_get_channel_by_name_locked(name);

...

--> if (ast_monitor_start(c, format, fname, 1, X_REC_IN | X_REC_OUT))

...

57

8/8/2019 API 1.6.0 Changes

58/92

Function ast_rtp_get_quality

Location /include/asterisk/rtp.h

1.4.0 prototype char *ast_rtp_get_quality(struct ast_rtp *rtp);

1.6.0 prototype char *ast_rtp_get_quality(struct ast_rtp *rtp,

struct ast_rtp_quality *qual);

Changed

explanation

qual parameter was added because users needed

individual RTP statistics, rather than having to

extract them from a string

New types or

variables

ast_rtp_quality see page 91

1.4.0 example:

static int handle_request_bye(struct sip_pvt *p, struct sip_request*req)

{

struct ast_channel *c=NULL;

int res;

struct ast_channel *bridged_to;

/* If we have an INCOMING invite that we haven't answered,

terminate that transaction */

if (p->pendinginvite && !ast_test_flag(&p->flags[0],

SIP_OUTGOING) && !ast_test_flag(req, SIP_PKT_IGNORE) && !p->owner)transmit_response_reliable(p, "487 Request Terminated", &p-

>initreq);

p->invitestate = INV_TERMINATED;

copy_request(&p->initreq, req);

check_via(p, req);

sip_alreadygone(p);

/* Get RTCP quality before end of call */if (!ast_test_flag(&p->flags[0], SIP_NO_HISTORY) || p->owner) {

char *audioqos, *videoqos;

if (p->rtp) {

--> audioqos = ast_rtp_get_quality(p->rtp);

...

58

8/8/2019 API 1.6.0 Changes

59/92

59

8/8/2019 API 1.6.0 Changes

60/92

(continued)

1.6.0 example:

static int acf_channel_read(struct ast_channel *chan, const char

*funcname, char *preparse, char *buf, size_t buflen)

{

struct sip_pvt *p = chan->tech_pvt;

char *all = "", *parse = ast_strdupa(preparse);

int res = 0;


AST_APP_ARG(param);

AST_APP_ARG(type);

AST_APP_ARG(field);

);

AST_STANDARD_APP_ARGS(args, parse);

/* Sanity check */

if (!IS_SIP_TECH(chan->tech)) {

ast_log(LOG_ERROR, "Cannot call %s on a non-SIP channel\n",

funcname);

return 0;

}

memset(buf, 0, buflen);

if (!strcasecmp(args.param, "rtpqos")) {

struct ast_rtp_quality qos;

memset(&qos, 0, sizeof(qos));

if (ast_strlen_zero(args.type))

args.type = "audio";

if (ast_strlen_zero(args.field))

args.field = "all";

if (strcasecmp(args.type, "AUDIO") == 0) {--> all = ast_rtp_get_quality(p->rtp, &qos);

}

...

60

8/8/2019 API 1.6.0 Changes

61/92

Function ast_rtp_settos

Location /include/asterisk/rtp.h

1.4.0 prototype int ast_rtp_settos(struct ast_rtp *rtp, int tos);

1.6.0 prototype int ast_rtp_setqos(struct ast_rtp *rtp, int tos, int

cos, char *desc);

Changed

explanation

cos parameter sets priority level, description

parameter describes what tos/cos settings apply to

New types or

variables

none

1.4.0 example:

if (sip_methods[intended_method].need_rtp) {

p->rtp = ast_rtp_new_with_bindaddr(sched, io, 1, 0,bindaddr.sin_addr);

...

ast_rtp_setdtmf(p->rtp, ast_test_flag(&p->flags[0], SIP_DTMF)

!= SIP_DTMF_INFO);

ast_rtp_setdtmfcompensate(p->rtp, ast_test_flag(&p->flags[1],

SIP_PAGE2_RFC2833_COMPENSATE));

--> ast_rtp_settos(p->rtp, global_tos_audio);

...

1.6.0 example:

if (sip_methods[intended_method].need_rtp) {

p->rtp = ast_rtp_new_with_bindaddr(sched, io, 1, 0,

bindaddr.sin_addr);

...

--> ast_rtp_setqos(p->rtp, global_tos_audio, global_cos_audio,

"SIP RTP");

ast_rtp_setdtmf(p->rtp, ast_test_flag(&p->flags[0], SIP_DTMF) ==

SIP_DTMF_RFC2833);

ast_rtp_setdtmfcompensate(p->rtp, ast_test_flag(&p->flags[1],SIP_PAGE2_RFC2833_COMPENSATE));

...

61

8/8/2019 API 1.6.0 Changes

62/92

Function ast_senddigit


1.4.0 prototype int ast_senddigit(struct ast_channel *chan, char

digit);

1.6.0 prototype int ast_senddigit(struct ast_channel *chan, char

digit, unsigned int duration);

Changed

explanation

duration parameter specifies length digit is played

as long as duration is longer than

AST_DEFAULT_EMULATE_DTMF_DURATION (100ms)

New types or

variables

none

1.4.0 example:

static int manager_play_dtmf(struct mansession *s, struct message *m)

{

char *channel = astman_get_header(m, "Channel");

char *digit = astman_get_header(m, "Digit");

struct ast_channel *chan =

ast_get_channel_by_name_locked(channel);

--> ast_senddigit(chan, *digit);

ast_mutex_unlock(&chan->lock);astman_send_ack(s, m, "DTMF successfully queued");

...

1.6.0 example:

static int manager_play_dtmf(struct mansession *s, const struct

message *m)

{

const char *channel = astman_get_header(m, "Channel");

const char *digit = astman_get_header(m, "Digit");struct ast_channel *chan =

ast_get_channel_by_name_locked(channel);

--> ast_senddigit(chan, *digit, 0);

62

8/8/2019 API 1.6.0 Changes

63/92

ast_channel_unlock(chan);

astman_send_ack(s, m, "DTMF successfully queued");

...

63

8/8/2019 API 1.6.0 Changes

64/92

Function ast_senddigit_end


1.4.0 prototype int ast_senddigit_end(struct ast_channel *chan, char

digit);

1.6.0 prototype int ast_senddigit_end(struct ast_channel *chan, char

digit, unsigned int duration);

Changed

explanation

duration parameter determ length sent if supported

(send_digit_end function pointer called)

New types or

variables

none

1.4.0 example:

static int agent_digit_end(struct ast_channel *ast, char digit){

struct agent_pvt *p = ast->tech_pvt;

int res = -1;

ast_mutex_lock(&p->lock);

--> ast_senddigit_end(p->chan, digit);

ast_mutex_unlock(&p->lock);

return res;

}

1.6.0 example:

static int agent_digit_end(struct ast_channel *ast, char digit,

unsigned int duration)

{

struct agent_pvt *p = ast->tech_pvt;

ast_mutex_lock(&p->lock);

if (p->chan) {

--> ast_senddigit_end(p->chan, digit, duration);

}

ast_mutex_unlock(&p->lock);return 0;

}

64

8/8/2019 API 1.6.0 Changes

65/92

8/8/2019 API 1.6.0 Changes

66/92

(continued)

1.6.0 example:

static int builtin_blindtransfer(struct ast_channel *chan, struct

ast_channel *peer, struct ast_bridge_config *config, char *code, int

sense, void *data)

{

struct ast_channel *transferer;

struct ast_channel *transferee;

const char *transferer_real_context;

char xferto[256];

int res;

set_peers(&transferer, &transferee, peer, chan, sense);

transferer_real_context = real_ctx(transferer, transferee);

/* Start autoservice on chan while we talk to the originator */

ast_autoservice_start(transferee);

ast_indicate(transferee, AST_CONTROL_HOLD);

memset(xferto, 0, sizeof(xferto));

/* Transfer */

--> res = ast_stream_and_wait(transferer, "pbx-transfer",

AST_DIGIT_ANY);

...

66

8/8/2019 API 1.6.0 Changes

67/92

Function

(all defines)

ast_string_field_count

ast_string_field_free

ast_string_field_free_pools

ast_string_field_free_all

ast_string_field_index

ast_string_field_index_free

Location /include/asterisk/stringfields.h

1.4.0 prototype ast_string_field_count(x)

ast_string_field_index(x, field)

ast_string_field_index_free(x, index)

ast_string_field_free(x, field)

ast_string_field_free_pools(x)

ast_string_field_free_all(x)

1.6.0 prototype ast_string_field_free_memory(x)

ast_string_field_set(x, field, data)Changed

explanation

All the old free functions were replaced by a new

single ast_string_field_free_memory function.

New types or

variables

none

1.4.0 example:

static void sip_registry_destroy(struct sip_registry *reg)

{...

--> ast_string_field_free_pools(reg);

regobjs--;

free(reg);

}

1.6.0 example:

static void sip_registry_destroy(struct sip_registry *reg)

{...

--> ast_string_field_free_memory(reg);

regobjs--;

ast_free(reg);

67

8/8/2019 API 1.6.0 Changes

68/92

}

Note: Previously, where string_field_free() was used to NULL out a

single string field, you now simply do string_field_set(obj, field,

NULL), instead.

68

8/8/2019 API 1.6.0 Changes

69/92

Function

(define)

AST_THREADSTORAGE


1.4.0 prototype AST_THREADSTORAGE(my_buf, my_buf_init);

1.6.0 prototype AST_THREADSTORAGE(my_buf);

Changed

explanation

The new define handles the initialization based on

the buffer name.

New types or

variables

none

1.4.0 example:

AST_THREADSTORAGE(ast_cli_buf, ast_cli_buf_init);

1.6.0 example:

AST_THREADSTORAGE(ast_cli_buf);

69

8/8/2019 API 1.6.0 Changes

70/92

Function ast_tzsetwall

Location was /include/asterisk/localtime.h

1.4.0 prototype int ast_tzsetwall(void)

1.6.0 prototype none

Changedexplanation

deemed completely unnecessary

New types or

variables

none


70

8/8/2019 API 1.6.0 Changes

71/92

Function ast_variable_delete


1.4.0 prototype int ast_variable_delete(struct ast_category

*category, char *variable, char *match);

1.6.0 prototype int ast_variable_delete(struct ast_category

*category, const char *variable, const char *match,

const char *line);

Changed

explanation

optional line number specified will specify exact

location in file which could potentially save time

searching

New types or

variables

none

1.4.0 example:

static void handle_updates(struct mansession *s, struct message *m,

struct ast_config *cfg)

{

int x;

char hdr[40];

char *action, *cat, *var, *value, *match;

struct ast_category *category;


for (x=0;x

8/8/2019 API 1.6.0 Changes

72/92

if (!strcasecmp(action, "delete")) {

if (!ast_strlen_zero(cat) && !ast_strlen_zero(var) &&

(category = ast_category_get(cfg, cat)))

--> ast_variable_delete(category, var, match);

72

8/8/2019 API 1.6.0 Changes

73/92

(continued)

1.6.0 example:

static enum error_type handle_updates(struct mansession *s, const

struct message *m, struct ast_config *cfg, const char *dfn)

{

int x;

char hdr[40];

const char *action, *cat, *var, *value, *match, *line;



for (x = 0; x < 100000; x++) {

unsigned int object = 0;

snprintf(hdr, sizeof(hdr), "Action-%06d", x);

action = astman_get_header(m, hdr);

if (ast_strlen_zero(action))

break;

snprintf(hdr, sizeof(hdr), "Cat-%06d", x);

cat = astman_get_header(m, hdr);

snprintf(hdr, sizeof(hdr), "Var-%06d", x);

var = astman_get_header(m, hdr);

snprintf(hdr, sizeof(hdr), "Value-%06d", x);

value = astman_get_header(m, hdr);

if (!ast_strlen_zero(value) && *value == '>') {

object = 1;

value++;

}

snprintf(hdr, sizeof(hdr), "Match-%06d", x);

match = astman_get_header(m, hdr);

snprintf(hdr, sizeof(hdr), "Line-%06d", x);

line = astman_get_header(m, hdr);

if (!strcasecmp(action, "delete")) {

if (ast_strlen_zero(cat) || (ast_strlen_zero(var) &&

ast_strlen_zero(line)))return UNSPECIFIED_ARGUMENT;

if (!(category = ast_category_get(cfg, cat)))

return UNKNOWN_CATEGORY;

--> if (ast_variable_delete(category, var, match, line))

return FAILURE_DELETE;

73

8/8/2019 API 1.6.0 Changes

74/92

}

74

8/8/2019 API 1.6.0 Changes

75/92

Function ast_variable_new


1.4.0 prototype struct ast_variable *ast_variable_new(const char

*name, const char *value);

1.6.0 prototype struct ast_variable *ast_variable_new(const char

*name, const char *value, const char *filename);

Changed

explanation

filename used for destination file during save

operation

New types or

variables

none

1.4.0 example:

static struct ast_variable *variable_clone(const struct ast_variable*old)

{

--> struct ast_variable *new = ast_variable_new(old->name, old-

>value);

if (new) {

new->lineno = old->lineno;

new->object = old->object;

new->blanklines = old->blanklines;

}

return new;

}

1.6.0 example:

static struct ast_variable *variable_clone(const struct ast_variable

*old)

{

--> struct ast_variable *new = ast_variable_new(old->name, old->value, old->file);

if (new) {

new->lineno = old->lineno;

new->object = old->object;

75

8/8/2019 API 1.6.0 Changes

76/92

new->blanklines = old->blanklines;

}

return new;

}

76

8/8/2019 API 1.6.0 Changes

77/92

Function ast_variable_update


1.4.0 prototype int ast_variable_update(struct ast_category

*category, char *variable, char *value, char

*match);

1.6.0 prototype int ast_variable_update(struct ast_category

*category, const char *variable, const char *value,

const char *match, unsigned int object);

Changed

explanation

object parameter added to differentiate both types

of config file assignment operators ( = and => )

New types or

variables

none

1.4.0 example:

static void handle_updates(struct mansession *s, struct message *m,

struct ast_config *cfg)

{

int x;

char hdr[40];

char *action, *cat, *var, *value, *match;



for (x=0;x

8/8/2019 API 1.6.0 Changes

78/92

(category = ast_category_get(cfg, cat)))

--> ast_variable_update(category, var, value, match);

78

8/8/2019 API 1.6.0 Changes

79/92

(continued)

1.6.0 example:

static enum error_type handle_updates(struct mansession *s, const

struct message *m, struct ast_config *cfg, const char *dfn)

{

int x;

char hdr[40];

const char *action, *cat, *var, *value, *match, *line;



for (x = 0; x < 100000; x++) {

unsigned int object = 0;

snprintf(hdr, sizeof(hdr), "Action-%06d", x);

action = astman_get_header(m, hdr);

if (ast_strlen_zero(action))

break;

snprintf(hdr, sizeof(hdr), "Cat-%06d", x);

cat = astman_get_header(m, hdr);

snprintf(hdr, sizeof(hdr), "Var-%06d", x);

var = astman_get_header(m, hdr);

snprintf(hdr, sizeof(hdr), "Value-%06d", x);

value = astman_get_header(m, hdr);

if (!ast_strlen_zero(value) && *value == '>') {

object = 1;

value++;

}

snprintf(hdr, sizeof(hdr), "Match-%06d", x);

match = astman_get_header(m, hdr);

snprintf(hdr, sizeof(hdr), "Line-%06d", x);

line = astman_get_header(m, hdr);

if (!strcasecmp(action, "update")) {

if (ast_strlen_zero(cat) || ast_strlen_zero(var))

return UNSPECIFIED_ARGUMENT;if (!(category = ast_category_get(cfg,cat)))

return UNKNOWN_CATEGORY;

--> if (ast_variable_update(category, var, value, match,

object))

return FAILURE_UPDATE;

79

8/8/2019 API 1.6.0 Changes

80/92

Function config_load_func


1.4.0 prototype typedef struct ast_config *config_load_func(const

char *database, const char *table, const char

*configfile, struct ast_config *config, int

withcomments);

1.6.0 prototype typedef struct ast_config *config_load_func(const

char *database, const char *table, const char

*configfile, struct ast_config *config, struct

ast_flags flags, const char *suggested_include_file,

const char *who_asked);

Changed

explanation

ast_flags parameter now handles comment flags,

suggested_include_file is used for keeping track of

destination file, and who_asked is used for config

file caching

New types or

variables

ast_flags see 90


80

8/8/2019 API 1.6.0 Changes

81/92

Function fsk_serie

Location /include/asterisk/fskmodem.h

1.4.0 prototype int fsk_serie(fsk_data *fskd, short *buffer, int

*len, int *outbyte);

1.6.0 prototype int fsk_serial(fsk_data *fskd, short *buffer, int

*len, int *outbyte);

Changed

explanation

translated to English

New types or

variables

none


81

8/8/2019 API 1.6.0 Changes

82/92

Function pbx_builtin_serialize_variables


1.4.0 prototype int pbx_builtin_serialize_variables(struct

ast_channel *chan, char *buf, size_t size);

1.6.0 prototype int pbx_builtin_serialize_variables(struct

ast_channel *chan, struct ast_str **buf);

Changed

explanation

ast_str is a better string data structure allowing

support for dynamic strings which uses less memory

New types or

variables

ast_str see page 91

/* both code examples assume 1 is a valid channel */

1.4.0 example:

char buf[2048];


--> if (pbx_builtin_serialize_variables(c,buf,sizeof(buf)))

ast_cli(fd," Variables:\n%s\n",buf);

1.6.0 example:

struct ast_str *out = ast_str_alloca(2048);struct ast_channel *c = ast_get_channel_by_name_locked(1);

--> if (pbx_builtin_serialize_variables(c, &out))

ast_cli(a->fd," Variables:\n%s\n", out->str);

82

8/8/2019 API 1.6.0 Changes

83/92

Modified data structures

Data structure struct agi_command


Changed Removed: *nextAdded: int dead, ast_module *mod, AST_LIST_ENTRY

list

Data structure struct aji_buddy


Changed Removed: AST_OBJCOMPONENTS

Added: AST_OBJCOMPONENTS_FULL, btype

Data structure struct aji_client


Changed Removed: context

Added: name_space

Data structure struct ast_call_feature

Location /include/asterisk/features.h

Changed Added void *data parameter to operation function

pointer.

Data structure struct ast_channel


Changed ast_mutex_t lock changed to lock_dont_use

Data structure struct ast_channel_tech


Changed duration parameter added to send_digit_end function

83

8/8/2019 API 1.6.0 Changes

84/92

pointer

84

8/8/2019 API 1.6.0 Changes

85/92

Data structure struct ast_cli_entry

Location /include/asterisk/cli.h

Changed handler and generator function pointers replaced by

a single new handler function pointer

Data structure struct ast_custom_function


Changed Modified read and write function pointers to have

second argument const.

acflist member changed to a AST_RW_LIST entry for

convenience.

Data structure struct ast_datastore


Changed Changed char *uid to const char *uid

Added: unsigned int inheritance

Data structure struct ast_dynamic_str


Changed Removed completely because of new string handling in

strings.h

Data structure struct ast_filestream

Location /include/asterisk/file.h

Changed Made opaque type

Data structure struct ast_format

Location /include/asterisk/file.h

Changed Made opaque type

85

8/8/2019 API 1.6.0 Changes

86/92

Data structure struct ast_format_list

Location /include/asterisk/frame.h

Changed Removed: visible

Added: samplespersecond

Data structure struct ast_frame

Location /include/asterisk/frame.h

Changed Removed: has_timing_info

Added: flags

Data structure struct ast_ha

Location /include/asterisk/acl.h

Changed Added all members to make public:

netaddr, netmask, sense, and *next

Data structure struct ast_http_uri


Changed Changed next entry to use AST_LIST_ENTRY macro and

renamed entry.

Added: static_content bitfield

Data structure struct ast_lastreloadtime

Location /include/asterisk/options.h

Changed changed type to struct timeval

Data structure struct manager_actionLocation /include/asterisk/manager.h

Changed

explanation

manager_action pointer renamed to list and changed

to use linkedlist macro.

86

8/8/2019 API 1.6.0 Changes

87/92

Data structure struct message

Location /include/asterisk/manager.h

Changed headers member is now a pointer to const strings

instead of allocating the entire string list inside

the struct.

Data structure struct ast_option_flags

Location /include/asterisk/options.h

Changed Removed: AST_OPT_FLAG_PRIORITY_JUMPING

Data

api 1.6.0 changes

Documents