Pau Espin Pedrol | 54b614a | 2024-04-17 18:58:36 +0200 | [diff] [blame] | 1 | /* Asterisk's AMI interface functions in TTCN-3 |
| 2 | * (C) 2024 by sysmocom - s.f.m.c. GmbH <info@sysmocom.de> |
| 3 | * Author: Pau Espin Pedrol <pespin@sysmocom.de> |
| 4 | * All rights reserved. |
| 5 | * |
| 6 | * Released under the terms of GNU General Public License, Version 2 or |
| 7 | * (at your option) any later version. |
| 8 | * |
| 9 | * SPDX-License-Identifier: GPL-2.0-or-later |
| 10 | */ |
| 11 | |
| 12 | /* |
| 13 | * https://docs.asterisk.org/Configuration/Interfaces/Asterisk-Manager-Interface-AMI/AMI-v2-Specification/ |
| 14 | */ |
| 15 | module AMI_Functions { |
| 16 | |
| 17 | import from Misc_Helpers all; |
| 18 | import from TELNETasp_PortType all; |
| 19 | import from Osmocom_Types all; |
| 20 | import from TCCConversion_Functions all; |
| 21 | import from Socket_API_Definitions all; |
| 22 | |
| 23 | modulepar { |
| 24 | float mp_ami_prompt_timeout := 10.0; |
| 25 | } |
| 26 | |
| 27 | const charstring AMI_FIELD_ACTION := "Action"; |
| 28 | const charstring AMI_FIELD_USERNAME := "Username"; |
| 29 | const charstring AMI_FIELD_SECRET := "Secret"; |
| 30 | const charstring AMI_FIELD_RESPONSE := "Response"; |
| 31 | |
| 32 | type record AMI_Field { |
| 33 | charstring key, |
| 34 | charstring val |
Pau Espin Pedrol | de7a485 | 2024-04-19 16:20:45 +0200 | [diff] [blame^] | 35 | } with { |
| 36 | encode "TEXT" |
| 37 | variant "SEPARATOR(': ', ':\s+')" |
Pau Espin Pedrol | 54b614a | 2024-04-17 18:58:36 +0200 | [diff] [blame] | 38 | }; |
Pau Espin Pedrol | de7a485 | 2024-04-19 16:20:45 +0200 | [diff] [blame^] | 39 | |
| 40 | type set of AMI_Field AMI_Msg with { |
| 41 | encode "TEXT" |
| 42 | variant "SEPARATOR('\r\n', '(\r\n)|[\n]')" |
| 43 | variant "END('\r\n', '(\r\n)|[\n]')" |
| 44 | }; |
| 45 | |
| 46 | external function enc_AMI_Msg(in AMI_Msg msg) return charstring |
| 47 | with { extension "prototype(convert) encode(TEXT)" } |
| 48 | external function dec_AMI_Msg(in charstring stream) return AMI_Msg |
| 49 | with { extension "prototype(convert) decode(TEXT)" } |
Pau Espin Pedrol | 54b614a | 2024-04-17 18:58:36 +0200 | [diff] [blame] | 50 | |
| 51 | template (value) AMI_Field |
| 52 | ts_AMI_Field(template (value) charstring key, |
| 53 | template (value) charstring val) := { |
| 54 | key := key, |
| 55 | val := val |
| 56 | }; |
| 57 | |
| 58 | template (present) AMI_Field |
| 59 | tr_AMI_Field(template (present) charstring key := ?, |
| 60 | template (present) charstring val := ?) := { |
| 61 | key := key, |
| 62 | val := val |
| 63 | }; |
| 64 | |
| 65 | /* |
| 66 | * Field Templates: |
| 67 | */ |
| 68 | |
| 69 | template (value) AMI_Field |
| 70 | ts_AMI_Field_Action(template (value) charstring val) := ts_AMI_Field(AMI_FIELD_ACTION, val); |
| 71 | template (value) AMI_Field |
| 72 | ts_AMI_Field_Username(template (value) charstring val) := ts_AMI_Field(AMI_FIELD_USERNAME, val); |
| 73 | template (value) AMI_Field |
| 74 | ts_AMI_Field_Secret(template (value) charstring val) := ts_AMI_Field(AMI_FIELD_SECRET, val); |
| 75 | |
| 76 | template (present) AMI_Field |
| 77 | tr_AMI_Field_Action(template (present) charstring val := ?) := tr_AMI_Field(AMI_FIELD_ACTION, val); |
| 78 | template (present) AMI_Field |
| 79 | tr_AMI_Field_Username(template (present) charstring val := ?) := tr_AMI_Field(AMI_FIELD_USERNAME, val); |
| 80 | template (present) AMI_Field |
| 81 | tr_AMI_Field_Secret(template (present) charstring val := ?) := tr_AMI_Field(AMI_FIELD_SECRET, val); |
| 82 | template (present) AMI_Field |
| 83 | tr_AMI_Field_Response(template (present) charstring val := ?) := tr_AMI_Field(AMI_FIELD_RESPONSE, val); |
| 84 | |
| 85 | |
| 86 | template (present) AMI_Field |
| 87 | tr_AMI_Field_ResponseSuccess := tr_AMI_Field(AMI_FIELD_RESPONSE, "Success"); |
| 88 | |
| 89 | |
| 90 | /* |
| 91 | * Message Templates: |
| 92 | */ |
| 93 | |
| 94 | template (value) AMI_Msg |
| 95 | ts_AMI_Action_Login(charstring username, charstring secret) := { |
| 96 | ts_AMI_Field_Action("Login"), |
| 97 | ts_AMI_Field_Username(username), |
| 98 | ts_AMI_Field_Secret(secret) |
| 99 | }; |
| 100 | |
| 101 | template (present) AMI_Msg |
| 102 | tr_AMI_Action_Login(template(present) charstring username := ?, |
| 103 | template(present) charstring secret := ?) := superset( |
| 104 | tr_AMI_Field_Action("Login"), |
| 105 | tr_AMI_Field_Username(username), |
| 106 | tr_AMI_Field_Secret(secret) |
| 107 | ); |
| 108 | |
| 109 | template (present) AMI_Msg |
| 110 | tr_AMI_Response_Success := superset( |
| 111 | tr_AMI_Field_ResponseSuccess |
| 112 | ); |
| 113 | |
| 114 | /* |
| 115 | * Functions: |
| 116 | */ |
| 117 | |
Pau Espin Pedrol | 54b614a | 2024-04-17 18:58:36 +0200 | [diff] [blame] | 118 | private function f_ami_wait_for_prompt_str(TELNETasp_PT pt, charstring log_label := "(?)") |
| 119 | return charstring { |
| 120 | var charstring rx, buf := ""; |
| 121 | var integer fd; |
| 122 | timer T; |
| 123 | |
| 124 | T.start(mp_ami_prompt_timeout); |
| 125 | alt { |
Pau Espin Pedrol | de7a485 | 2024-04-19 16:20:45 +0200 | [diff] [blame^] | 126 | [] pt.receive(pattern "\n") { buf := buf & "\n" }; |
Pau Espin Pedrol | 54b614a | 2024-04-17 18:58:36 +0200 | [diff] [blame] | 127 | [] pt.receive(charstring:?) -> value rx { buf := buf & rx; repeat }; |
| 128 | [] pt.receive(integer:?) -> value fd { |
| 129 | if (fd == -1) { |
| 130 | Misc_Helpers.f_shutdown(__BFILE__, __LINE__, fail, |
| 131 | "AMI Telnet Connection Failure: " & log_label); |
| 132 | } else { |
| 133 | repeat; /* telnet connection succeeded */ |
| 134 | } |
| 135 | } |
| 136 | [] T.timeout { |
| 137 | Misc_Helpers.f_shutdown(__BFILE__, __LINE__, fail, |
| 138 | "AMI Timeout for prompt: " & log_label); |
| 139 | }; |
| 140 | } |
| 141 | T.stop; |
| 142 | return buf; |
| 143 | } |
| 144 | |
| 145 | function f_ami_wait_for_prompt(TELNETasp_PT pt, charstring log_label := "(?)") return AMI_Msg { |
| 146 | var charstring buf := f_ami_wait_for_prompt_str(pt, log_label); |
Pau Espin Pedrol | de7a485 | 2024-04-19 16:20:45 +0200 | [diff] [blame^] | 147 | var AMI_Msg msg := dec_AMI_Msg(buf); |
Pau Espin Pedrol | 54b614a | 2024-04-17 18:58:36 +0200 | [diff] [blame] | 148 | return msg; |
| 149 | } |
| 150 | |
| 151 | /* send a AMI command and obtain response until prompt is received */ |
| 152 | private function f_ami_transceive_ret_str(TELNETasp_PT pt, charstring tx) return charstring { |
| 153 | pt.send(tx); |
| 154 | return f_ami_wait_for_prompt_str(pt, tx); |
| 155 | } |
| 156 | |
| 157 | function f_ami_transceive_ret(TELNETasp_PT pt, template (value) AMI_Msg tx_msg) return AMI_Msg { |
Pau Espin Pedrol | de7a485 | 2024-04-19 16:20:45 +0200 | [diff] [blame^] | 158 | var charstring tx_txt := enc_AMI_Msg(valueof(tx_msg)); |
Pau Espin Pedrol | 54b614a | 2024-04-17 18:58:36 +0200 | [diff] [blame] | 159 | var charstring resp_txt := f_ami_transceive_ret_str(pt, tx_txt); |
Pau Espin Pedrol | de7a485 | 2024-04-19 16:20:45 +0200 | [diff] [blame^] | 160 | return dec_AMI_Msg(resp_txt); |
Pau Espin Pedrol | 54b614a | 2024-04-17 18:58:36 +0200 | [diff] [blame] | 161 | } |
| 162 | |
| 163 | function f_ami_transceive_match(TELNETasp_PT pt, |
| 164 | template (value) AMI_Msg tx_msg, |
| 165 | template (present) AMI_Msg exp_ret := ?) { |
| 166 | var AMI_Msg ret := f_ami_transceive_ret(pt, tx_msg); |
| 167 | if (not match(ret, exp_ret)) { |
| 168 | Misc_Helpers.f_shutdown(__BFILE__, __LINE__, fail, |
| 169 | log2str("Non-matching AMI response: ", ret, " vs exp: ", exp_ret)); |
| 170 | } |
| 171 | } |
| 172 | |
| 173 | function f_ami_transceive_match_response_success(TELNETasp_PT pt, |
| 174 | template (value) AMI_Msg tx_msg) { |
| 175 | f_ami_transceive_match(pt, tx_msg, tr_AMI_Response_Success); |
| 176 | } |
| 177 | |
| 178 | function f_ami_action_login(TELNETasp_PT pt, charstring username, charstring secret) { |
| 179 | f_ami_transceive_match_response_success(pt, ts_AMI_Action_Login(username, secret)); |
| 180 | } |
| 181 | |
| 182 | } |