/src/opensips/mi/item.h

Source (jump to first uncovered line)
/*
 * Copyright (C) 2006 Voice Sistem SRL
 * Copyright (C) 2018 OpenSIPS Solutions
 *
 * This file is part of opensips, a free SIP server.
 *
 * opensips is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * opensips is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 *
 */


#ifndef _MI_ITEM_H
#define _MI_ITEM_H

#include <stdarg.h>
#include "../str.h"
#include "../lib/cJSON.h"

#define MI_DATE_BUF_LEN 21

#define MI_SSTR(_s) _s,(sizeof(_s)-1)

#define JSONRPC_S "jsonrpc"
#define JSONRPC_VERS_S "2.0"

#define JSONRPC_RESULT_S "result"

#define JSONRPC_ERROR_S "error"
#define JSONRPC_ERR_CODE_S "code"
#define JSONRPC_ERR_MSG_S "message"
#define JSONRPC_ERR_DATA_S "data"

#define MI_OK_S "OK"

#define MI_ITEM_IS_ARRAY(item) ((item)->type & cJSON_Array)

typedef cJSON mi_item_t;

typedef mi_item_t mi_response_t;
typedef flush_fn mi_flush_f;

typedef struct mi_params_ {
  mi_item_t *item;
  char * const *list;
} mi_params_t;

/* The functions below can be used to build a MI Response
 */

/* Initializes a successful MI Response
 * with an empty array returned in the @arr_out parameter.
 */
mi_response_t *init_mi_result_array(mi_item_t **arr_out);

/* Initializes a successful MI Response
 * with an empty object returned in the @obj_out parameter.
 */
mi_response_t *init_mi_result_object(mi_item_t **obj_out);

/* Initializes a successful MI Response
 * with the provided string.
 */
mi_response_t *init_mi_result_string(const char *value, int value_len);

/* Initializes a successful MI Response
 * with the "OK" string.
 */
#define init_mi_result_ok() init_mi_result_string(MI_SSTR(MI_OK_S))

/* Initializes a successful MI Response
 * with the provided double (as a 'number' json type).
 */
mi_response_t *init_mi_result_number(double value);

/* Initializes a successful MI Response
 * with the provided boolean value.
 */
mi_response_t *init_mi_result_bool(int b);

/* Initializes a successful MI Response
 * with null.
 */
mi_response_t *init_mi_result_null(void);

/* Initializes an error MI Response
 * with the given error code and message.
 * Accepts a string of additional error details.
 */
mi_response_t *init_mi_error_extra(int code, const char *msg, int msg_len,
                const char *details, int details_len);

/* Initializes an error MI Response
 * with the given error code and message.
 */
static inline mi_response_t *init_mi_error(int code, const char *msg, int msg_len)
{
  return init_mi_error_extra(code, msg, msg_len, NULL, 0);
}

/* Frees a MI Reponse
 */
void free_mi_response(mi_response_t *response);

/* Appends a new array to an existing array or to an object at the given name.
 * When appending to an array, @name and @name_len are ignored.
 */
mi_item_t *add_mi_array(mi_item_t *to, char *name, int name_len);

/* Appends a new object to an array or to another object at the given name.
 * When appending to an array, @name and @name_len are ignored.
 */
mi_item_t *add_mi_object(mi_item_t *to, char *name, int name_len);

/* Appends a string to an array or to an object at the given name.
 * When appending to an array, @name and @name_len are ignored.
 */
int add_mi_string(mi_item_t *to, char *name, int name_len,
          const char *value, int value_len);

/* Appends a formated string to an array or to an object at the given name.
 * When appending to an array, @name and @name_len are ignored.
 */
int add_mi_string_fmt(mi_item_t *to, char *name, int name_len,
            char *fmt_val, ...);

/* Appends a double (as a 'number' json type) to an array or to an object at
 * the given name. When appending to an array, @name and @name_len are ignored.
 */
int add_mi_number(mi_item_t *to, char *name, int name_len, double value);

/* Appends a boolean to an array or to an object at the given name.
 * When appending to an array, @name and @name_len are ignored.
 */
int add_mi_bool(mi_item_t *to, char *name, int name_len, int b);

