Review Board 1.7.16


xmldoc: Add support for an <example> tag in the Asterisk XML documentation

Review Request #3807 - Created July 16, 2014 and submitted

Matt Jordan
trunk
Reviewers
asterisk-dev
Asterisk
This patch adds support for an <example /> tag in the XML documentation schema.

For CLI help, this doesn't change the formatting too much:
 - Preceeding white space is removed
 - Unlike with para elements, new lines are preserved

However, having an <example /> tag in the XML schema allows for the wiki documentation generation script to surround the documentation with {code} or {noformat} tags, generating much better content for the wiki - and allowing us to put dialplan examples (and other code snippets, if desired) into the documentation for an application/function/AMI command/etc.
Updated the JITTERBUFFER function. It now displays its dialplan examples in a single example block in the CLI help.

Changes between revision 1 and 2

1 2 3 4
1 2 3 4

  1. /trunk/funcs/func_jitterbuffer.c: Loading...
/trunk/funcs/func_jitterbuffer.c
Diff Revision 1 Diff Revision 2
1
/*
1
/*
2
 * Asterisk -- An open source telephony toolkit.
2
 * Asterisk -- An open source telephony toolkit.
3
 *
3
 *
4
 * Copyright (C) 2011, Digium, Inc.
4
 * Copyright (C) 2011, Digium, Inc.
5
 *
5
 *
6
 * David Vossel <dvossel@digium.com>
6
 * David Vossel <dvossel@digium.com>
7
 *
7
 *
8
 * See http://www.asterisk.org for more information about
8
 * See http://www.asterisk.org for more information about
9
 * the Asterisk project. Please do not directly contact
9
 * the Asterisk project. Please do not directly contact
10
 * any of the maintainers of this project for assistance;
10
 * any of the maintainers of this project for assistance;
11
 * the project provides a web site, mailing lists and IRC
11
 * the project provides a web site, mailing lists and IRC
12
 * channels for your use.
12
 * channels for your use.
13
 *
13
 *
14
 * This program is free software, distributed under the terms of
14
 * This program is free software, distributed under the terms of
15
 * the GNU General Public License Version 2. See the LICENSE file
15
 * the GNU General Public License Version 2. See the LICENSE file
16
 * at the top of the source tree.
16
 * at the top of the source tree.
17
 */
17
 */
18

    
   
18

   
19
/*! \file
19
/*! \file
20
 *
20
 *
21
 * \brief Put a jitterbuffer on the read side of a channel
21
 * \brief Put a jitterbuffer on the read side of a channel
22
 *
22
 *
23
 * \author David Vossel <dvossel@digium.com>
23
 * \author David Vossel <dvossel@digium.com>
24
 *
24
 *
25
 * \ingroup functions
25
 * \ingroup functions
26
 */
26
 */
27

    
   
27

   
28
/*** MODULEINFO
28
/*** MODULEINFO
29
	<support_level>core</support_level>
29
	<support_level>core</support_level>
30
 ***/
30
 ***/
31

    
   
31

   
32
#include "asterisk.h"
32
#include "asterisk.h"
33

    
   
33

   
34
ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
34
ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
35

    
   
35

   
36
#include "asterisk/module.h"
36
#include "asterisk/module.h"
37
#include "asterisk/channel.h"
37
#include "asterisk/channel.h"
38
#include "asterisk/framehook.h"
38
#include "asterisk/framehook.h"
39
#include "asterisk/frame.h"
39
#include "asterisk/frame.h"
40
#include "asterisk/pbx.h"
40
#include "asterisk/pbx.h"
41
#include "asterisk/abstract_jb.h"
41
#include "asterisk/abstract_jb.h"
42
#include "asterisk/timing.h"
42
#include "asterisk/timing.h"
43
#include "asterisk/app.h"
43
#include "asterisk/app.h"
44

    
   
