Doxygen documentation update from oej (issue #5505)
[asterisk/asterisk.git] / funcs / func_strings.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2005, Digium, Inc.
5  * Portions Copyright (C) 2005, Tilghman Lesher.  All rights reserved.
6  * Portions Copyright (C) 2005, Anthony Minessale II
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  *
21  * \brief String manipulation dialplan functions
22  * 
23  */
24
25 #include <stdlib.h>
26 #include <string.h>
27 #include <sys/types.h>
28 #include <regex.h>
29
30 #include "asterisk.h"
31
32 /* ASTERISK_FILE_VERSION(__FILE__, "$Revision$") */
33
34 #include "asterisk/channel.h"
35 #include "asterisk/pbx.h"
36 #include "asterisk/logger.h"
37 #include "asterisk/utils.h"
38 #include "asterisk/app.h"
39 #include "asterisk/localtime.h"
40
41 static char *function_fieldqty(struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len)
42 {
43         char *varname, *varval, workspace[256];
44         char *delim = ast_strdupa(data);
45         int fieldcount = 0;
46
47         if (delim) {
48                 varname = strsep(&delim, "|");
49                 pbx_retrieve_variable(chan, varname, &varval, workspace, sizeof(workspace), NULL);
50                 while (strsep(&varval, delim))
51                         fieldcount++;
52                 snprintf(buf, len, "%d", fieldcount);
53         } else {
54                 ast_log(LOG_ERROR, "Out of memory\n");
55                 strncpy(buf, "1", len);
56         }
57         return buf;
58 }
59
60 #ifndef BUILTIN_FUNC
61 static
62 #endif
63 struct ast_custom_function fieldqty_function = {
64         .name = "FIELDQTY",
65         .synopsis = "Count the fields, with an arbitrary delimiter",
66         .syntax = "FIELDQTY(<varname>,<delim>)",
67         .read = function_fieldqty,
68 };
69
70 static char *builtin_function_regex(struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len) 
71 {
72         char *arg, *earg = NULL, *tmp, errstr[256] = "";
73         int errcode;
74         regex_t regexbuf;
75
76         ast_copy_string(buf, "0", len);
77         
78         tmp = ast_strdupa(data);
79         if (!tmp) {
80                 ast_log(LOG_ERROR, "Out of memory in %s(%s)\n", cmd, data);
81                 return buf;
82         }
83
84         /* Regex in quotes */
85         arg = strchr(tmp, '"');
86         if (arg) {
87                 arg++;
88                 earg = strrchr(arg, '"');
89                 if (earg) {
90                         *earg++ = '\0';
91                         /* Skip over any spaces before the data we are checking */
92                         while (*earg == ' ')
93                                 earg++;
94                 }
95         } else {
96                 arg = tmp;
97         }
98
99         if ((errcode = regcomp(&regexbuf, arg, REG_EXTENDED | REG_NOSUB))) {
100                 regerror(errcode, &regexbuf, errstr, sizeof(errstr));
101                 ast_log(LOG_WARNING, "Malformed input %s(%s): %s\n", cmd, data, errstr);
102         } else {
103                 if (!regexec(&regexbuf, earg ? earg : "", 0, NULL, 0))
104                         ast_copy_string(buf, "1", len); 
105         }
106         regfree(&regexbuf);
107
108         return buf;
109 }
110
111 #ifndef BUILTIN_FUNC
112 static
113 #endif
114 struct ast_custom_function regex_function = {
115         .name = "REGEX",
116         .synopsis = "Regular Expression: Returns 1 if data matches regular expression.",
117         .syntax = "REGEX(\"<regular expression>\" <data>)",
118         .read = builtin_function_regex,
119 };
120
121 static char *builtin_function_len(struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len) 
122 {
123         int length = 0;
124         if (data) {
125                 length = strlen(data);
126         }
127         snprintf(buf, len, "%d", length);
128         return buf;
129 }
130
131 #ifndef BUILTIN_FUNC
132 static
133 #endif
134 struct ast_custom_function len_function = {
135         .name = "LEN",
136         .synopsis = "Returns the length of the argument given",
137         .syntax = "LEN(<string>)",
138         .read = builtin_function_len,
139 };
140
141 static char *acf_strftime(struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len) 
142 {
143         char *format, *epoch, *timezone = NULL;
144         long epochi;
145         struct tm time;
146
147         buf[0] = '\0';
148
149         if (!data) {
150                 ast_log(LOG_ERROR, "Asterisk function STRFTIME() requires an argument.\n");
151                 return buf;
152         }
153         
154         format = ast_strdupa(data);
155         if (!format) {
156                 ast_log(LOG_ERROR, "Out of memory\n");
157                 return buf;
158         }
159         
160         epoch = strsep(&format, "|");
161         timezone = strsep(&format, "|");
162
163         if (!epoch || ast_strlen_zero(epoch) || !sscanf(epoch, "%ld", &epochi)) {
164                 struct timeval tv = ast_tvnow();
165                 epochi = tv.tv_sec;
166         }
167
168         ast_localtime(&epochi, &time, timezone);
169
170         if (!format) {
171                 format = "%c";
172         }
173
174         if (!strftime(buf, len, format, &time)) {
175                 ast_log(LOG_WARNING, "C function strftime() output nothing?!!\n");
176         }
177         buf[len - 1] = '\0';
178
179         return buf;
180 }
181
182 #ifndef BUILTIN_FUNC
183 static
184 #endif
185 struct ast_custom_function strftime_function = {
186         .name = "STRFTIME",
187         .synopsis = "Returns the current date/time in a specified format.",
188         .syntax = "STRFTIME([<epoch>][,[timezone][,format]])",
189         .read = acf_strftime,
190 };
191
192 static char *function_eval(struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len) 
193 {
194         memset(buf, 0, len);
195
196         if (!data || ast_strlen_zero(data)) {
197                 ast_log(LOG_WARNING, "EVAL requires an argument: EVAL(<string>)\n");
198                 return buf;
199         }
200
201         pbx_substitute_variables_helper(chan, data, buf, len - 1);
202
203         return buf;
204 }
205
206 #ifndef BUILTIN_FUNC
207 static
208 #endif
209 struct ast_custom_function eval_function = {
210         .name = "EVAL",
211         .synopsis = "Evaluate stored variables.",
212         .syntax = "EVAL(<variable>)",
213         .desc = "Using EVAL basically causes a string to be evaluated twice.\n"
214                 "When a variable or expression is in the dialplan, it will be\n"
215                 "evaluated at runtime. However, if the result of the evaluation\n"
216                 "is in fact a variable or expression, using EVAL will have it\n"
217                 "evaluated a second time. For example, if the variable ${MYVAR}\n"
218                 "contains \"${OTHERVAR}\", then the result of putting ${EVAL(${MYVAR})}\n"
219                 "in the dialplan will be the contents of the variable, OTHERVAR.\n"
220                 "Normally, by just putting ${MYVAR} in the dialplan, you would be\n"
221                 "left with \"${OTHERVAR}\".\n", 
222         .read = function_eval,
223 };
224