/* Appends null to an array or to an object at the given name.
 * When appending to an array, @name and @name_len are ignored.
 */
int add_mi_null(mi_item_t *to, char *name, int name_len);


/* Clones a MI Response to shm memory
 */
mi_response_t *shm_clone_mi_response(mi_response_t *src);

/* Frees a MI Reponse from shm memory
 */
void free_shm_mi_response(mi_response_t *response);

/* Clones a MI item to shm memory
 */
mi_item_t *shm_clone_mi_item(mi_item_t *src);

/* Frees a MI item from shm memory
 */
void free_shm_mi_item(mi_item_t *response);

/* The string provided in @value will be freed along with the MI request
 * so it should be strdup'ed as necessary
 */
int get_mi_string_param(const mi_params_t *params, char *name,
          char **value, int *value_len);

int get_mi_bool_like_param(const mi_params_t *params, char *name,
          int default_value);

int get_mi_int_param(const mi_params_t *params, char *name, int *value);

int get_mi_array_param(const mi_params_t *params, char *name,
          mi_item_t **value, int *no_items);

/* get the string item at the index @pos from an array parameter
 * returned by get_mi_array_param()
 */
int get_mi_arr_param_string(const mi_item_t *array, int pos,
            char **value, int *value_len);

/* get the string item at the index @pos from an array parameter
 * returned by get_mi_array_param()
 */
int get_mi_arr_param_int(const mi_item_t *array, int pos, int *value);

/* set of functions for trying to get a parameter, but do not fail if
 * it cannot be found
 */
int try_get_mi_int_param(const mi_params_t *params, char *name,
    int *value);
int try_get_mi_string_param(const mi_params_t *params, char *name,
    char **value, int *value_len);
int try_get_mi_array_param(const mi_params_t *params, char *name,
    mi_item_t **value, int *no_items);
int try_get_mi_arr_param_string(const mi_item_t *array, int pos,
    char **value, int *value_len);
int try_get_mi_arr_param_int(const mi_item_t *array, int pos, int *value);
int try_get_mi_arr_param_object(const mi_item_t *array, int pos,
    mi_item_t **obj);
int get_mi_arr_param_object(const mi_item_t *array, int pos,
    mi_item_t **obj);

/* Initializes a standard MI Response with details about the last
 * parameter error produced by a parameter getter function
 */
mi_response_t *init_mi_param_error(void);

#endif

Coverage Report

Created: 2025-07-11 06:28