44

   
45
/*** DOCUMENTATION
45
/*** DOCUMENTATION
46
	<function name="JITTERBUFFER" language="en_US">
46
	<function name="JITTERBUFFER" language="en_US">
47
		<synopsis>
47
		<synopsis>
48
			Add a Jitterbuffer to the Read side of the channel.  This dejitters the audio stream before it reaches the Asterisk core. This is a write only function.
48
			Add a Jitterbuffer to the Read side of the channel.  This dejitters the audio stream before it reaches the Asterisk core. This is a write only function.
49
		</synopsis>
49
		</synopsis>
50
		<syntax>
50
		<syntax>
51
			<parameter name="jitterbuffer type" required="true">
51
			<parameter name="jitterbuffer type" required="true">
52
				<para>Jitterbuffer type can be <literal>fixed</literal>, <literal>adaptive</literal>, or
52
				<para>Jitterbuffer type can be <literal>fixed</literal>, <literal>adaptive</literal>, or
53
					<literal>disabled</literal>.</para>
53
					<literal>disabled</literal>.</para>
54
				<para>Used as follows. </para>
54
				<para>Used as follows. </para>
55
				<para>Set(JITTERBUFFER(type)=max_size[,resync_threshold[,target_extra]])</para>
55
				<para>Set(JITTERBUFFER(type)=max_size[,resync_threshold[,target_extra]])</para>
56
				<para>Set(JITTERBUFFER(type)=default) </para>
56
				<para>Set(JITTERBUFFER(type)=default) </para>
57
			</parameter>
57
			</parameter>
58
		</syntax>
58
		</syntax>
59
		<description>
59
		<description>
60
			<para>max_size: Defaults to 200 ms</para>
60
			<para>max_size: Defaults to 200 ms</para>
61
			<para>Length in milliseconds of buffer.</para>
61
			<para>Length in milliseconds of buffer.</para>
62
			<para> </para>
62
			<para> </para>
63
			<para>resync_threshold: Defaults to 1000ms </para>
63
			<para>resync_threshold: Defaults to 1000ms </para>
64
			<para>The length in milliseconds over which a timestamp difference will result in resyncing the jitterbuffer. </para>
64
			<para>The length in milliseconds over which a timestamp difference will result in resyncing the jitterbuffer. </para>
65
			<para> </para>
65
			<para> </para>
66
			<para>target_extra: Defaults to 40ms</para>
66
			<para>target_extra: Defaults to 40ms</para>
67
			<para>This option only affects the adaptive jitterbuffer. It represents the amount time in milliseconds by which the new jitter buffer will pad its size.</para>
67
			<para>This option only affects the adaptive jitterbuffer. It represents the amount time in milliseconds by which the new jitter buffer will pad its size.</para>
68
			<para> </para>
68
			<para> </para>
69
			<example title="Dialplan examples" language="text">
69
			<example title="Fixed with defaults" language="text">
70
			exten => 1,1,Set(JITTERBUFFER(fixed)=default);Fixed with defaults.
70
			exten => 1,1,Set(JITTERBUFFER(fixed)=default)
71
			exten => 1,1,Set(JITTERBUFFER(fixed)=200);Fixed with max size 200ms, default resync threshold and target extra.
71
			</example>
72
			exten => 1,1,Set(JITTERBUFFER(fixed)=200,1500);Fixed with max size 200ms resync threshold 1500.
72
			<example title="Fixed with 200ms max size" language="text">
73
			exten => 1,1,Set(JITTERBUFFER(adaptive)=default);Adaptive with defaults.
73
			exten => 1,1,Set(JITTERBUFFER(fixed)=200)
74
			exten => 1,1,Set(JITTERBUFFER(adaptive)=200,,60);Adaptive with max size 200ms, default resync threshold and 40ms target extra.
74
			</example>
75
			exten => 1,n,Set(JITTERBUFFER(disabled)=);Remove previously applied jitterbuffer
75
			<example title="Fixed with 200ms max size, resync threshold 1500" language="text">

    
   
76
			exten => 1,1,Set(JITTERBUFFER(fixed)=200,1500)

    
   
77
			</example>

    
   
78
			<example title="Adaptive with defaults" language="text">

    
   
79
			exten => 1,1,Set(JITTERBUFFER(adaptive)=default)

    
   
80
			</example>

    
   
81
			<example title="Adaptive with 200ms max size, 60ms target extra" language="text">

    
   
82
			exten => 1,1,Set(JITTERBUFFER(adaptive)=200,,60)

    
   
83
			</example>

    
   
84
			<example title="Set a fixed jitterbuffer with defaults; then remove it" language="text">

    
   
85
			exten => 1,1,Set(JITTERBUFFER(fixed)=default)

    
   
86
			exten => 1,n,Set(JITTERBUFFER(disabled)=)
76
			</example>
87
			</example>
77
			<note><para>If a channel specifies a jitterbuffer due to channel driver configuration and
88
			<note><para>If a channel specifies a jitterbuffer due to channel driver configuration and
78
			the JITTERBUFFER function has set a jitterbuffer for that channel, the jitterbuffer set by
89
			the JITTERBUFFER function has set a jitterbuffer for that channel, the jitterbuffer set by
79
			the JITTERBUFFER function will take priority and the jitterbuffer set by the channel
90
			the JITTERBUFFER function will take priority and the jitterbuffer set by the channel
80
			configuration will not be applied.</para></note>
91
			configuration will not be applied.</para></note>
81
		</description>
92
		</description>
82
	</function>
93
	</function>
83
 ***/
94
 ***/
84

    
   
95

   
85
static int jb_helper(struct ast_channel *chan, const char *cmd, char *data, const char *value)
96
static int jb_helper(struct ast_channel *chan, const char *cmd, char *data, const char *value)
86
{
97
{
87
	struct ast_jb_conf jb_conf;
98
	struct ast_jb_conf jb_conf;
88

    
   
99

   
89
	if (!chan) {
100
	if (!chan) {
90
		ast_log(LOG_WARNING, "No channel was provided to %s function.\n", cmd);
101
		ast_log(LOG_WARNING, "No channel was provided to %s function.\n", cmd);
91
		return -1;
102
		return -1;
92
	}
103
	}
93

    
   
104

   
94
	/* Initialize and set jb_conf */
105
	/* Initialize and set jb_conf */
95
	ast_jb_conf_default(&jb_conf);
106
	ast_jb_conf_default(&jb_conf);
96

    
   
107

   
97
	/* Now check user options to see if any of the defaults need to change. */
108
	/* Now check user options to see if any of the defaults need to change. */
98
	if (!ast_strlen_zero(data)) {
109
	if (!ast_strlen_zero(data)) {
99
		if (strcasecmp(data, "fixed") &&
110
		if (strcasecmp(data, "fixed") &&
100
				strcasecmp(data, "adaptive") &&
111
				strcasecmp(data, "adaptive") &&
101
				strcasecmp(data, "disabled")) {
112
				strcasecmp(data, "disabled")) {
102
			ast_log(LOG_WARNING, "Unknown Jitterbuffer type %s. Failed to create jitterbuffer.\n", data);
113
			ast_log(LOG_WARNING, "Unknown Jitterbuffer type %s. Failed to create jitterbuffer.\n", data);
103
			return -1;
114
			return -1;
104
		}
115
		}
105
		ast_copy_string(jb_conf.impl, data, sizeof(jb_conf.impl));
116
		ast_copy_string(jb_conf.impl, data, sizeof(jb_conf.impl));
106
	}
117
	}
107

    
   
118

   
108
	if (!ast_strlen_zero(value) && strcasecmp(value, "default")) {
119
	if (!ast_strlen_zero(value) && strcasecmp(value, "default")) {
109
		char *parse = ast_strdupa(value);
120
		char *parse = ast_strdupa(value);
110
		int res = 0;
121
		int res = 0;
111
		AST_DECLARE_APP_ARGS(args,
122
		AST_DECLARE_APP_ARGS(args,
112
			AST_APP_ARG(max_size);
123
			AST_APP_ARG(max_size);
113
			AST_APP_ARG(resync_threshold);
124
			AST_APP_ARG(resync_threshold);
114
			AST_APP_ARG(target_extra);
125
			AST_APP_ARG(target_extra);
115
		);
126
		);
116

    
   
127

   
117
		AST_STANDARD_APP_ARGS(args, parse);
128
		AST_STANDARD_APP_ARGS(args, parse);
118
		if (!ast_strlen_zero(args.max_size)) {
129
		if (!ast_strlen_zero(args.max_size)) {
119
			res |= ast_jb_read_conf(&jb_conf,
130
			res |= ast_jb_read_conf(&jb_conf,
120
				"jbmaxsize",
131
				"jbmaxsize",
121
				args.max_size);
132
				args.max_size);
122
		}
133
		}
123
		if (!ast_strlen_zero(args.resync_threshold)) {
134
		if (!ast_strlen_zero(args.resync_threshold)) {
124
			res |= ast_jb_read_conf(&jb_conf,
135
			res |= ast_jb_read_conf(&jb_conf,
125
				"jbresyncthreshold",
136
				"jbresyncthreshold",
126
				args.resync_threshold);
137
				args.resync_threshold);
127
		}
138
		}
128
		if (!ast_strlen_zero(args.target_extra)) {
139
		if (!ast_strlen_zero(args.target_extra)) {
129
			res |= ast_jb_read_conf(&jb_conf,
140
			res |= ast_jb_read_conf(&jb_conf,
130
				"jbtargetextra",
141
				"jbtargetextra",
131
				args.target_extra);
142
				args.target_extra);
132
		}
143
		}
133
		if (res) {
144
		if (res) {
134
			ast_log(LOG_WARNING, "Invalid jitterbuffer parameters %s\n", value);
145
			ast_log(LOG_WARNING, "Invalid jitterbuffer parameters %s\n", value);
135
		}
146
		}
136
	}
147
	}
137

    
   
148

   
138
	ast_jb_create_framehook(chan, &jb_conf, 0);
149
	ast_jb_create_framehook(chan, &jb_conf, 0);
139

    
   
150

   
140
	return 0;
151
	return 0;
141
}
152
}
142

    
   
153

   
143

    
   
154

   
144
static struct ast_custom_function jb_function = {
155
static struct ast_custom_function jb_function = {
145
	.name = "JITTERBUFFER",
156
	.name = "JITTERBUFFER",
146
	.write = jb_helper,
157
	.write = jb_helper,
147
};
158
};
148

    
   
159

   
149
static int unload_module(void)
160
static int unload_module(void)
150
{
161
{
151
	return ast_custom_function_unregister(&jb_function);
162
	return ast_custom_function_unregister(&jb_function);
152
}
163
}
153

    
   
164

   
154
static int load_module(void)
165
static int load_module(void)
155
{
166
{
156
	int res = ast_custom_function_register(&jb_function);
167
	int res = ast_custom_function_register(&jb_function);
157
	return res ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS;
168
	return res ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS;
158
}
169
}
159

    
   
170

   
160
AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Jitter buffer for read side of channel.");
171
AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Jitter buffer for read side of channel.");
161

    
   
172

   
  1. /trunk/funcs/func_jitterbuffer.c: Loading...

https://reviewboard.asterisk.org/ runs on a server provided by Digium, Inc. and uses bandwidth donated to the open source Asterisk community by API Digital Communications in Huntsville, AL USA.
Please report problems with this site to asteriskteam@digium.com.