Line	Count	Source (jump to first uncovered line)
1		/*
2		* Copyright (C) 2006 Voice Sistem SRL
3		* Copyright (C) 2018 OpenSIPS Solutions
4		*
5		* This file is part of opensips, a free SIP server.
6		*
7		* opensips is free software; you can redistribute it and/or modify
8		* it under the terms of the GNU General Public License as published by
9		* the Free Software Foundation; either version 2 of the License, or
10		* (at your option) any later version.
11		*
12		* opensips is distributed in the hope that it will be useful,
13		* but WITHOUT ANY WARRANTY; without even the implied warranty of
14		* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15		* GNU General Public License for more details.
16		*
17		* You should have received a copy of the GNU General Public License
18		* along with this program; if not, write to the Free Software
19		* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
20		*
21		*/
22
23
24		#ifndef _MI_ITEM_H
25		#define _MI_ITEM_H
26
27		#include <stdarg.h>
28		#include "../str.h"
29		#include "../lib/cJSON.h"
30
31	0	#define MI_DATE_BUF_LEN 21
32
33	0	#define MI_SSTR(_s) _s,(sizeof(_s)-1)
34
35	0	#define JSONRPC_S "jsonrpc"
36	0	#define JSONRPC_VERS_S "2.0"
37
38	0	#define JSONRPC_RESULT_S "result"
39
40	0	#define JSONRPC_ERROR_S "error"
41	0	#define JSONRPC_ERR_CODE_S "code"
42	0	#define JSONRPC_ERR_MSG_S "message"
43	0	#define JSONRPC_ERR_DATA_S "data"
44
45		#define MI_OK_S "OK"
46
47	0	#define MI_ITEM_IS_ARRAY(item) ((item)->type & cJSON_Array)
48
49		typedef cJSON mi_item_t;
50
51		typedef mi_item_t mi_response_t;
52		typedef flush_fn mi_flush_f;
53
54		typedef struct mi_params_ {
55		mi_item_t *item;
56		char * const *list;
57		} mi_params_t;
58
59		/* The functions below can be used to build a MI Response
60		*/
61
62		/* Initializes a successful MI Response
63		* with an empty array returned in the @arr_out parameter.
64		*/
65		mi_response_t init_mi_result_array(mi_item_t *arr_out);
66
67		/* Initializes a successful MI Response
68		* with an empty object returned in the @obj_out parameter.
69		*/
70		mi_response_t init_mi_result_object(mi_item_t *obj_out);
71
72		/* Initializes a successful MI Response
73		* with the provided string.
74		*/
75		mi_response_t init_mi_result_string(const char value, int value_len);
76
77		/* Initializes a successful MI Response
78		* with the "OK" string.
79		*/
80	0	#define init_mi_result_ok() init_mi_result_string(MI_SSTR(MI_OK_S))
81
82		/* Initializes a successful MI Response
83		* with the provided double (as a 'number' json type).
84		*/
85		mi_response_t *init_mi_result_number(double value);
86
87		/* Initializes a successful MI Response
88		* with the provided boolean value.
89		*/
90		mi_response_t *init_mi_result_bool(int b);
91
92		/* Initializes a successful MI Response
93		* with null.
94		*/
95		mi_response_t *init_mi_result_null(void);
96
97		/* Initializes an error MI Response
98		* with the given error code and message.
99		* Accepts a string of additional error details.
100		*/
101		mi_response_t init_mi_error_extra(int code, const char msg, int msg_len,
102		const char *details, int details_len);
103
104		/* Initializes an error MI Response
105		* with the given error code and message.
106		*/
107		static inline mi_response_t init_mi_error(int code, const char msg, int msg_len)
108	0	{
109	0	return init_mi_error_extra(code, msg, msg_len, NULL, 0);
110	0	} Unexecuted instantiation: fuzz_msg_parser.c:init_mi_error Unexecuted instantiation: msg_parser.c:init_mi_error Unexecuted instantiation: parse_uri.c:init_mi_error Unexecuted instantiation: parse_fline.c:init_mi_error Unexecuted instantiation: parse_hname2.c:init_mi_error Unexecuted instantiation: parse_content.c:init_mi_error Unexecuted instantiation: hf.c:init_mi_error Unexecuted instantiation: parse_to.c:init_mi_error Unexecuted instantiation: parse_via.c:init_mi_error Unexecuted instantiation: dprint.c:init_mi_error Unexecuted instantiation: pt.c:init_mi_error Unexecuted instantiation: strcommon.c:init_mi_error Unexecuted instantiation: ut.c:init_mi_error Unexecuted instantiation: sdp_ops.c:init_mi_error Unexecuted instantiation: statistics.c:init_mi_error Unexecuted instantiation: pvar.c:init_mi_error Unexecuted instantiation: route.c:init_mi_error Unexecuted instantiation: socket_info.c:init_mi_error Unexecuted instantiation: ipc.c:init_mi_error Unexecuted instantiation: core_stats.c:init_mi_error Unexecuted instantiation: route_struct.c:init_mi_error Unexecuted instantiation: dset.c:init_mi_error Unexecuted instantiation: pt_scaling.c:init_mi_error Unexecuted instantiation: pt_load.c:init_mi_error Unexecuted instantiation: sr_module.c:init_mi_error Unexecuted instantiation: action.c:init_mi_error Unexecuted instantiation: flags.c:init_mi_error Unexecuted instantiation: db_insertq.c:init_mi_error Unexecuted instantiation: db.c:init_mi_error Unexecuted instantiation: proto_tcp.c:init_mi_error Unexecuted instantiation: proto_udp.c:init_mi_error Unexecuted instantiation: trans.c:init_mi_error Unexecuted instantiation: net_tcp_proc.c:init_mi_error Unexecuted instantiation: net_tcp.c:init_mi_error Unexecuted instantiation: tcp_common.c:init_mi_error Unexecuted instantiation: net_udp.c:init_mi_error Unexecuted instantiation: tcp_conn_profile.c:init_mi_error Unexecuted instantiation: trans_trace.c:init_mi_error Unexecuted instantiation: net_tcp_report.c:init_mi_error Unexecuted instantiation: shm_mem.c:init_mi_error Unexecuted instantiation: rpm_mem.c:init_mi_error Unexecuted instantiation: mem.c:init_mi_error Unexecuted instantiation: mi.c:init_mi_error Unexecuted instantiation: item.c:init_mi_error Unexecuted instantiation: sdp.c:init_mi_error Unexecuted instantiation: sdp_helpr_funcs.c:init_mi_error Unexecuted instantiation: digest_parser.c:init_mi_error Unexecuted instantiation: param_parser.c:init_mi_error Unexecuted instantiation: parse_contact.c:init_mi_error Unexecuted instantiation: parse_body.c:init_mi_error Unexecuted instantiation: parse_security.c:init_mi_error Unexecuted instantiation: parse_call_info.c:init_mi_error Unexecuted instantiation: parse_event.c:init_mi_error Unexecuted instantiation: parse_disposition.c:init_mi_error Unexecuted instantiation: parse_authenticate.c:init_mi_error Unexecuted instantiation: parser_f.c:init_mi_error Unexecuted instantiation: parse_rpid.c:init_mi_error Unexecuted instantiation: parse_ppi.c:init_mi_error Unexecuted instantiation: parse_fcaps.c:init_mi_error Unexecuted instantiation: parse_rr.c:init_mi_error Unexecuted instantiation: parse_param.c:init_mi_error Unexecuted instantiation: parse_diversion.c:init_mi_error Unexecuted instantiation: parse_nameaddr.c:init_mi_error Unexecuted instantiation: parse_expires.c:init_mi_error Unexecuted instantiation: parse_refer_to.c:init_mi_error Unexecuted instantiation: parse_from.c:init_mi_error Unexecuted instantiation: parse_pai.c:init_mi_error Unexecuted instantiation: event_interface.c:init_mi_error Unexecuted instantiation: evi_params.c:init_mi_error Unexecuted instantiation: receive.c:init_mi_error Unexecuted instantiation: ip_addr.c:init_mi_error Unexecuted instantiation: async.c:init_mi_error Unexecuted instantiation: daemonize.c:init_mi_error Unexecuted instantiation: timer.c:init_mi_error Unexecuted instantiation: trace_api.c:init_mi_error Unexecuted instantiation: mod_fix.c:init_mi_error Unexecuted instantiation: reactor.c:init_mi_error Unexecuted instantiation: forward.c:init_mi_error Unexecuted instantiation: xlog.c:init_mi_error Unexecuted instantiation: blacklists.c:init_mi_error Unexecuted instantiation: usr_avp.c:init_mi_error Unexecuted instantiation: resolve.c:init_mi_error Unexecuted instantiation: io_wait.c:init_mi_error Unexecuted instantiation: transformations.c:init_mi_error Unexecuted instantiation: sr_module_deps.c:init_mi_error Unexecuted instantiation: cfg_reload.c:init_mi_error Unexecuted instantiation: time_rec.c:init_mi_error Unexecuted instantiation: map.c:init_mi_error Unexecuted instantiation: status_report.c:init_mi_error Unexecuted instantiation: signals.c:init_mi_error Unexecuted instantiation: db_id.c:init_mi_error Unexecuted instantiation: csv.c:init_mi_error Unexecuted instantiation: cJSON.c:init_mi_error Unexecuted instantiation: evi_transport.c:init_mi_error Unexecuted instantiation: msg_translator.c:init_mi_error Unexecuted instantiation: md5utils.c:init_mi_error Unexecuted instantiation: cfg.tab.c:init_mi_error Unexecuted instantiation: modparam.c:init_mi_error Unexecuted instantiation: crc.c:init_mi_error Unexecuted instantiation: lex.yy.c:init_mi_error Unexecuted instantiation: cfg_pp.c:init_mi_error Unexecuted instantiation: proxy.c:init_mi_error Unexecuted instantiation: shutdown.c:init_mi_error Unexecuted instantiation: core_cmds.c:init_mi_error Unexecuted instantiation: cachedb.c:init_mi_error Unexecuted instantiation: cachedb_id.c:init_mi_error
111
112		/* Frees a MI Reponse
113		*/
114		void free_mi_response(mi_response_t *response);
115
116		/* Appends a new array to an existing array or to an object at the given name.
117		* When appending to an array, @name and @name_len are ignored.
118		*/
119		mi_item_t add_mi_array(mi_item_t to, char *name, int name_len);
120
121		/* Appends a new object to an array or to another object at the given name.
122		* When appending to an array, @name and @name_len are ignored.
123		*/
124		mi_item_t add_mi_object(mi_item_t to, char *name, int name_len);
125
126		/* Appends a string to an array or to an object at the given name.
127		* When appending to an array, @name and @name_len are ignored.
128		*/
129		int add_mi_string(mi_item_t to, char name, int name_len,
130		const char *value, int value_len);
131
132		/* Appends a formated string to an array or to an object at the given name.
133		* When appending to an array, @name and @name_len are ignored.
134		*/
135		int add_mi_string_fmt(mi_item_t to, char name, int name_len,
136		char *fmt_val, ...);
137
138		/* Appends a double (as a 'number' json type) to an array or to an object at
139		* the given name. When appending to an array, @name and @name_len are ignored.
140		*/
141		int add_mi_number(mi_item_t to, char name, int name_len, double value);
142
143		/* Appends a boolean to an array or to an object at the given name.
144		* When appending to an array, @name and @name_len are ignored.
145		*/
146		int add_mi_bool(mi_item_t to, char name, int name_len, int b);
147
148		/* Appends null to an array or to an object at the given name.
149		* When appending to an array, @name and @name_len are ignored.
150		*/
151		int add_mi_null(mi_item_t to, char name, int name_len);
152
153
154		/* Clones a MI Response to shm memory
155		*/
156		mi_response_t shm_clone_mi_response(mi_response_t src);
157
158		/* Frees a MI Reponse from shm memory
159		*/
160		void free_shm_mi_response(mi_response_t *response);
161
162		/* Clones a MI item to shm memory
163		*/
164		mi_item_t shm_clone_mi_item(mi_item_t src);
165
166		/* Frees a MI item from shm memory
167		*/
168		void free_shm_mi_item(mi_item_t *response);
169
170		/* The string provided in @value will be freed along with the MI request
171		* so it should be strdup'ed as necessary
172		*/
173		int get_mi_string_param(const mi_params_t params, char name,
174		char *value, int value_len);
175
176		int get_mi_bool_like_param(const mi_params_t params, char name,
177		int default_value);
178
179		int get_mi_int_param(const mi_params_t params, char name, int *value);
180
181		int get_mi_array_param(const mi_params_t params, char name,
182		mi_item_t *value, int no_items);
183
184		/* get the string item at the index @pos from an array parameter
185		* returned by get_mi_array_param()
186		*/
187		int get_mi_arr_param_string(const mi_item_t *array, int pos,
188		char *value, int value_len);
189
190		/* get the string item at the index @pos from an array parameter
191		* returned by get_mi_array_param()
192		*/
193		int get_mi_arr_param_int(const mi_item_t array, int pos, int value);
194
195		/* set of functions for trying to get a parameter, but do not fail if
196		* it cannot be found
197		*/
198		int try_get_mi_int_param(const mi_params_t params, char name,
199		int *value);
200		int try_get_mi_string_param(const mi_params_t params, char name,
201		char *value, int value_len);
202		int try_get_mi_array_param(const mi_params_t params, char name,
203		mi_item_t *value, int no_items);
204		int try_get_mi_arr_param_string(const mi_item_t *array, int pos,
205		char *value, int value_len);
206		int try_get_mi_arr_param_int(const mi_item_t array, int pos, int value);
207		int try_get_mi_arr_param_object(const mi_item_t *array, int pos,
208		mi_item_t **obj);
209		int get_mi_arr_param_object(const mi_item_t *array, int pos,
210		mi_item_t **obj);
211
212		/* Initializes a standard MI Response with details about the last
213		* parameter error produced by a parameter getter function
214		*/
215		mi_response_t *init_mi_param_error(void);
216
217		#endif